epub

package module
v0.0.0-...-4ea8d45 Latest Latest
Warning

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

 Go to latest Published: Aug 27, 2022 License: MIT Imports: 24 Imported by: 0

README

CI 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

Contributions

Contributions are welcome; please see CONTRIBUTING.md for more information.

Development

Clone this repository using Git. Run tests as documented below.

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"
	VideoFolderName = "videos"
)

Folder names used for resources inside the EPUB

Variables

This section is empty.

Functions

func Use 

func Use(s FSType)

Use s as default storage/ This is typically used in an init function. Default to local filesystem

Types

type Epub 

type Epub struct {
	sync.Mutex
	*http.Client
	// 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, a path to a local file, or an embedded data URL; in any 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 
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, a path to a local file, or an embedded data URL; in any 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 
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, a path to a local file, or an embedded data URL; in any 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 
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 
Output:

firstsection.xhtml
section0001.xhtml

func (*Epub) AddSubSection 

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

AddSubSection adds a nested section (chapter, etc) to an existing section. The method returns a relative path to the section that can be used from another section (for links).

The parent filename must be a valid filename from another section already added.

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 as a nested entry of the parent section in the table of contents. 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 
Output:

firstsection.xhtml
section0001.xhtml

func (*Epub) AddVideo 

func (e *Epub) AddVideo(source string, videoFilename string) (string, error)

AddVideo adds an video to the EPUB and returns a relative path to the video file that can be used in EPUB sections in the format: ../VideoFolderName/internalFilename

The video source should either be a URL, a path to a local file, or an embedded data URL; in any case, the video file will be retrieved and stored in the EPUB.

The internal filename will be used when storing the video file in the EPUB and must be unique among all video 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.

func (*Epub) Author 

func (e *Epub) Author() string

Author returns the author of the EPUB.

func (*Epub) Description 

func (e *Epub) Description() string

Description returns the description of the EPUB.

func (*Epub) Identifier 

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 

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 
Output:

func (*Epub) SetDescription 

func (e *Epub) SetDescription(desc string)

SetDescription sets the description of the EPUB.

func (*Epub) SetIdentifier 

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 
Output:

func (*Epub) SetLang 

func (e *Epub) SetLang(lang string)

SetLang sets the language of the EPUB.

func (*Epub) SetPpd 

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. The result is always writen to the local filesystem even if the underlying storage is in memory.

func (*Epub) WriteTo 

func (e *Epub) WriteTo(dst io.Writer) (int64, error)

WriteTo the dest io.Writer. The return value is the number of bytes written. Any error encountered during write is also returned.

type FSType 

type FSType int
const (
	// OsFS This defines the local filesystem
	OsFS FSType = iota
	// MemoryFS This defines the memory filesystem
	MemoryFS
)

type FileRetrievalError 

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 

func (e *FileRetrievalError) Error() string

type FilenameAlreadyUsedError 

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 

func (e *FilenameAlreadyUsedError) Error() string

type ParentDoesNotExistError 

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

ParentDoesNotExistError is thrown by AddSubSection if the parent with the previously defined internal filename does not exist.

func (*ParentDoesNotExistError) Error 

func (e *ParentDoesNotExistError) Error() string

type UnableToCreateEpubError 

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 

func (e *UnableToCreateEpubError) Error() string

Source Files

View all Source files

Directories

Path Synopsis
internal

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.