pdf

package module
v2.1.2 Latest Latest
Warning

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

Go to latest
Published: Nov 8, 2025 License: BSD-3-Clause Imports: 17 Imported by: 0

README

Steve’s PDF Library

This repository contains code for reading and writing PDF files, as needed for various other projects of mine.

The top package is the library used by other programs. The sub-packages are mostly utility commands based on that library. Specifically:

  • pdfdump is a program that dumps the entire structure of a PDF file in a human-readable form.
  • pdfinspect is a program that dumps individual objects from the PDF file in a human-readable form.

There is also a directory _pdfform, with code for a deprecated package that knows how to read and write fillable forms in PDF files. It's out of date and no longer used, but saved in case I need it someday.

The sub-package pdftest is just a test program used during development of the library.

Documentation

Overview

Code generated by gen-metrics -- DO NOT EDIT.

Package pdf provides methods for reading, creating, and updating PDF files.

Index

Constants

This section is empty.

Variables

View Source
var ErrDoesntFit = errors.New("text does not fit in bounding box")

ErrDoesntFit is the error returned by Draw if the text doesn't fit in its Rectangle. The text was still drawn, either overflowing or clipped to the Rectangle depending on the Clip setting.

View Source
var ErrIllegalChar = errors.New("text contains invalid character")

ErrIllegalChar is the error returned by Draw if the text contains a character that cannot be rendered. The text was still drawn but the offending character(s) were omitted.

View Source
var ErrNoSuchPage = errors.New("no such page number")

ErrNoSuchPage indicates a reference to a page number that does not exist in the PDF.

View Source
var USLetterPortrait = Rectangle{0, 0, 612, 792}

USLetterPortrait is the most common mediaBox parameter to AddPage.

Functions

func ArrayPaths

func ArrayPaths(arrayPath Path, array Array) iter.Seq[Path]

ArrayPaths returns an iterator of paths to the elements of an array.

func DictPaths

func DictPaths(dictPath Path, dict Dict) iter.Seq[Path]

DictPaths returns an iterator of paths to the elements of a Dict (or Stream Dict).

func EncodeHexString

func EncodeHexString(by []byte) string

func EncodeName

func EncodeName(n Name) string

func EncodeString

func EncodeString(s string) string

func FontMetrics

func FontMetrics(font string, fontSize float64) (habove, hbelow float64)

FontMetrics returns the maximum height above the baseline and below the baseline at the specified font size. A 0,0 return indicates an unknown font.

func MeasureText

func MeasureText(s, font string, size float64) (width, habove, hbelow float64)

MeasureText returns the metrics of the specified string in the specified font at the specified size: specifically, the width, the height above the baseline, and the height below the baseline. The string must not contain control characters, and must be in UTF-8 encoding. Characters that are not recognized (i.e., not in Windows-1252 encoding) are ignored. The function returns zeros if the font is not known.

Types

type Array

type Array []Object

An Array is an array of objects.

func (Array) ToMatrix

func (a Array) ToMatrix() (m Matrix, err error)

type Box

type Box struct {
	// Rectangle gives the size and location of the box.  Required.
	Rectangle Rectangle
	// Page gives the page number to draw on.  Default is 1.
	Page int
	// Fill gives the fill color for the box, as an array of three or four
	// bytes (R, G, B, and maybe A).  Default is no fill.
	Fill []byte
	// Stroke gives the stroke color for the box, as an array of three or
	// four bytes (R, G, B, and maybe A).  Default is no stroke.
	Stroke []byte
	// StrokeWidth gives the stroke width for the box (meaningful only if
	// Stroke is specified).  Default is 1pt.
	StrokeWidth float64
}

Box is a structure containing all of the parameters for drawing a box. To draw a box, create a Box structure and call its Draw method.

func (Box) Draw

func (b Box) Draw(pdf *PDF) (err error)

type Cell

type Cell struct {
	// Row is the row number of the cell.  For cells that span rows,
	// it is the topmost row that the cell spans.  Rows are numbered from 0
	// starting at the top of the table.
	Row int
	// Col is the column number of the cell.  For cells that span columns,
	// it is the leftmost column that the cell spans.  Cells are numbered
	// from 0 starting at the left of the table.
	Col int
	// RowSpan is the number of rows the cell spans (default 1).
	RowSpan int
	// ColSpan is the number of columns the cell spans (default 1).
	ColSpan int
	// Fill is the background color of the cell, if any.
	Fill []byte
	// Text is the text to place in the cell.  Note that the Page,
	// Rectangle, MinFontSize, and Wrap will be overridden by Table.Draw.
	Text *Text
}

Cell is a structure defining the parameters for a single cell in a Table.

type Circle

type Circle struct {
	// Center gives the center point of the circle.  Required.
	Center Point
	// Radius gives the radius of the circle.  Required.
	Radius float64
	// Page gives the page number to draw on.  Default is 1.
	Page int
	// Fill gives the fill color for the circle, as an array of three or
	// four bytes (R, G, B, and maybe A).  Default is no fill.
	Fill []byte
	// Stroke gives the stroke color for the circle, as an array of three or
	// four bytes (R, G, B, and maybe A).  Default is no stroke.
	Stroke []byte
}

Circle is a structure containing all of the parameters for drawing a circle. To draw a circle, create a Circle structure and call its Draw method.

func (Circle) Draw

func (b Circle) Draw(pdf *PDF) (err error)

type Cross

type Cross struct {
	// Rectangle gives the size and location of the cross.  Required.
	Rectangle Rectangle
	// Page gives the page number to draw on.  Default is 1.
	Page int
	// LineWidth gives the line width.  Default is 1 point.
	LineWidth float64
	// Stroke gives the stroke color for the lines, as an array of three or
	// four bytes (R, G, B, and maybe A).  Default is black.
	Stroke []byte
}

Cross is a structure containing all of the parameters for drawing a cross (i.e., two perpendicular lines crossing a rectangular area). To draw a cross, create a Cross structure and call its Draw method.

func (Cross) Draw

func (b Cross) Draw(pdf *PDF) (err error)

type Dict

type Dict map[Name]Object

A Dict is a map from Name to Object.

type Importer added in v2.1.2

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

func (*Importer) ImportPage added in v2.1.2

func (imp *Importer) ImportPage(srcPageNum, destPageNum int) (err error)

type Line

type Line struct {
	// P1 and P2 give the endpoints of the line.  Required.
	P1, P2 Point
	// Page gives the page number to draw on.  Default is 1.
	Page int
	// Stroke gives the stroke color for the line, as an array of three or
	// four bytes (R, G, B, and maybe A).  Default is solid black.
	Stroke []byte
	// Width gives the line width.  Default is 1pt.
	Width float64
}

Line is a structure containing all of the parameters for drawing a line. To draw a line, create a Line structure and call its Draw method.

func (Line) Draw

func (b Line) Draw(pdf *PDF) (err error)

type Matrix

type Matrix struct{ A, B, C, D, E, F float64 }

A Matrix specifies a coordinate transformation matrix. Following PDF standard, the matrix

┌a b 0┐
│c d 0│
└e f 1┘

is represented as the array [a b c d e f].

func (Matrix) Multiply

func (m Matrix) Multiply(o Matrix) (p Matrix)

func (Matrix) PreMultiply

func (m Matrix) PreMultiply(o Matrix) Matrix

func (Matrix) ToArray

func (m Matrix) ToArray() Array

func (Matrix) Transform

func (m Matrix) Transform(p Point) (t Point)

type Name

type Name string

A Name is a PDF/Postscript name, without the leading slash.

type Object

type Object any

An Object is an object as defined by the PDF specification. While an Object is defined as "any", it will in fact be one of the following:

  • nil (a null object)
  • bool
  • int
  • float64
  • string
  • []byte (a hex string)
  • Name
  • Array
  • Dict
  • Stream
  • Reference

type PDF

type PDF struct {
	Info    Dict
	Catalog Dict
	Trailer Dict
	// contains filtered or unexported fields
}

A PDF is a reference to a PDF file.

func New

func New(wh io.WriteSeeker) (pdf *PDF)

New creates a new PDF file. After objects are added to it, Write must be called on it.

func Open

func Open(fh Reader) (p *PDF, err error)

Open opens an existing PDF file.

func (*PDF) AddPage

func (pdf *PDF) AddPage(mediaBox Rectangle) (err error)

AddPage adds a page to the PDF, with the specified dimensions.

func (*PDF) AddPageContent

func (pdf *PDF) AddPageContent(pagenum int, content string) (err error)

AddPageContent adds content to the specified page.

func (*PDF) AddPageResource

func (pdf *PDF) AddPageResource(pagenum int, resType, resName Name, resource Object) (err error)

AddPageResource adds a resource to a page.

func (*PDF) Append

func (pdf *PDF) Append(p Path, value Object) (err error)

Append appends the specified value to the Array at the specified path. It marks the nearest ancestor object as dirty.

func (*PDF) CreateObject

func (p *PDF) CreateObject(obj Object) (ref Reference)

CreateObject creates a new object with the specified content, and returns a reference to it. The new content will be written if Write is called.

func (*PDF) Fetch

func (p *PDF) Fetch(r Reference) (obj Object, err error)

Fetch returns the object specified by the reference.

func (*PDF) Get

func (pdf *PDF) Get(p Path) (object Object)

Get returns the object at the specified Path. If the file structure isn't consistent with the path, the object returned is an error.

func (*PDF) GetArray

func (pdf *PDF) GetArray(p Path) (v Array, err error)

GetArray is like Get but asserts that the result is an Array.

func (*PDF) GetBool

func (pdf *PDF) GetBool(p Path) (v bool, err error)

GetBool is like Get but asserts that the result is a boolean.

func (*PDF) GetDict

func (pdf *PDF) GetDict(p Path) (v Dict, err error)

GetDict is like Get but asserts that the result is a Dict.

func (*PDF) GetInt

func (pdf *PDF) GetInt(p Path) (v int, err error)

GetInt is like Get but asserts that the result is an int.

func (*PDF) GetName

func (pdf *PDF) GetName(p Path) (v Name, err error)

GetName is like Get but asserts that the result is a Name.

func (*PDF) GetReal

func (pdf *PDF) GetReal(p Path) (v float64, err error)

GetReal is like Get but asserts that the result is a float64 (or an int, which is converted to float64).

func (*PDF) GetRectangle

func (pdf *PDF) GetRectangle(p Path) (v Rectangle, err error)

GetRectangle is like Get but asserts that the result is a Rectangle (i.e., an Array of four numbers).

func (*PDF) GetReference

func (pdf *PDF) GetReference(p Path) (v Reference, err error)

GetReference is like Get but asserts that the result is a Reference.

func (*PDF) GetStream

func (pdf *PDF) GetStream(p Path) (v Stream, err error)

GetStream is like Get but asserts that the result is a Stream.

func (*PDF) GetString

func (pdf *PDF) GetString(p Path) (v string, err error)

GetString is like Get but asserts that the result is a string (or a []byte, which is converted to string).

func (*PDF) ImportPDF

func (pdf *PDF) ImportPDF(otherPDF *PDF) (err error)

ImportPDF imports all of the pages from the specified other PDF into the receiver PDF. The imported page content is overlaid onto the existing content of each corresponding page; new pages are added as needed.

func (*PDF) NewImporter added in v2.1.2

func (pdf *PDF) NewImporter(otherPDF *PDF) (imp *Importer, err error)

NewImporter creates a new Importer object, which can be used to import pages from another PDF into this one by calling its ImportPage method.

func (*PDF) NumPages

func (pdf *PDF) NumPages() (count int, err error)

NumPages returns the number of pages in the PDF.

func (*PDF) PagePath

func (pdf *PDF) PagePath(pagenum int) (p Path, err error)

PagePath returns the path to the page dictionary for the specified page number (starting from 1).

func (*PDF) Set

func (pdf *PDF) Set(p Path, value Object) (err error)

Set sets the value at the specified path to the specified value. It marks the nearest ancestor object as dirty.

func (*PDF) UpdateObject

func (p *PDF) UpdateObject(ref Reference, obj Object)

UpdateObject registers new content for the object with the specified reference. The new content will be written if Write is called.

func (*PDF) Write

func (p *PDF) Write() (err error)

Write updates the PDF in place to save the updated objects previously passed to UpdateObject. For this to work, the receiver must have been created by New, or by Open with a file handle that supports io.WriteSeeker. The caller needs to close the file when finished.

type Path

type Path string

A Path represents a path to an object in a PDF, navigating from the PDF's trailer dictionary. It looks like a file system path, with "/" representing the trailer dictionary and subsequent components of the path being either Dict keys, Stream.Dict keys, or Array indices. So, for example, /Root/Pages/Kids/0/Content might be the path to the content stream of the first page of the PDF. Indirect object references are not represented in the path.

func (Path) I

func (p Path) I(i int) Path

I adds an Array index to the path.

func (Path) K

func (p Path) K(n Name) Path

K adds a Dict or Stream.Dict key to the path.

type Point

type Point struct{ X, Y float64 }

A Point specifies a point.

func PointXY

func PointXY(x, y float64) Point

PointXY returns a Point.

type Reader

type Reader interface {
	io.Seeker
	io.ReaderAt
}

Reader is the interface that must be satisfied by any file passed to Open.

type Rectangle

type Rectangle struct{ LLX, LLY, URX, URY float64 }

A Rectangle specifies a rectangle, in terms of its lower left and upper right coordinates, in points.

func RectangleRT

func RectangleRT(x, y, r, t float64) Rectangle

RectangleRT returns a Rectangle specified with X, Y, Right, and Top.

func RectangleWH

func RectangleWH(x, y, w, h float64) Rectangle

RectangleWH returns a Rectangle specified with X, Y, Width, and Height.

type Reference

type Reference struct {
	Number     int
	Generation int
}

A Reference is an indirect reference to an Object.

type Stream

type Stream struct {
	Dict Dict
	Data []byte
}

A Stream is a Dict followed by a block of arbitrary data. Note that when retrieved from the pdfstruct library, stream data has been decompressed and decoded.

func (*Stream) Decompress

func (s *Stream) Decompress(rowsize int) error

Decompress removes any compression and/or encoding from the stream data. Some encoding methods need to know the size (in bytes) of a "row" in the data for decoding, so that is a parameter.

type Table

type Table struct {
	// Page is the page number onto which to draw the table.  Default 1.
	Page int
	// Rectangle is the page area into which to draw the table.  The table
	// is vertically aligned to the top of the rectangle and horizontally
	// centered in it.  After a call to Draw, Rectangle reflects the actual
	// rectangle used.
	Rectangle Rectangle
	// TableBorderWidth is the width of the border drawn around the table.
	TableBorderWidth float64
	// TableBorderStroke is the color of the border drawn around the table.
	TableBorderStroke []byte
	// CellPadX is the padding on the left and right side of each cell.
	CellPadX float64
	// CellPadY is the padding on the top and bottom of each cell.
	CellPadY float64
	// CellBorderWidth is the width of the border drawn around each cell of
	// the table.
	CellBorderWidth float64
	// CellBorderStroke is the color of the border drawn around each cell of
	// the table.
	CellBorderStroke []byte
	// Align specifies the alignment of the table within the Rectangle.  It
	// contains up to two letters:  "t", "m", or "b" to specify top, middle,
	// or bottom vertical alignment, and "l", "c", or "r" to specify left,
	// center, or right horizontal alignment.  The default is "tc".
	Align string
	// contains filtered or unexported fields
}

Table is a structure containing the parameters for drawing a table. To draw a table, create a Table structure, call its Cell method repeatedly for each cell in it, and then call its Draw method.

func (*Table) Cell

func (t *Table) Cell(cell *Cell)

Cell adds a cell to the table. Cells may be added in any order. Note that cells with rowSpan != 1 are ignored in row height calculations and cells with colSpan != 1 are ignored in column width calculations.

func (*Table) ColumnWidths

func (t *Table) ColumnWidths() []float64

ColumnWidths returns the column widths. These can be passed to SetColumnWidths of a different table to align layouts. Call this before calling Draw.

func (*Table) Draw

func (t *Table) Draw(pdf *PDF) (err error)

Draw draws a table. The table Rectangle is left encapsulating the space used by the table. If the table doesn't fit on the page, nothing is drawn and ErrDoesntFit is returned.

func (*Table) InsertRow added in v2.1.0

func (t *Table) InsertRow(row int)

InsertRow inserts an empty row at the specified row number. In other words, any existing Cells with a row number >= the specified number have their row number incremented.

func (*Table) SetColumnWidths

func (t *Table) SetColumnWidths(widths []float64)

SetColumnWidths sets the column widths. Call this before calling Cell.

func (*Table) Size added in v2.0.2

func (t *Table) Size() (width, height float64)

Size returns the computed size of the table. It must be called before Draw. (To get the saze of the table after Draw, look at its Rectangle.)

type Text

type Text struct {
	// String is the string to be drawn.  Required.  The string should be
	// encoded in UTF-8 as normal; however, only characters in the Windows
	// 1252 character set (a superset of ISO 8859-1) will actually be
	// rendered.
	String string
	// Rectangle is the page area into which to draw the string.  Required.
	Rectangle Rectangle
	// Page is the page number onto which to draw the string.  Default 1.
	Page int
	// Baseline, if nonzero, is the Y-coordinate of the baseline for the
	// first line of text.  This overrides any alignment specified in Align
	// or VAlign.
	Baseline float64
	// Font is the name of font in which the string should be drawn.  It
	// must be either "Courier", "Helvetica", or "Times-Roman".  Default is
	// "Helvetica".
	Font string
	// FontSize is the starting and maximum size of the font with which the
	// string should be drawn.  Default 12.0.
	FontSize float64
	// MinFontSize is the minimum size of the font with which the string
	// should be drawn.  Defaults to FontSize.  If less than FontSize, text
	// will be shrunk to fit within the Rectangle, but no smaller than
	// MinFontSize.
	MinFontSize float64
	// LineHeight is the distance between lines in a multi-line text block
	// (either String contains newlines or Wrap is enabled and String gets
	// wrapped).  Specified as a multiple of the font size, default 1.0.
	LineHeight float64
	// Color is the color in which the text should be drawn, as a slice of
	// three byte values, one each for red, green, and blue.  Default is
	// black (i.e., 0, 0, 0).
	Color []byte
	// Align specifies the alignment of the text within the rectangle.  It
	// contains up to two letters, one specifying the vertical alignment and
	// the other specifying the horizontal alignment.  The order of the two
	// does not matter.
	//
	// The vertical alignment characters are T, M, F, B, t, m, f, and b.
	// These stand for top, middle, first-middle, and bottom respectively.
	// The lowercase versions align based on the actual text (i.e., what
	// ascenders and descenders are actually used); the uppercase versions
	// align based on the font bounding box (i.e., assuming full ascenders
	// and descenders even if the text being rendered doesn't use them).
	// M/m differs from F/f only for multi-line text:  M/m centers the whole
	// block and F/f centers the first line.  If no vertical alignment
	// character is specified, the default is F.  Note that an nonzero value
	// of Baseline overrides any vertical alignment character.
	//
	// The horizontal alignment characters are l, c, and r, for left,
	// center, and right.  If no horizontal alignment character is
	// specified, the default is l.
	Align string
	// HAlign indicates how the text should be aligned horizontally.
	// Allowed values are "left" (the default), "center", and "right".
	// Deprecated:  use Align instead.
	HAlign string
	// VAlign indicates how the text hsould be aligned vertically.  Allowed
	// values are "top", "center", "bottom", and "baseline" (the default).
	// "baseline" means to arrange for the baseline of the first line of
	// text to be at Baseline, shifting that up as needed to make the text
	// fit in Rectangle.  Deprecated: use Align instead.
	VAlign string
	// Wrap indicates that text should be wrapped to fit in the Rectangle.
	Wrap bool
	// Clip indicates that text should be clipped to the Rectangle.  If
	// false, text that doesn't fit in the Rectangle is allowed to extend
	// past its boundaries.
	Clip bool
	// contains filtered or unexported fields
}

Text is a structure containing all of the parameters for drawing a text string. To draw a text string, create a Text structure and call its Draw method.

func (Text) Draw

func (t Text) Draw(pdf *PDF) (err error)

Draw draws the text into the specified PDF.

Directories

Path Synopsis
Package pdfform reads and writes the fillable form fields in a PDF.
Package pdfform reads and writes the fillable form fields in a PDF.
gen-metrics generates metrics.go from the files in github:Hopding/standard-fonts, which it assumes is checked out at ../standard-fonts.
gen-metrics generates metrics.go from the files in github:Hopding/standard-fonts, which it assumes is checked out at ../standard-fonts.
pdfinspect dumps one or more objects from a PDF file.
pdfinspect dumps one or more objects from a PDF file.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL