BUPE (BUPE v0.6.5)

View Source

BUPE is an Elixir EPUB generator and parser with support for EPUB 2 and 3.

Installation

First, add :bupe to your list of dependencies in mix.exs:

def deps do
  [
    {:bupe, "~> 0.6"}
  ]
end

To check the latest release on Hex, run mix hex.info bupe or visit the bupe page on Hex.pm.

Then update your dependencies:

mix deps.get

Usage

Builder

To create an EPUB file:

pages = "~/book/*.xhtml" |> Path.expand() |> Path.wildcard()
config = BUPE.Config.new(%{
  title: "Sample",
  language: "en",
  creator: "John Doe",
  publisher: "Sample",
  pages: pages
})
BUPE.build(config, "sample.epub")
# {:ok, '/Users/dev/sample.epub'}

If you prefer, you can build the EPUB document in memory:

BUPE.build(config, "sample.epub", [:memory])

For more control over pages, you can provide a list of BUPE.Item structs instead of a list of strings:

pages = [
  %BUPE.Item{
    href: "/Users/dev/book/bacon.xhtml",
    description: "Ode to Bacon"
  }
]

The description is used in the EPUB Table of Contents; if you omit it, BUPE derives a default description from the file name.

If a page includes JavaScript, use the properties field in BUPE.Item:

pages = [
  %BUPE.Item{
    href: "/Users/dev/book/bacon.xhtml",
    description: "Ode to Bacon",
    properties: "scripted"
  }
]

Keep in mind that if you add the scripted property to a page without JavaScript, you will see warnings from validation tools such as EPUBCheck.

See BUPE.build/3, BUPE.Config, and BUPE.Item for details.

Using the builder via command line

You can build EPUB documents from the command line as follows:

  1. Install BUPE as an escript:
mix escript.install hex bupe
  1. Then use it in your projects:
bupe "EPUB_TITLE" -p egg.xhtml -p bacon.xhtml -l path/to/logo.png

For more details on the command-line tool, review the usage guide:

bupe --help

Parser

To parse an EPUB file:

BUPE.parse("Elixir.epub")

See BUPE.parse/1 for details.

Summary

Functions

build(config, output, options \\ [])

Builds an EPUB file from a BUPE.Config struct.

parse(epub_file)

Parses an EPUB file into BUPE data structures.

version()

Returns the BUPE version used in templates and CLI output.

Functions

build(config, output, options \\ [])

Builds an EPUB file from a BUPE.Config struct.

Options

  • :memory - Instead of writing a file, returns {file_name, binary()} where the binary is a full ZIP archive (suitable for :zip.unzip/2).

Example

iex(1)> files = Enum.map(~w(bacon.xhtml egg.xhtml ham.xhtml), &Path.join("/Users/dev/book", &1))
["/Users/dev/book/bacon.xhtml", "/Users/dev/book/egg.xhtml", "/Users/dev/book/ham.xhtml"]
iex(2)> get_id = &Path.basename(&1, ".xhtml")
iex(3)> pages = Enum.map(files, fn file ->
...(3)>   %BUPE.Item{href: file, id: get_id.(file), description: file |> get_id.() |> String.capitalize()}
...(3)> end)
iex(4)> config = %{
...(4)>  title: "Sample",
...(4)>  language: "en",
...(4)>  creator: "John Doe",
...(4)>  publisher: "Sample",
...(4)>  date: "2016-06-23T06:00:00Z",
...(4)>  unique_identifier: "EXAMPLE",
...(4)>  identifier: "http://example.com/book/jdoe/1",
...(4)>  pages: pages
...(4)> }
iex(5)> BUPE.Config.new(config)

Once you have the %Bupe.Config{} struct ready, you can execute BUPE.build/3, e.g., BUPE.build(config, "example.epub")

parse(epub_file)

Parses an EPUB file into BUPE data structures.

The parser conforms to EPUB 3 and aims to be compatible with EPUB 2.

Example

BUPE.parse("sample.epub")

version()

@spec version() :: String.t()

Returns the BUPE version used in templates and CLI output.