Struct EpubBuilder 

pub struct EpubBuilder<Version> { /* private fields */ }

EPUB Builder

The main structure used to create and build EPUB ebook files. Supports the EPUB 3.0 specification and can build a complete EPUB file structure.

Usage

use lib_epub::{
    builder::{EpubBuilder, EpubVersion3},
    types::{MetadataItem, ManifestItem, NavPoint, SpineItem},
};

let mut builder = EpubBuilder::<EpubVersion3>::new()?;

builder
    .add_rootfile("EPUB/content.opf")?
    .add_metadata(MetadataItem::new("title", "Test Book"))
    .add_metadata(MetadataItem::new("language", "en"))
    .add_metadata(
        MetadataItem::new("identifier", "unique-id")
            .with_id("pub-id")
            .build(),
    )
    .add_manifest(
        "./test_case/Overview.xhtml",
        ManifestItem::new("content", "target/path")?,
    )?
    .add_spine(SpineItem::new("content"))
    .add_catalog_item(NavPoint::new("label"));

builder.build("output.epub")?;

Notes

• All resource files must exist on the local file system.
• At least one rootfile must be added before adding manifest items.
• Requires at least one title, language, and identifier with id pub-id.

Implementations

impl EpubBuilder<EpubVersion3>

pub fn new() -> Result<Self, EpubError>

Create a new EpubBuilder instance

Return

• Ok(EpubBuilder): Builder instance created successfully
• Err(EpubError): Error occurred during builder initialization

pub fn add_rootfile(&mut self, rootfile: &str) -> Result<&mut Self, EpubError>

Add a rootfile path

The added path points to an OPF file that does not yet exist and will be created when building the Epub file.

Parameters

• rootfile: Rootfile path

Notes

• The added rootfile path must be a relative path and cannot start with “../”.
• At least one rootfile must be added before adding metadata items.

pub fn add_metadata(&mut self, item: MetadataItem) -> &mut Self

Add metadata item

Required metadata includes title, language, and an identifier with ‘pub-id’. Missing this data will result in an error when building the epub file.

Parameters

• item: Metadata items to add

pub fn add_manifest( &mut self, manifest_source: &str, manifest_item: ManifestItem, ) -> Result<&mut Self, EpubError>

Add manifest item and corresponding resource file

The builder will automatically recognize the file type of the added resource and update it in ManifestItem.

Parameters

• manifest_source - Local resource file path
• manifest_item - Manifest item information

Return

• Ok(&mut Self) - Successful addition, returns a reference to itself
• Err(EpubError) - Error occurred during the addition process

Notes

• At least one rootfile must be added before adding manifest items.

pub fn add_spine(&mut self, item: SpineItem) -> &mut Self

Add spine item

The spine item defines the reading order of the book.

Parameters

• item: Spine item to add

pub fn set_catalog_title(&mut self, title: &str) -> &mut Self

Set catalog title

Parameters

• title: Catalog title

pub fn add_catalog_item(&mut self, item: NavPoint) -> &mut Self

Add catalog item

Added directory items will be added to the end of the existing list.

Parameters

• item: Catalog item to add

pub fn set_catalog(&mut self, catalog: Vec<NavPoint>) -> &mut Self

Re-/ Set catalog

The passed list will overwrite existing data.

Parameters

• catalog: Catalog to set

pub fn make<P: AsRef<Path>>(self, output_path: P) -> Result<(), EpubError>

Builds an EPUB file and saves it to the specified path

Parameters

• output_path: Output file path

Return

• Ok(()): Build successful
• Err(EpubError): Error occurred during the build process

pub fn build<P: AsRef<Path>>( self, output_path: P, ) -> Result<EpubDoc<BufReader<File>>, EpubError>

Builds an EPUB file and returns a EpubDoc

Builds an EPUB file at the specified location and parses it into a usable EpubDoc object.

Parameters

• output_path: Output file path

Return

• Ok(EpubDoc): Build successful
• Err(EpubError): Error occurred during the build process

pub fn from<R: Read + Seek>(doc: &mut EpubDoc<R>) -> Result<Self, EpubError>

Creates an EpubBuilder instance from an existing EpubDoc

This function takes an existing parsed EPUB document and creates a new builder instance with all the document’s metadata, manifest items, spine, and catalog information. It essentially reverses the EPUB building process by extracting all the necessary components from the parsed document and preparing them for reconstruction.

The function copies the following information from the provided EpubDoc:

• Rootfile path (based on the document’s base path)
• All metadata items (title, author, identifier, etc.)
• Spine items (reading order of the publication)
• Catalog information (navigation points)
• Catalog title
• All manifest items (except those with ‘nav’ property, which are skipped)

Parameters

• doc: A mutable reference to an EpubDoc instance that contains the parsed EPUB data

Return

• Ok(EpubBuilder): Successfully created builder instance populated with the document’s data
• Err(EpubError): Error occurred during the extraction process

Notes

• This type of conversion will upgrade Epub2.x publications to Epub3.x. This upgrade conversion may encounter unknown errors (it is unclear whether it will cause errors), so please use it with caution.

Trait Implementations

impl<Version> Drop for EpubBuilder<Version>

fn drop(&mut self)

Remove temporary directory when dropped