# BUPE
BUPE is an Elixir ePub generator and parser, it supports EPUB v2 and v3.
## Installation
First, add `bupe` to your list of dependencies in `mix.exs`:
```elixir
def deps do
[{:bupe, "~> MAJOR.MINOR"}]
end
```
To find out the latest release available on Hex, you can run `mix hex.info
bupe` in your shell, or by going to the
[`bupe` page on Hex.pm](https://hex.pm/packages/bupe)
Then, update your dependencies:
```sh-session
$ mix deps.get
```
## Usage
### Builder
If you want to create an EPUB file you can do the following:
```elixir
iex(1)> pages = "~/book/*.xhtml" |> Path.expand() |> Path.wildcard()
["/Users/dev/book/bacon.xhtml", "/Users/dev/book/egg.xhtml", "/Users/dev/book/ham.xhtml"]
iex(2)> config = %BUPE.Config{
...(2)> title: "Sample",
...(2)> language: "en",
...(2)> creator: "John Doe",
...(2)> publisher: "Sample",
...(2)> pages: pages
...(2)> }
%BUPE.Config{
audio: [],
contributor: nil,
cover: true,
coverage: nil,
creator: "John Doe",
date: nil,
description: nil,
fonts: [],
format: nil,
identifier: nil,
images: [],
language: "en",
logo: nil,
modified: nil,
nav: [],
pages: ["/Users/dev/book/bacon.xhtml",
"/Users/dev/book/egg.xhtml",
"/Users/dev/book/ham.xhtml"],
publisher: "Sample",
relation: nil,
rights: nil,
scripts: [],
source: nil,
styles: [],
subject: nil,
title: "Sample",
type: nil,
unique_identifier: nil,
version: "3.0"
}
iex(3)> BUPE.build(config, "sample.epub")
{:ok, '/Users/dev/sample.epub'}
```
If you prefer, you can build the EPUB document in memory doing the following:
```elixir
iex(4)> BUPE.build(config, "sample.epub", [:memory])
{:ok,
{'/Users/dev/sample.epub',
<<80, 75, 3, 4, 20, 0, 0, 0, 0, 0, 61, 123, 119, 78, 111, 97, 171, 44, 20, 0,
0, 0, 20, 0, 0, 0, 8, 0, 0, 0, 109, 105, 109, 101, 116, 121, 112, 101, 97,
112, 112, 108, 105, 99, 97, 116, ...>>}}
```
If you want to have more control over the `pages` configuration, instead of
passing a list of string, you can provide a list of `%BUPE.Item{}` like this:
```elixir
iex(1)> pages = [%BUPE.Item{href: "/Users/dev/book/bacon.xhtml", description: "Ode to Bacon"}]
[
%BUPE.Item{
description: "Ode to Bacon",
duration: nil,
fallback: nil,
href: "/Users/dev/book/bacon.xhtml",
id: nil,
media_overlay: nil,
media_type: nil,
properties: ""
}
]
```
The given `description` will be used in the _Table of Contents_ of EPUB
document, otherwise `BUPE` will provide a default description based on the file
name.
If your page include JavaScript, is recommended that you use the `properties`
field from `%BUPE.Item{}` like this:
```elixir
iex(2)> pages = [%BUPE.Item{href: "/Users/dev/book/bacon.xhtml", description: "Ode to Bacon", properties: "scripted"}]
[
%BUPE.Item{
description: "Ode to Bacon",
duration: nil,
fallback: nil,
href: "/Users/dev/book/bacon.xhtml",
id: nil,
media_overlay: nil,
media_type: nil,
properties: "scripted"
}
]
```
Keep in mind that if you put the `scripted` property on a page that does not
have any JavaScript, you will get warnings from validation tools such as
[EPUBCheck][epubcheck].
See `BUPE.Builder`, `BUPE.Config`, and `BUPE.Item` for more details.
### Parser
If you want to parse an EPUB file you can do the following:
```elixir
iex> BUPE.parse("sample.epub")
%BUPE.Config{
audio: nil,
contributor: nil,
cover: true,
coverage: nil,
creator: "John Doe",
date: nil,
description: nil,
fonts: nil,
format: nil,
identifier: "urn:uuid:bc864bda-1a0b-4014-a72f-30f6dc60e120",
images: nil,
language: "en",
logo: nil,
modified: "2019-03-23T20:22:20Z",
nav: [
%{idref: 'cover', linear: 'no'},
%{idref: 'nav'},
%{idref: 'pages-ecbedca7-f77e-46b6-8fe2-99718d00c903'},
%{idref: 'pages-59ad8356-e46d-4328-b7cc-e81af2880c3a'},
%{idref: 'pages-1d3ee5e3-cf45-4e45-bd79-8a931e293584'}
],
pages: [
%{
href: 'nav.xhtml',
id: 'nav',
"media-type": 'application/xhtml+xml',
properties: 'nav'
},
%{href: 'title.xhtml', id: 'cover', "media-type": 'application/xhtml+xml'},
%{
href: 'content/bacon.xhtml',
id: 'pages-ecbedca7-f77e-46b6-8fe2-99718d00c903',
"media-type": 'application/xhtml+xml',
properties: 'scripted'
},
%{
href: 'content/egg.xhtml',
id: 'pages-59ad8356-e46d-4328-b7cc-e81af2880c3a',
"media-type": 'application/xhtml+xml',
properties: 'scripted'
},
%{
href: 'content/ham.xhtml',
id: 'pages-1d3ee5e3-cf45-4e45-bd79-8a931e293584',
"media-type": 'application/xhtml+xml',
properties: 'scripted'
}
],
publisher: "Sample",
relation: nil,
rights: nil,
scripts: nil,
source: nil,
styles: [%{href: 'css/stylesheet.css', id: 'css', "media-type": 'text/css'}],
subject: nil,
title: "Sample",
type: nil,
unique_identifier: "BUPE",
version: "3.0"
}
```
See `BUPE.Parser` for more details.
## License
BUPE source code is released under Apache 2 License.
Check the [LICENSE](LICENSE) for more information.
[epubcheck]: https://github.com/w3c/epubcheck