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 remove_last_rootfile(&mut self) -> &mut Self

Remove the last added rootfile from the builder

pub fn take_last_rootfile(&mut self) -> Option<String>

Remove and return the last added rootfile

Return

• Some(String): The last added rootfile
• None: If no rootfile exists

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

Clear all configured rootfile entries from the builder

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 remove_last_metadata(&mut self) -> &mut Self

Remove the last metadata item

pub fn take_last_metadata(&mut self) -> Option<MetadataItem>

Remove and return the last metadata item

Return

• Some(MetadataItem): The last metadata item
• None: If no metadata exists

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

Clear all metadata entries

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 remove_manifest(&mut self, id: &str) -> Result<&mut Self, EpubError>

Remove manifest item and corresponding resource file

This function removes the manifest item from the manifest list and also deletes the corresponding resource file from the temporary directory.

Parameters

• id: The unique identifier of the manifest item to remove

Return

• Ok(&mut Self) Successfully removed the manifest item
• Err(EpubError) Error occurred during the removal process

pub fn take_manifest(&mut self, id: &str) -> Option<ManifestItem>

Remove and return the specified manifest item

Parameters

• id: The unique identifier of the manifest item to remove

Return

• Some(ManifestItem): The removed manifest item
• None: If the manifest item does not exist or error occurs during the removal process

pub fn clear_manifests(&mut self) -> Result<&mut Self, EpubError>

Clear all manifest items and their corresponding resource files

Return

• Ok(&mut Self) - Successfully cleared all manifest items, returns a reference to itself
• Err(EpubError) - Error occurred during the clearing process

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 remove_last_spine(&mut self) -> &mut Self

Remove the last spine item from the builder

pub fn take_last_spine(&mut self) -> Option<SpineItem>

Remove and return the last spine item from the builder

Return

• Some(SpineItem): The last spine item if it existed
• None: If no spine items exist in the list

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

Clear all spine items from the builder

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 remove_last_catalog_item(&mut self) -> &mut Self

Remove the last catalog item

pub fn take_last_catalog_item(&mut self) -> Option<NavPoint>

Remove and return the last catalog item

Return

• Some(NavPoint): The last catalog item if it existed
• None: If no catalog items exist in the list

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 clear_catalog(&mut self) -> &mut Self

Clear all catalog items

pub fn clear_all(&mut self) -> Result<&mut Self, EpubError>

Clear all data from the builder

This function clears all metadata, manifest items, spine items, catalog items, etc. from the builder, effectively resetting it to an empty state.

Return

• Ok(&mut Self): Successfully cleared all data
• Err(EpubError): Error occurred during the clearing process (specifically during manifest clearing)

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