# `BUPE`
[🔗](https://github.com/milmazz/bupe/blob/main/lib/bupe.ex#L1)

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

## Installation

BUPE requires Elixir ~> 1.17 and Erlang/OTP 27 or later.

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

```elixir
def deps do
  [
    {:bupe, "~> 0.8"}
  ]
end
```

To check the latest release on Hex, run `mix hex.info bupe` or visit the
[`bupe` page on Hex.pm](https://hex.pm/packages/bupe).

Then update your dependencies:

```console
mix deps.get
```

## Usage

### Builder

To create an [EPUB] file:

```elixir
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:

```elixir
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:

```elixir
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.

The `language` must be a valid [BCP 47][bcp47] language tag (e.g. `"en"`,
`"pt-BR"`); `BUPE.build/3` raises `BUPE.InvalidLanguage` when the tag is
invalid.

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

```elixir
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][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:

```console
mix escript.install hex bupe
```

2. Then use it in your projects:

```console
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:

```console
bupe --help
```

### Parser

To parse an EPUB file:

```elixir
BUPE.parse("Elixir.epub")
```

See `BUPE.parse/1` for details.

[bcp47]: https://www.rfc-editor.org/info/bcp47
[epub]: https://www.w3.org/publishing/epub3/
[epubcheck]: https://github.com/w3c/epubcheck

# `build`

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`

Parses an EPUB file into BUPE data structures.

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

## Example

    BUPE.parse("sample.epub")

[epub]: https://idpf.org/epub/301/spec/epub-overview.html

# `version`

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

Returns the BUPE version used in templates and CLI output.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
