doc

Documentation

Overview

Package doc opens a document without the caller knowing what it is.

d, err := doc.Open("file")
defer d.Close()

for i := range d.NumPages() {
	p, err := d.Page(i)
	img, err := p.ImageDPI(150)
}

It sniffs the contents and hands back the pdf, svg or html document behind one interface. What the three do not share - a PDF's optional content, a book's spine, a drawing's viewBox - is reached by type asserting Underlying.

A caller who knows the format should import that package instead: this one pulls all three in.

Index

• Variables
• func RegisterPictureDecoder(name, magic string, dec PictureDecoder)
• type Document
  • func Load(b []byte) (Document, error)
  • func NewReader(r io.ReaderAt, size int64) (Document, error)
  • func NewStream(r io.Reader) (Document, error)
  • func Open(name string) (Document, error)
• type Kind
  • func Detect(head []byte) Kind
  • func (k Kind) String() string
• type Link
• type Metadata
• type Page
• type PictureDecoder

Variables

var ErrUnsupported = errors.New("doc: unsupported document")

ErrUnsupported is a file none of the three packages reads.

Functions

func RegisterPictureDecoder

func RegisterPictureDecoder(name, magic string, dec PictureDecoder)

RegisterPictureDecoder installs a decoder for a picture format, for every kind of document: a picture in a book, a drawing, and a JPEG in a PDF.

The decoder must hand back the image's own color model. A JPEG forced to RGBA reaches a PDF that names DeviceCMYK or DeviceGray with the wrong number of components.

doc.RegisterPictureDecoder("jpeg", "\xff\xd8", func(b []byte) (image.Image, error) {
	return jpegn.Decode(bytes.NewReader(b), nil)
})

Types

type Document

type Document interface {
	// Kind is what the file turned out to be.
	Kind() Kind
	// Underlying is the *pdf.Document, *html.Document or *svg.Document.
	Underlying() any
	// NumPages is how many pages the document has. A book is laid out at its
	// default size the first time it is asked.
	NumPages() int
	// Page returns one page, counting from zero.
	Page(i int) (Page, error)
	// Metadata is the title and author the document gives.
	Metadata() Metadata
	// Close releases the document. It must not be called while a page renders.
	Close() error
}

Document is an open document of any of the three kinds.

func Load

func Load(b []byte) (Document, error)

Load reads a document from a buffer.

func NewReader

func NewReader(r io.ReaderAt, size int64) (Document, error)

NewReader reads a document of size bytes from r.

func NewStream

func NewStream(r io.Reader) (Document, error)

NewStream reads a document from a reader that cannot be seeked, buffering it.

func Open

func Open(name string) (Document, error)

Open reads the named file, deciding from its contents what it is.

type Kind

type Kind int

Kind is what a file turned out to be.

const (
	KindUnknown Kind = iota
	KindPDF
	KindSVG
	KindBook
)

The kinds a file may open as, and KindUnknown for one that is none of them.

func Detect

func Detect(head []byte) Kind

Detect reports what the head of a file says it is, and KindUnknown for none of the three. A kilobyte is enough of it.

func (Kind) String

func (k Kind) String() string

type Link

type Link struct {
	// Rect is the area the link covers, in the page's own space.
	Rect raster.Rect
	// URI is where a link out of the document points, and "" for one inside
	// it, which only the underlying document can resolve.
	URI string
}

Link is where a link on a page leads, as much as the three formats share.

type Metadata

type Metadata struct {
	Title    string
	Author   string
	Created  time.Time
	Modified time.Time
}

Metadata is what all three formats say about themselves. The rest is on the document Underlying returns.

type Page

type Page interface {
	// Bounds is the page in its own space, which ImageDPI renders one to one
	// at 72 for a PDF or a book and at 96 for a drawing.
	Bounds() raster.Rect
	// Image renders the page at its natural resolution.
	Image() (*image.RGBA, error)
	// ImageDPI renders it at the resolution asked for.
	ImageDPI(dpi float64) (*image.RGBA, error)
	// Text is what the page says.
	Text() (string, error)
	// StructuredText is the same with the box every character covers.
	StructuredText() (*gfx.TextPage, error)
	// Links is where the page leads.
	Links() []Link
	// SVG is the page as a drawing.
	SVG() (string, error)
	// HTML is the page as markup, laid out where it was drawn.
	HTML() (string, error)
	// Run draws the page through a device.
	Run(dev gfx.Device, ctm raster.Matrix) error
}

Page is one page of a document.

type PictureDecoder

type PictureDecoder = gfx.PictureDecoder

PictureDecoder reads one of the raster formats a document carries a picture in.