Struct epub_builder::EpubBuilder

source · [−]

pub struct EpubBuilder<Z: Zip> { /* private fields */ }

Expand description

Epub Builder

The main struct you’ll need to use in this library. It is first created using a wrapper to zip files; then you add content to it, and finally you generate the EPUB file by calling the generate method.

use epub_builder::EpubBuilder;
use epub_builder::ZipCommand;
use std::io;

// "Empty" EPUB file
let mut builder = EpubBuilder::new(ZipCommand::new().unwrap()).unwrap();
builder.metadata("title", "Empty EPUB").unwrap();
builder.metadata("author", "Ann 'Onymous").unwrap();
builder.generate(&mut io::stdout()).unwrap();

Implementations

source

impl<Z: Zip> EpubBuilder<Z>

source

pub fn new(zip: Z) -> Result<EpubBuilder<Z>>

Create a new default EPUB Builder

source

pub fn epub_version(&mut self, version: EpubVersion) -> &mut Self

Set EPUB version (default: V20)

Supported versions are:

V20: EPUB 2.0.1
’V30`: EPUB 3.0.1

source

pub fn metadata<S1, S2>(&mut self, key: S1, value: S2) -> Result<&mut Self> where
S1: AsRef<str>,
S2: Into<String>,

Set some EPUB metadata

For most metadata, this function will replace the existing metadata, but for subject, cteator and identifier who can have multiple values, it will add data to the existing data, unless the empty string “” is passed, in which case it will delete existing data for this key.

Valid keys used by the EPUB builder

author: author(s) of the book;
title: title of the book;
lang: the language ot the book, quite important as EPUB renderers rely on it for e.g. hyphenating words.
generator: generator of the book (should be your program name);
toc_name: the name to use for table of contents (by default, “Table of Contents”);
subject;
description;
license.

source

pub fn stylesheet<R: Read>(&mut self, content: R) -> Result<&mut Self>

Sets stylesheet of the EPUB.

This content will be written in a stylesheet.css file; it is used by some pages (such as nav.xhtml), you don’t have use it in your documents though it makes sense to also do so.

source

pub fn inline_toc(&mut self) -> &mut Self

Adds an inline toc in the document.

If this method is called it adds a page that contains the table of contents that appears in the document.

The position where this table of contents will be inserted depends on when you call this method: if you call it before adding any content, it will be at the beginning, if you call it after, it will be at the end.

source

pub fn add_resource<R, P, S>(
 &mut self,
 path: P,
 content: R,
 mime_type: S
) -> Result<&mut Self> where
 R: Read,
 P: AsRef<Path>,
 S: Into<String>,

Add a resource to the EPUB file

This resource can be a picture, a font, some CSS file, …. Unlike add_content, files added this way won’t appear in the linear document.

Note that these files will automatically be inserted into an OEBPS directory, so you don’t need (and shouldn’t) prefix your path with OEBPS/.

Arguments

path: the path where this file will be writen in the EPUB OEBPS structure, e.g. data/image_0.png
content: the resource to include
mime_type: the mime type of this file, e.g. “image/png”.

source

pub fn add_cover_image<R, P, S>(
 &mut self,
 path: P,
 content: R,
 mime_type: S
) -> Result<&mut Self> where
 R: Read,
 P: AsRef<Path>,
 S: Into<String>,

Add a cover image to the EPUB.

This works similarly to adding the image as a resource with the add_resource method, except, it signals it in the Manifest secton so it is displayed as the cover by Ereaders

source

pub fn add_content<R: Read>(
&mut self,
content: EpubContent<R>
) -> Result<&mut Self>

Add a XHTML content file that will be added to the EPUB.

Examples

let content = "Some content";
let mut builder = EpubBuilder::new(ZipLibrary::new().unwrap()).unwrap();
// Add a chapter that won't be added to the Table of Contents
builder.add_content(EpubContent::new("intro.xhtml", content.as_bytes())).unwrap();

// Sets the title of a chapter so it is added to the Table of contents
// Also add information about its structure
builder.add_content(EpubContent::new("chapter_1.xhtml", content.as_bytes())
                     .title("Chapter 1")
                     .child(TocElement::new("chapter_1.xhtml#1", "1.1"))).unwrap();

// Add a section, by setting the level to 2 (instead of the default value 1)
builder.add_content(EpubContent::new("section.xhtml", content.as_bytes())
                     .title("Section 1")
                     .level(2)).unwrap();

Note that these files will automatically be inserted into an OEBPS directory, so you don’t need (and shouldn’t) prefix your path with OEBPS/.

pub fn generate<W: Write>(&mut self, to: W) -> Result<()>

Generate the EPUB file and write it to the writer

Example

let mut builder = EpubBuilder::new(ZipLibrary::new().unwrap()).unwrap();
// Write the EPUB file into a Vec<u8>
let mut epub: Vec<u8> = vec!();
builder.generate(&mut epub).unwrap();