core

package
v0.4.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 22, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package core implements the fundamental PDF object types defined in ISO 32000 §7.3 — Boolean, Number, String, Name, Array, Dictionary, Stream, and Null — plus indirect references (§7.3.10) and standard security handler encryption (§7.6).

Every object type satisfies the PdfObject interface, which provides WriteTo for serialization and Type for runtime type discrimination. Composite types (Array, Dictionary, Stream) preserve insertion order to produce deterministic output.

Encryption covers three standard security handler revisions:

  • RC4-128 (V=2, R=3): legacy, widely compatible
  • AES-128 (V=4, R=4): recommended minimum
  • AES-256 (V=5, R=6): strongest, PDF 2.0

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func EscapeLiteralString 

func EscapeLiteralString(s string) string

EscapeLiteralString escapes special characters inside a PDF literal string. Per ISO 32000 §7.3.4.2, the characters \, (, and ) must be escaped. Control characters (0x00–0x1F except \n, \r, \t) are escaped as octal.

Types

type DictEntry 

type DictEntry struct {
	Key   *PdfName
	Value PdfObject
}

DictEntry is a key-value pair in a PdfDictionary. We use a slice of entries rather than a map to preserve insertion order, which produces deterministic PDF output (important for testing and byte-level reproducibility).

type EncryptionRevision 

type EncryptionRevision int

EncryptionRevision identifies the encryption algorithm. 

const (
	RevisionRC4128 EncryptionRevision = 3 // RC4 128-bit (V=2, R=3)
	RevisionAES128 EncryptionRevision = 4 // AES-128-CBC (V=4, R=4)
	RevisionAES256 EncryptionRevision = 6 // AES-256-CBC (V=5, R=6)
)

type Encryptor 

type Encryptor struct {
	Revision EncryptionRevision
	FileKey  []byte // 16 bytes (RC4/AES-128) or 32 bytes (AES-256)
	O, U     []byte // owner/user hash (32 bytes for R3/R4, 48 bytes for R6)
	OE, UE   []byte // owner/user key encryption (32 bytes, R6 only)
	Perms    []byte // encrypted permissions (16 bytes, R6 only)
	P        int32  // permission flags
	FileID   []byte // 16-byte file identifier
	// contains filtered or unexported fields
}

Encryptor handles PDF object encryption for a single document.

func NewEncryptor 

func NewEncryptor(rev EncryptionRevision, userPassword, ownerPassword string, perms Permission) (*Encryptor, error)

NewEncryptor creates an Encryptor for the given revision and passwords. If ownerPassword is empty, it defaults to userPassword.

func (*Encryptor) BuildEncryptDict 

func (e *Encryptor) BuildEncryptDict() *PdfDictionary

BuildEncryptDict returns the /Encrypt dictionary for the trailer.

func (*Encryptor) EncryptBytes 

func (e *Encryptor) EncryptBytes(objNum, genNum int, data []byte) ([]byte, error)

EncryptBytes encrypts data for the given indirect object.

func (*Encryptor) EncryptObject 

func (e *Encryptor) EncryptObject(obj PdfObject, objNum, genNum int) error

EncryptObject walks a PdfObject tree and encrypts all strings and stream data in place. The /Encrypt dictionary object is skipped.

func (*Encryptor) SetEncryptDictObjNum 

func (e *Encryptor) SetEncryptDictObjNum(n int)

SetEncryptDictObjNum records the object number of the /Encrypt dictionary so it can be skipped during the encryption walk.

type ObjectType 

type ObjectType int

ObjectType enumerates the PDF object types. 

const (
	ObjectTypeBoolean    ObjectType = iota
	ObjectTypeNumber                // integer or real
	ObjectTypeString                // literal or hexadecimal
	ObjectTypeName                  // /Name
	ObjectTypeArray                 // [...]
	ObjectTypeDictionary            // << ... >>
	ObjectTypeStream                // dictionary + byte sequence
	ObjectTypeNull                  // null
	ObjectTypeReference             // indirect reference (e.g. 1 0 R)
)

type PdfArray 

type PdfArray struct {
	Elements []PdfObject
}

PdfArray represents a PDF array object (ISO 32000 §7.3.6). An array is a one-dimensional collection of objects.

func NewPdfArray 

func NewPdfArray(elements ...PdfObject) *PdfArray

NewPdfArray creates a new PdfArray containing the given elements.

func (*PdfArray) Add 

func (a *PdfArray) Add(obj PdfObject)

Add appends an object to the array. Panics if obj is nil.

func (*PdfArray) Len 

func (a *PdfArray) Len() int

Len returns the number of elements.

func (*PdfArray) Type 

func (a *PdfArray) Type() ObjectType

Type returns ObjectTypeArray.

func (*PdfArray) WriteTo 

func (a *PdfArray) WriteTo(w io.Writer) (int64, error)

WriteTo serializes the array in PDF syntax to w.

type PdfBoolean 

type PdfBoolean struct {
	Value bool
}

PdfBoolean represents a PDF boolean value (ISO 32000 §7.3.2).

func NewPdfBoolean 

func NewPdfBoolean(v bool) *PdfBoolean

NewPdfBoolean creates a new PdfBoolean with the given value.

func (*PdfBoolean) Type 

func (b *PdfBoolean) Type() ObjectType

Type returns ObjectTypeBoolean.

func (*PdfBoolean) WriteTo 

func (b *PdfBoolean) WriteTo(w io.Writer) (int64, error)

WriteTo serializes the boolean as "true" or "false" to w.

type PdfDictionary 

type PdfDictionary struct {
	Entries []DictEntry
}

PdfDictionary represents a PDF dictionary object (ISO 32000 §7.3.7). Keys are PdfName objects; values can be any PdfObject.

func NewPdfDictionary 

func NewPdfDictionary() *PdfDictionary

NewPdfDictionary creates a new empty PdfDictionary.

func (*PdfDictionary) Get 

func (d *PdfDictionary) Get(key string) PdfObject

Get retrieves a value by key name. Returns nil if not found.

func (*PdfDictionary) Remove 

func (d *PdfDictionary) Remove(key string)

Remove deletes an entry by key name. Does nothing if the key does not exist.

func (*PdfDictionary) Set 

func (d *PdfDictionary) Set(key string, value PdfObject)

Set adds or updates an entry. If the key already exists, its value is replaced. Panics if value is nil.

func (*PdfDictionary) Type 

func (d *PdfDictionary) Type() ObjectType

Type returns ObjectTypeDictionary.

func (*PdfDictionary) WriteTo 

func (d *PdfDictionary) WriteTo(w io.Writer) (int64, error)

WriteTo serializes the dictionary in PDF syntax to w.

type PdfIndirectReference 

type PdfIndirectReference struct {
	ObjectNumber     int
	GenerationNumber int
}

PdfIndirectReference represents a PDF indirect reference (ISO 32000 §7.3.10). Written as "objNum genNum R" (e.g., "1 0 R"). Generation numbers are almost always 0 in modern PDFs.

func NewPdfIndirectReference 

func NewPdfIndirectReference(objNum, genNum int) *PdfIndirectReference

NewPdfIndirectReference creates a new indirect reference with the given object and generation numbers.

func (*PdfIndirectReference) Type 

func (r *PdfIndirectReference) Type() ObjectType

Type returns ObjectTypeReference.

func (*PdfIndirectReference) WriteTo 

func (r *PdfIndirectReference) WriteTo(w io.Writer) (int64, error)

WriteTo serializes the indirect reference as "objNum genNum R" to w.

type PdfName 

type PdfName struct {
	Value string // the name without the leading /
}

PdfName represents a PDF name object (ISO 32000 §7.3.5). Names are written with a leading solidus: /Type, /Pages, etc.

func NewPdfName 

func NewPdfName(v string) *PdfName

NewPdfName creates a new PdfName with the given value (without the leading solidus).

func (*PdfName) Type 

func (n *PdfName) Type() ObjectType

Type returns ObjectTypeName.

func (*PdfName) WriteTo 

func (n *PdfName) WriteTo(w io.Writer) (int64, error)

WriteTo serializes the name with a leading solidus to w.

type PdfNull 

type PdfNull struct{}

PdfNull represents the PDF null object (ISO 32000 §7.3.9).

func NewPdfNull 

func NewPdfNull() *PdfNull

NewPdfNull creates a new PdfNull instance.

func (*PdfNull) Type 

func (n *PdfNull) Type() ObjectType

Type returns ObjectTypeNull.

func (*PdfNull) WriteTo 

func (n *PdfNull) WriteTo(w io.Writer) (int64, error)

WriteTo serializes the null object as "null" to w.

type PdfNumber 

type PdfNumber struct {
	// contains filtered or unexported fields
}

PdfNumber represents a PDF numeric object — either integer or real (ISO 32000 §7.3.3). It tracks whether the value is integral so that integers serialize without a decimal point.

func NewPdfInteger 

func NewPdfInteger(v int) *PdfNumber

NewPdfInteger creates an integer PdfNumber.

func NewPdfReal 

func NewPdfReal(v float64) *PdfNumber

NewPdfReal creates a real (floating-point) PdfNumber.

func (*PdfNumber) FloatValue 

func (n *PdfNumber) FloatValue() float64

FloatValue returns the float64 value.

func (*PdfNumber) IntValue 

func (n *PdfNumber) IntValue() int

IntValue returns the integer value. It truncates reals.

func (*PdfNumber) IsInteger 

func (n *PdfNumber) IsInteger() bool

IsInteger reports whether this number was created as an integer.

func (*PdfNumber) Type 

func (n *PdfNumber) Type() ObjectType

Type returns ObjectTypeNumber.

func (*PdfNumber) WriteTo 

func (n *PdfNumber) WriteTo(w io.Writer) (int64, error)

WriteTo serializes the number as an integer or real to w.

type PdfObject 

type PdfObject interface {
	// WriteTo serializes the object in PDF syntax to w.
	WriteTo(w io.Writer) (int64, error)

	// Type returns the object's PDF type.
	Type() ObjectType
}

PdfObject is the interface satisfied by every PDF object type.

type PdfStream 

type PdfStream struct {
	Dict *PdfDictionary
	Data []byte
	// contains filtered or unexported fields
}

PdfStream represents a PDF stream object (ISO 32000 §7.3.8). A stream consists of a dictionary followed by a sequence of bytes enclosed between "stream" and "endstream" keywords.

func NewPdfStream 

func NewPdfStream(data []byte) *PdfStream

NewPdfStream creates a stream with the given data (uncompressed). The /Length entry is managed automatically during serialization.

func NewPdfStreamCompressed 

func NewPdfStreamCompressed(data []byte) *PdfStream

NewPdfStreamCompressed creates a stream that will be compressed with FlateDecode (zlib) when written. The Data field holds the uncompressed bytes; compression happens during WriteTo.

func (*PdfStream) SetCompress 

func (s *PdfStream) SetCompress(enabled bool)

SetCompress enables or disables FlateDecode compression for this stream.

func (*PdfStream) Type 

func (s *PdfStream) Type() ObjectType

Type returns ObjectTypeStream.

func (*PdfStream) WriteTo 

func (s *PdfStream) WriteTo(w io.Writer) (int64, error)

WriteTo serializes the stream dictionary and data bytes to w.

type PdfString 

type PdfString struct {
	Value    string
	Encoding StringEncoding
}

PdfString represents a PDF string object (ISO 32000 §7.3.4). PDF supports two notations: literal strings in parentheses and hexadecimal strings in angle brackets.

func NewPdfHexString 

func NewPdfHexString(v string) *PdfString

NewPdfHexString creates a hexadecimal string: <hex>.

func NewPdfLiteralString 

func NewPdfLiteralString(v string) *PdfString

NewPdfLiteralString creates a literal string: (value).

func (*PdfString) Type 

func (s *PdfString) Type() ObjectType

Type returns ObjectTypeString.

func (*PdfString) WriteTo 

func (s *PdfString) WriteTo(w io.Writer) (int64, error)

WriteTo serializes the string in literal or hexadecimal notation to w.

type Permission 

type Permission uint32

Permission flags for PDF document encryption (ISO 32000 Table 22). Combine with | to grant multiple permissions. 

const (
	PermPrint         Permission = 1 << 2  // bit 3: print
	PermModify        Permission = 1 << 3  // bit 4: modify contents
	PermExtract       Permission = 1 << 4  // bit 5: copy/extract text and graphics
	PermAnnotate      Permission = 1 << 5  // bit 6: add/modify annotations, fill forms
	PermFillForms     Permission = 1 << 8  // bit 9: fill existing form fields
	PermExtractAccess Permission = 1 << 9  // bit 10: extract for accessibility
	PermAssemble      Permission = 1 << 10 // bit 11: assemble (insert, rotate, delete pages)
	PermPrintHigh     Permission = 1 << 11 // bit 12: high-quality print

	// PermAll grants all permissions.
	PermAll = PermPrint | PermModify | PermExtract | PermAnnotate |
		PermFillForms | PermExtractAccess | PermAssemble | PermPrintHigh
)

type StringEncoding 

type StringEncoding int

StringEncoding controls how a PdfString is serialized. 

const (
	StringLiteral     StringEncoding = iota // (Hello World)
	StringHexadecimal                       // <48656C6C6F>
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.