gopub

Documentation

Index

• Constants
• Variables
• type Container
  • func (c *Container) DefaultRendition() *Rootfile
• type Creator
• type Date
• type Guide
• type GuideReference
• type Identifier
• type Manifest
  • func (m *Manifest) Fonts() []*ManifestItem
  • func (m *Manifest) Images() []*ManifestItem
  • func (m *Manifest) Stylesheets() []*ManifestItem
• type ManifestItem
  • func (item *ManifestItem) Open() (io.ReadCloser, error)
• type MetaTag
• type Metadata
  • func (m *Metadata) MainTitle() Title
  • func (m *Metadata) PrimarySubject() string
• type NCX
• type NavDoc
• type NavItem
• type NavPoint
• type NavSection
• type Package
• type ReadCloser
  • func OpenReader(name string, opts ...ReaderOptions) (*ReadCloser, error)
  • func (rc *ReadCloser) Close() error
• type Reader
  • func NewReader(ra io.ReaderAt, size int64, opts ...ReaderOptions) (*Reader, error)
  • func (r *Reader) GetCover() (*ManifestItem, error)
• type ReaderOptions
• type Refinable
• type Rootfile
  • func (rf *Rootfile) ItemName(href string) string
  • func (rf *Rootfile) TOCNav() *NavSection
• type Spine
• type SpineItem
  • func (s *SpineItem) IsLinear() bool
• type Title

Constants

const (
	MediaTypeNCX      = "application/x-dtbncx+xml"
	MediaTypeOEBPS    = "application/oebps-package+xml"
	MediaTypeXHTML    = "application/xhtml+xml"
	MediaTypeHTML     = "text/html"
	MediaTypeCSS      = "text/css"
	MediaTypeSVG      = "image/svg+xml"
	MediaTypeJPEG     = "image/jpeg"
	MediaTypePNG      = "image/png"
	MediaTypeGIF      = "image/gif"
	MediaTypeWEBP     = "image/webp"
	MediaTypeAVIF     = "image/avif"
	MediaTypeOTF      = "font/otf"
	MediaTypeTTF      = "font/ttf"
	MediaTypeWOFF     = "font/woff"
	MediaTypeWOFF2    = "font/woff2"
	MediaTypeEOT      = "application/vnd.ms-fontobject"
	MediaTypeMP3      = "audio/mpeg"
	MediaTypeOGG      = "audio/ogg"
	MediaTypeMP4Audio = "audio/mp4"
	MediaTypeMP4Video = "video/mp4"
	MediaTypeWebM     = "video/webm"
	MediaTypeJS       = "application/javascript"
)

Media type constants for common EPUB content types.

Variables

var (
	ErrNoContainerfile  = errors.New("epub: no containerfile found")
	ErrBadContainerfile = errors.New("epub: bad containerfile")
	ErrNoRootfile       = errors.New("epub: no rootfile found in container")
	ErrBadRootfile      = errors.New("epub: container references non-existent rootfile")
	ErrNoItemref        = errors.New("epub: no itemrefs found in spine")
	ErrBadItemref       = errors.New("epub: itemref references non-existent item")
	ErrBadManifest      = errors.New("epub: manifest references non-existent item")
	ErrMissingCoverId   = errors.New("epub: missing cover id in metadata")
	ErrFileTooLarge     = errors.New("epub: file exceeds MaxFileSize limit")
	ErrDuplicateID      = errors.New("epub: duplicate manifest item id")
)

Types

type Container

type Container struct {
	Rootfiles []*Rootfile `xml:"rootfiles>rootfile"`
}

Container serves as a directory of Rootfiles.

func (*Container) DefaultRendition

func (c *Container) DefaultRendition() *Rootfile

DefaultRendition returns the first rootfile, or nil if none exist.

type Creator

type Creator struct {
	Refinable
	CreatorRole string `xml:"role,attr"`
	DisplaySeq  string `xml:"display-seq,attr"`
}

Creator represents a dc:creator or dc:contributor element.

type Date

type Date struct {
	Name string `xml:"event,attr"`
	Date string `xml:",chardata"`
}

Date holds an event date from dc:date.

type Guide

type Guide struct {
	References []GuideReference `xml:"reference"`
}

Guide lists EPUB 2.0 guide references (e.g. cover page, TOC).

type GuideReference

type GuideReference struct {
	Type  string `xml:"type,attr"`
	Title string `xml:"title,attr"`
	Href  string `xml:"href,attr"`
}

GuideReference is a typed link within the EPUB 2.0 guide element.

type Identifier

type Identifier struct {
	Scheme string `xml:"scheme,attr"`
	Value  string `xml:",chardata"`
}

Identifier represents a dc:identifier element with optional scheme.

type Manifest

type Manifest struct {
	Items []ManifestItem `xml:"manifest>item"`
}

Manifest lists every file that is part of the epub.

func (*Manifest) Fonts

func (m *Manifest) Fonts() []*ManifestItem

Fonts returns manifest items with font/* or common font application media types.

func (*Manifest) Images

func (m *Manifest) Images() []*ManifestItem

Images returns manifest items with image/* media types.

func (*Manifest) Stylesheets

func (m *Manifest) Stylesheets() []*ManifestItem

Stylesheets returns manifest items with media type text/css.

type ManifestItem

type ManifestItem struct {
	ID         string `xml:"id,attr"`
	HREF       string `xml:"href,attr"`
	MediaType  string `xml:"media-type,attr"`
	Properties string `xml:"properties,attr"`
	F          *zip.File
}

ManifestItem represents a file stored in the epub.

func (*ManifestItem) Open

func (item *ManifestItem) Open() (io.ReadCloser, error)

Open returns a ReadCloser that provides access to the item's contents.

type MetaTag

type MetaTag struct {
	Name     string `xml:"name,attr"`
	Content  string `xml:"content,attr"`
	Refines  string `xml:"refines,attr"`
	Property string `xml:"property,attr"`
	InnerXML string `xml:",chardata"`
}

MetaTag represents a <meta> element inside <metadata>.

type Metadata

type Metadata struct {
	Title       []Title      `xml:"title"`
	Language    string       `xml:"language"`
	Identifier  []Identifier `xml:"identifier"`
	Creator     []Creator    `xml:"creator"`
	Contributor []Creator    `xml:"contributor"`
	Publisher   Refinable    `xml:"publisher"`
	Subject     []string     `xml:"subject"`
	Description string       `xml:"description"`
	Event       []Date       `xml:"date"`
	Type        string       `xml:"type"`
	Format      string       `xml:"format"`
	Source      string       `xml:"source"`
	Relation    string       `xml:"relation"`
	Coverage    string       `xml:"coverage"`
	Rights      string       `xml:"rights"`
	// Meta holds raw <meta> tags; consumed by processRefinements, then cleared.
	Meta []MetaTag `xml:"meta"`
	// Post-processed fields (not from XML directly).
	OtherTags       map[string][]string `xml:"-"`
	CoverManifestId string              `xml:"-"`
	// might contain duplicates
	PrimaryWritingMode []string `xml:"-"`
	// Common EPUB 3.0 meta properties extracted from OtherTags.
	Modified    string `xml:"-"` // dcterms:modified
	Series      string `xml:"-"` // belongs-to-collection
	SeriesIndex string `xml:"-"` // group-position
}

Metadata contains publishing information about the epub.

func (*Metadata) MainTitle

func (m *Metadata) MainTitle() Title

MainTitle returns the primary title. Priority: TitleType=="main" → TitleType=="" → first. Returns zero Title if Metadata has no titles.

func (*Metadata) PrimarySubject

func (m *Metadata) PrimarySubject() string

PrimarySubject returns the first subject, or "" if none.

type NCX

type NCX struct {
	DocTitle  string     `xml:"docTitle>text"`
	NavPoints []NavPoint `xml:"navMap>navPoint"`
}

NCX represents an EPUB 2.0 compatible navigation document.

type NavDoc

type NavDoc struct {
	Navs []NavSection `xml:"body>nav"`
}

NavDoc represents an EPUB 3.0 compatible navigation document.

type NavItem

type NavItem struct {
	Link     navLink   `xml:"a"`
	SubItems []NavItem `xml:"ol>li"`
}

NavItem represents a navigable location within the epub.

type NavPoint

type NavPoint struct {
	ID        string `xml:"id,attr"`
	PlayOrder int    `xml:"playOrder,attr"`
	NavLabel  struct {
		Text string `xml:"text"`
	} `xml:"navLabel"`
	Content struct {
		Src string `xml:"src,attr"`
	} `xml:"content"`
	NavPoints []NavPoint `xml:"navPoint"`
}

NavPoint represents a location within the epub that can be navigated to.

type NavSection

type NavSection struct {
	Type  string    `xml:"type,attr"`
	Items []NavItem `xml:"ol>li"`
}

NavSection represents a single <nav> element (e.g. toc, landmarks). Type corresponds to the epub:type attribute (e.g. "toc", "landmarks", "page-list"). Go's xml package matches the local name "type" regardless of namespace prefix.

type Package

type Package struct {
	Version          string   `xml:"version,attr"`
	UniqueIdentifier string   `xml:"unique-identifier,attr"`
	Metadata         Metadata `xml:"metadata"`
	Manifest
	Spine Spine `xml:"spine"`
	Guide Guide `xml:"guide"`
}

Package represents an epub content.opf file.

type ReadCloser

type ReadCloser struct {
	Reader
	Size int64
	// contains filtered or unexported fields
}

ReadCloser represents a readable epub file that can be closed.

func OpenReader

func OpenReader(name string, opts ...ReaderOptions) (*ReadCloser, error)

OpenReader opens the epub file at name and returns a ReadCloser.

func (*ReadCloser) Close

func (rc *ReadCloser) Close() error

Close closes the epub file.

type Reader

type Reader struct {
	Container
	// contains filtered or unexported fields
}

Reader represents a readable epub file.

func NewReader

func NewReader(ra io.ReaderAt, size int64, opts ...ReaderOptions) (*Reader, error)

NewReader reads an epub from ra. The caller retains ownership of ra.

func (*Reader) GetCover

func (r *Reader) GetCover() (*ManifestItem, error)

GetCover returns the cover image manifest item, or an error if not found.

type ReaderOptions

type ReaderOptions struct {
	// MaxFileSize limits how many bytes are read from any single file inside
	// the EPUB ZIP. 0 means unlimited. Set this when processing untrusted
	// EPUBs to guard against ZIP-bomb / OOM attacks.
	MaxFileSize int64
}

ReaderOptions configures optional behaviour for Reader and ReadCloser. The zero value is valid and applies no restrictions.

type Refinable

type Refinable struct {
	Name   string `xml:",chardata"`
	ID     string `xml:"id,attr"`
	FileAs string `xml:"file-as,attr"`
}

Refinable is a metadata element that can carry file-as and id attributes.

type Rootfile

type Rootfile struct {
	FullPath string `xml:"full-path,attr"`
	Package
	NCX
	NavDoc
}

Rootfile contains the location of an epub .opf file.

func (*Rootfile) ItemName

func (rf *Rootfile) ItemName(href string) string

ItemName looks up a display name for the given item href. Tries EPUB 3.0 NavDoc first, falls back to EPUB 2.0 NCX.

func (*Rootfile) TOCNav

func (rf *Rootfile) TOCNav() *NavSection

TOCNav returns the NavSection with epub:type "toc", or nil if not found.

type Spine

type Spine struct {
	Itemrefs []SpineItem `xml:"itemref"`
	Toc      string      `xml:"toc,attr"`
	PPD      string      `xml:"page-progression-direction,attr"`
}

Spine defines the reading order of the epub documents.

type SpineItem

type SpineItem struct {
	IDREF           string `xml:"idref,attr"`
	Linear          string `xml:"linear,attr"`
	SpineProperties string `xml:"properties,attr"`
	SpineID         string `xml:"id,attr"`
	*ManifestItem   `xml:"-"`
}

SpineItem points to a ManifestItem.

func (*SpineItem) IsLinear

func (s *SpineItem) IsLinear() bool

IsLinear reports whether this spine item is part of the primary reading order. Items with linear="no" are supplementary (e.g. footnotes, back-matter).

type Title

type Title struct {
	Refinable
	TitleType string `xml:"title-type,attr"`
}

Title represents a dc:title element.