epub

package module
v0.6.0 Latest Latest
Warning

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

 Go to latest Published: Jun 11, 2021 License: MIT Imports: 14 Imported by: 50

README

Build Status Coverage Status Go Report Card License GoDoc

Features

  • Documented API
  • Creates valid EPUB 3.0 files
  • Adds an additional EPUB 2.0 table of contents (as seen here) for maximum compatibility
  • Includes support for adding CSS, images, and fonts

For an example of actual usage, see https://github.com/bmaupin/go-docs-epub

Installation

go get github.com/bmaupin/go-epub

Development

go get github.com/bmaupin/go-epub
cd $GOPATH/src/github.com/bmaupin/go-epub

Dependencies are managed using Go modules

Testing

EPUBCheck

EPUBCheck is a tool that will check an EPUB for validation errors.

If EPUBCheck is installed locally, it will be run alongside the Go tests. To install EPUBCheck:

  1. Make sure you have Java installed on your system

  2. Get the latest version of EPUBCheck from https://github.com/w3c/epubcheck/releases

  3. Download and extract EPUBCheck in the root directory of this project, e.g.

    wget https://github.com/IDPF/epubcheck/releases/download/v4.2.5/epubcheck-4.2.5.zip
unzip epubcheck-4.2.5.zip

If you do not wish to install EPUBCheck locally, you can manually validate the EPUB:

  1. Set doCleanup = false in epub_test.go

  2. Run the tests (see below)

  3. Upload the generated My EPUB.epub file to http://validator.idpf.org/

Run tests
go test

Documentation

Overview

Package epub generates valid EPUB 3.0 files with additional EPUB 2.0 table of contents (as seen here: https://github.com/bmaupin/epub-samples) for maximum compatibility.

Basic usage: 

// Create a new EPUB
e := epub.NewEpub("My title")

// Set the author
e.SetAuthor("Hingle McCringleberry")

// Add a section
section1Body := `<h1>Section 1</h1>
<p>This is a paragraph.</p>`
e.AddSection(section1Body, "Section 1", "", "")

// Write the EPUB
err = e.Write("My EPUB.epub")
if err != nil {
	// handle error
}

Index

Examples

Constants

View Source 
const (
	CSSFolderName   = "css"
	FontFolderName  = "fonts"
	ImageFolderName = "images"
)

Folder names used for resources inside the EPUB

Variables

This section is empty.

Functions

This section is empty.

Types

type Epub 

type Epub struct {
	sync.Mutex
	// contains filtered or unexported fields
}

Epub implements an EPUB file.

func NewEpub 

func NewEpub(title string) *Epub

NewEpub returns a new Epub.

func (*Epub) AddCSS 

func (e *Epub) AddCSS(source string, internalFilename string) (string, error)

AddCSS adds a CSS file to the EPUB and returns a relative path to the CSS file that can be used in EPUB sections in the format: ../CSSFolderName/internalFilename

The CSS source should either be a URL or a path to a local file; in either case, the CSS file will be retrieved and stored in the EPUB.

The internal filename will be used when storing the CSS file in the EPUB and must be unique among all CSS files. If the same filename is used more than once, FilenameAlreadyUsedError will be returned. The internal filename is optional; if no filename is provided, one will be generated.

Example 
e := epub.NewEpub("My title")

// Add CSS
css1Path, err := e.AddCSS("testdata/cover.css", "epub.css")
if err != nil {
	log.Fatal(err)
}

// The filename is optional
css2Path, err := e.AddCSS("testdata/cover.css", "")
if err != nil {
	log.Fatal(err)
}

// Use the CSS in a section
sectionBody := `    <h1>Section 1</h1>
	<p>This is a paragraph.</p>`
e.AddSection(sectionBody, "Section 1", "", css1Path)

fmt.Println(css1Path)
fmt.Println(css2Path)

Output:

../css/epub.css
../css/cover.css

func (*Epub) AddFont 

func (e *Epub) AddFont(source string, internalFilename string) (string, error)

AddFont adds a font file to the EPUB and returns a relative path to the font file that can be used in EPUB sections in the format: ../FontFolderName/internalFilename

The font source should either be a URL or a path to a local file; in either case, the font file will be retrieved and stored in the EPUB.

The internal filename will be used when storing the font file in the EPUB and must be unique among all font files. If the same filename is used more than once, FilenameAlreadyUsedError will be returned. The internal filename is optional; if no filename is provided, one will be generated.

Example 
e := epub.NewEpub("My title")

// Add a font from a local file
font1Path, err := e.AddFont("testdata/redacted-script-regular.ttf", "font.ttf")
if err != nil {
	log.Fatal(err)
}

// The filename is optional
font2Path, err := e.AddFont("testdata/redacted-script-regular.ttf", "")
if err != nil {
	log.Fatal(err)
}

fmt.Println(font1Path)
fmt.Println(font2Path)

Output:

../fonts/font.ttf
../fonts/redacted-script-regular.ttf

func (*Epub) AddImage 

func (e *Epub) AddImage(source string, imageFilename string) (string, error)

AddImage adds an image to the EPUB and returns a relative path to the image file that can be used in EPUB sections in the format: ../ImageFolderName/internalFilename

The image source should either be a URL or a path to a local file; in either case, the image file will be retrieved and stored in the EPUB.

The internal filename will be used when storing the image file in the EPUB and must be unique among all image files. If the same filename is used more than once, FilenameAlreadyUsedError will be returned. The internal filename is optional; if no filename is provided, one will be generated.

Example 
e := epub.NewEpub("My title")

// Add an image from a local file
img1Path, err := e.AddImage("testdata/gophercolor16x16.png", "go-gopher.png")
if err != nil {
	log.Fatal(err)
}

// Add an image from a URL. The filename is optional
img2Path, err := e.AddImage("https://golang.org/doc/gopher/gophercolor16x16.png", "")
if err != nil {
	log.Fatal(err)
}

fmt.Println(img1Path)
fmt.Println(img2Path)

Output:

../images/go-gopher.png
../images/gophercolor16x16.png

func (*Epub) AddSection 

func (e *Epub) AddSection(body string, sectionTitle string, internalFilename string, internalCSSPath string) (string, error)

AddSection adds a new section (chapter, etc) to the EPUB and returns a relative path to the section that can be used from another section (for links).

The body must be valid XHTML that will go between the <body> tags of the section XHTML file. The content will not be validated.

The title will be used for the table of contents. The section will be shown in the table of contents in the same order it was added to the EPUB. The title is optional; if no title is provided, the section will not be added to the table of contents.

The internal filename will be used when storing the section file in the EPUB and must be unique among all section files. If the same filename is used more than once, FilenameAlreadyUsedError will be returned. The internal filename is optional; if no filename is provided, one will be generated.

The internal path to an already-added CSS file (as returned by AddCSS) to be used for the section is optional.

Example 
e := epub.NewEpub("My title")

// Add a section. The CSS path is optional
section1Body := `    <h1>Section 1</h1>
	<p>This is a paragraph.</p>`
section1Path, err := e.AddSection(section1Body, "Section 1", "firstsection.xhtml", "")
if err != nil {
	log.Fatal(err)
}

// Link to the first section
section2Body := fmt.Sprintf(`    <h1>Section 2</h1>
	<a href="%s">Link to section 1</a>`,
	section1Path)
// The title and filename are also optional
section2Path, err := e.AddSection(section2Body, "", "", "")
if err != nil {
	log.Fatal(err)
}

fmt.Println(section1Path)
fmt.Println(section2Path)

Output:

firstsection.xhtml
section0002.xhtml

func (*Epub) Author 

func (e *Epub) Author() string

Author returns the author of the EPUB.

func (*Epub) Description added in v0.5.1 

func (e *Epub) Description() string

Description returns the description of the EPUB.

func (*Epub) Identifier added in v0.2.0 

func (e *Epub) Identifier() string

Identifier returns the unique identifier of the EPUB.

func (*Epub) Lang 

func (e *Epub) Lang() string

Lang returns the language of the EPUB.

func (*Epub) Ppd added in v0.2.1 

func (e *Epub) Ppd() string

Ppd returns the page progression direction of the EPUB.

func (*Epub) SetAuthor 

func (e *Epub) SetAuthor(author string)

SetAuthor sets the author of the EPUB.

func (*Epub) SetCover 

func (e *Epub) SetCover(internalImagePath string, internalCSSPath string)

SetCover sets the cover page for the EPUB using the provided image source and optional CSS.

The internal path to an already-added image file (as returned by AddImage) is required.

The internal path to an already-added CSS file (as returned by AddCSS) to be used for the cover is optional. If the CSS path isn't provided, default CSS will be used.

Example 
e := epub.NewEpub("My title")

// Set the cover. The CSS file is optional
coverImagePath, _ := e.AddImage("testdata/gophercolor16x16.png", "cover.png")
e.SetCover(coverImagePath, "")

// Update the cover using custom CSS
coverCSSPath, _ := e.AddCSS("testdata/cover.css", "")
e.SetCover(coverImagePath, coverCSSPath)

Output:

func (*Epub) SetDescription added in v0.5.1 

func (e *Epub) SetDescription(desc string)

SetDescription sets the description of the EPUB.

func (*Epub) SetIdentifier added in v0.2.0 

func (e *Epub) SetIdentifier(identifier string)

SetIdentifier sets the unique identifier of the EPUB, such as a UUID, DOI, ISBN or ISSN. If no identifier is set, a UUID will be automatically generated.

Example 
e := epub.NewEpub("My title")

// Set the identifier to a UUID
e.SetIdentifier("urn:uuid:a1b0d67e-2e81-4df5-9e67-a64cbe366809")

// Set the identifier to an ISBN
e.SetIdentifier("urn:isbn:9780101010101")

Output:

func (*Epub) SetLang 

func (e *Epub) SetLang(lang string)

SetLang sets the language of the EPUB.

func (*Epub) SetPpd added in v0.2.1 

func (e *Epub) SetPpd(direction string)

SetPpd sets the page progression direction of the EPUB.

func (*Epub) SetTitle 

func (e *Epub) SetTitle(title string)

SetTitle sets the title of the EPUB.

func (*Epub) Title 

func (e *Epub) Title() string

Title returns the title of the EPUB.

func (*Epub) Write 

func (e *Epub) Write(destFilePath string) error

Write writes the EPUB file. The destination path must be the full path to the resulting file, including filename and extension.

type FileRetrievalError added in v0.4.0 

type FileRetrievalError struct {
	Source string // The source of the file whose retrieval failed
	Err    error  // The underlying error that was thrown
}

FileRetrievalError is thrown by AddCSS, AddFont, AddImage, or Write if there was a problem retrieving the source file that was provided.

func (*FileRetrievalError) Error added in v0.4.0 

func (e *FileRetrievalError) Error() string

type FilenameAlreadyUsedError added in v0.4.0 

type FilenameAlreadyUsedError struct {
	Filename string // Filename that caused the error
}

FilenameAlreadyUsedError is thrown by AddCSS, AddFont, AddImage, or AddSection if the same filename is used more than once.

func (*FilenameAlreadyUsedError) Error added in v0.4.0 

func (e *FilenameAlreadyUsedError) Error() string

type UnableToCreateEpubError added in v0.4.0 

type UnableToCreateEpubError struct {
	Path string // The path that was given to Write to create the EPUB
	Err  error  // The underlying error that was thrown
}

UnableToCreateEpubError is thrown by Write if it cannot create the destination EPUB file

func (*UnableToCreateEpubError) Error added in v0.4.0 

func (e *UnableToCreateEpubError) Error() string

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.