README
¶
PDF Parser for Go
A high-performance, lightweight PDF parsing library for Go, forked from rsc/pdf.
This library has been extensively refactored to support modern PDF standards and high-throughput production environments with a focus on memory efficiency and security.
Key Improvements
1. High-Performance Zero-Allocation AST
The internal Abstract Syntax Tree (AST) has been rewritten to use a rigid Object union struct instead of interface{}. This eliminates the overhead of interface boxing for every PDF object (integers, names, strings, etc.), leading to massive reductions in memory allocations and GC pressure.
2. Modern Security Support
Added comprehensive support for encrypted PDFs:
- AES-128 (v4): Full implementation of AES-CBC decryption for strings and streams.
- AES-256 (v5): Support for PDF 2.0 / Extension Level 3 security handlers, including SHA-256 based Key Derivation (KDK) and File Encryption Key (FEK) retrieval.
3. Stability & Error Handling
- Panic-Free Design: Removed legacy
paniccalls in favor of proper Go error propagation. - Safe Method Chaining: The
Valuestruct now carries error state, allowing safe nested calls likedoc.Trailer().Key("Root").Key("Pages").Count(). - Robustness: Improved recovery from malformed PDF structures and strict parsing errors.
4. Memory Efficiency
- Buffer Pooling: Implemented
sync.Poolfor parsing buffers. - Bulk Scanning: Optimized
lex.gowith specialized bulk scanners for Names, Keywords, and Strings, drastically reducing per-byte overhead.
Benchmarks
Throughput comparison against the original library (parsing standard documents):
| Metric | Upstream Library | This Version | Change |
|---|---|---|---|
| Parsing Speed | 79,526 ns/op | 66,925 ns/op | ~16% Faster |
| Allocations | 2,517 allocs/op | 97 allocs/op | 96% Reduction |
| Memory usage | 113,712 B/op | 87,226 B/op | 23% Lower |
Usage
import "github.com/digitorus/pdf"
r, err := pdf.NewReader(file, size)
if err != nil {
return err
}
// Fluent, error-safe access
root := r.Trailer().Key("Root")
if err := root.Err(); err != nil {
return err
}
Documentation
¶
Index ¶
- Variables
- func Interpret(strm Value, do func(stk *Stack, op string))
- type Content
- type Font
- type Kind
- type Object
- type Outline
- type Page
- type Point
- type Ptr
- type Reader
- type ReaderXrefInformation
- type Rect
- type Stack
- type Text
- type TextEncoding
- type TextHorizontal
- type TextVertical
- type Value
- func (v Value) Bool() bool
- func (v Value) Data() []byte
- func (v Value) Err() error
- func (v Value) Float64() float64
- func (v Value) GetPtr() Ptr
- func (v Value) Header() Value
- func (v Value) Index(i int) Value
- func (v Value) Int64() int64
- func (v Value) IsNull() bool
- func (v Value) Key(key string) Value
- func (v Value) Keys() []string
- func (v Value) Kind() Kind
- func (v Value) Len() int
- func (v Value) Name() string
- func (v Value) RawString() string
- func (v Value) Reader() io.ReadCloser
- func (v Value) String() string
- func (v Value) Text() string
Constants ¶
This section is empty.
Variables ¶
var ErrInvalidPassword = fmt.Errorf("encrypted PDF: invalid password")
Functions ¶
func Interpret ¶
Interpret interprets the content in a stream as a basic PostScript program, pushing values onto a stack and then calling the do function to execute operators. The do function may push or pop values from the stack as needed to implement op.
Interpret handles the operators "dict", "currentdict", "begin", "end", "def", and "pop" itself.
Interpret is not a full-blown PostScript interpreter. Its job is to handle the very limited PostScript found in certain supporting file formats embedded in PDF files, such as cmap files that describe the mapping from font code points to Unicode code points.
There is no support for executable blocks, among other limitations.
Types ¶
type Font ¶
type Font struct {
V Value
}
A Font represent a font in a PDF file. The methods interpret a Font dictionary stored in V.
func (Font) Encoder ¶
func (f Font) Encoder() TextEncoding
Encoder returns the encoding between font code point sequences and UTF-8.
type Object ¶ added in v0.2.0
type Object struct {
Kind Kind
BoolVal bool
Int64Val int64
Float64Val float64
NameVal string
StringVal string
KeywordVal string
ArrayVal []Object
DictVal map[string]Object
PtrVal objptr
StreamOffset int64 // For Stream, DictVal holds the header
}
Object represents a PDF object using a tagged union approach to avoid interface{} boxing.
type Outline ¶
An Outline is a tree describing the outline (also known as the table of contents) of a document.
type Page ¶
type Page struct {
V Value
}
A Page represent a single page in a PDF file. The methods interpret a Page dictionary stored in V.
func (Page) Content ¶
Content returns the page's content. It recovers from panics caused by malformed content streams and returns an empty Content in such cases for security and robustness.
type Ptr ¶ added in v0.2.0
type Ptr struct {
// contains filtered or unexported fields
}
Ptr represents a PDF Object Reference (Indirect Object) This is the public API struct.
type Reader ¶
type Reader struct {
XrefInformation ReaderXrefInformation
PDFVersion string
// contains filtered or unexported fields
}
A Reader is a single PDF file open for reading.
func NewReaderEncrypted ¶
NewReaderEncrypted opens a file for reading, using the data in f with the given total size. If the PDF is encrypted, NewReaderEncrypted calls pw repeatedly to obtain passwords to try. If pw returns the empty string, NewReaderEncrypted stops trying to decrypt the file and returns an error.
func (*Reader) Close ¶ added in v0.2.0
Close closes the Reader and the underlying file if it implements io.Closer.
func (*Reader) GetObject ¶ added in v0.2.0
GetObject reads and returns the object with the given ID. It resolves the object from the XRef table, using the cache if available.
func (*Reader) Outline ¶
Outline returns the document outline. The Outline returned is the root of the outline tree and typically has no Title itself. That is, the children of the returned root are the top-level entries in the outline.
type ReaderXrefInformation ¶ added in v0.1.2
type ReaderXrefInformation struct {
StartPos int64
EndPos int64
Length int64
PositionLength int64
PositionStartPos int64
PositionEndPos int64
ItemCount int64
Type string
IncludingTrailerEndPos int64
IncludingTrailerLength int64
}
func (*ReaderXrefInformation) PrintDebug ¶ added in v0.1.2
func (info *ReaderXrefInformation) PrintDebug()
type Stack ¶
type Stack struct {
// contains filtered or unexported fields
}
A Stack represents a stack of values.
type Text ¶
type Text struct {
Font string // the font used
FontSize float64 // the font size, in points (1/72 of an inch)
X float64 // the X coordinate, in points, increasing left to right
Y float64 // the Y coordinate, in points, increasing bottom to top
W float64 // the width of the text, in points
S string // the actual UTF-8 text
}
A Text represents a single piece of text drawn on a page.
type TextEncoding ¶
type TextEncoding interface {
// Decode returns the UTF-8 text corresponding to
// the sequence of code points in raw.
Decode(raw string) (text string)
}
A TextEncoding represents a mapping between font code points and UTF-8 text.
type TextHorizontal ¶
type TextHorizontal []Text
TextHorizontal implements sort.Interface for sorting a slice of Text values in horizontal order, left to right, and then top to bottom within a column.
func (TextHorizontal) Len ¶
func (x TextHorizontal) Len() int
func (TextHorizontal) Less ¶
func (x TextHorizontal) Less(i, j int) bool
func (TextHorizontal) Swap ¶
func (x TextHorizontal) Swap(i, j int)
type TextVertical ¶
type TextVertical []Text
TextVertical implements sort.Interface for sorting a slice of Text values in vertical order, top to bottom, and then left to right within a line.
func (TextVertical) Len ¶
func (x TextVertical) Len() int
func (TextVertical) Less ¶
func (x TextVertical) Less(i, j int) bool
func (TextVertical) Swap ¶
func (x TextVertical) Swap(i, j int)
type Value ¶
type Value struct {
// contains filtered or unexported fields
}
A Value represents a value in a PDF file.
func (Value) Reader ¶
func (v Value) Reader() io.ReadCloser
Reader returns a reader for the stream v.
Source Files
Directories