Struct epub_builder::EpubBuilder

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

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

impl<Z: Zip> EpubBuilder<Z>

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

Create a new default EPUB Builder

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

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 of 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.

pub fn set_authors(&mut self, value: Vec<String>)

Sets the authors of the EPUB

pub fn add_author<S: Into<String>>(&mut self, value: S)

Add an author to the EPUB

pub fn clear_authors<S: Into<String>>(&mut self)

Remove all authors from EPUB

pub fn set_title<S: Into<String>>(&mut self, value: S)

Sets the title of the EPUB

pub fn escape_html(&mut self, val: bool)

Tells whether fields should be HTML-escaped.

• true: fields such as titles, description, and so on will be HTML-escaped everywhere (default)
• false: fields will be left as is (letting you in charge of making sure they do not contain anything illegal, e.g. < and > characters)

pub fn set_lang<S: Into<String>>(&mut self, value: S)

Sets the language of the EPUB

This is quite important as EPUB renderers rely on it for e.g. hyphenating words.

pub fn set_generator<S: Into<String>>(&mut self, value: S)

Sets the generator of the book (should be your program name)

pub fn set_toc_name<S: Into<String>>(&mut self, value: S)

Sets the name to use for table of contents. This is by default, “Table of Contents”

pub fn set_description(&mut self, value: Vec<String>)

Sets and replaces the description of the EPUB

pub fn add_description<S: Into<String>>(&mut self, value: S)

Adds a line to the EPUB description

pub fn clear_description(&mut self)

Remove all description paragraphs from EPUB

pub fn set_subjects(&mut self, value: Vec<String>)

Sets and replaces the subjects of the EPUB

pub fn add_subject<S: Into<String>>(&mut self, value: S)

Adds a value to the subjects

pub fn clear_subjects(&mut self)

Remove all the subjects from EPUB

pub fn set_license<S: Into<String>>(&mut self, value: S)

Sets the license under which this EPUB is distributed

pub fn set_publication_date(&mut self, date_published: DateTime<Utc>)

Sets the publication date of the EPUB

pub fn set_modified_date(&mut self, date_modified: DateTime<Utc>)

Sets the date on which the EPUB was last modified.

This value is part of the metadata. If this function is not called, the time at the moment of generation will be used instead.

pub fn set_uuid(&mut self, uuid: Uuid)

Sets the uuid used for the EPUB.

This is useful for reproducibly generating epubs.

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.

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.

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 written 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”.

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 section so it is displayed as the cover by Ereaders

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/.

See also

• EpubContent
• the add_resource method, to add other resources in the EPUB file.

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();

Trait Implementations

impl<Z: Debug + Zip> Debug for EpubBuilder<Z>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.