Struct EpubBuilder

Source

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

Expand description

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
    .rootfile()
    .add("EPUB/content.opf")?;

builder
    .metadata()
    .add(MetadataItem::new("title", "Test Book"))
    .add(MetadataItem::new("language", "en"))
    .add(
        MetadataItem::new("identifier", "unique-id")
            .with_id("pub-id")
            .build(),
    );

builder
    .manifest()
    .add(
        "./test_case/Overview.xhtml",
        ManifestItem::new("content", "target/path")?,
    )?;
 
builder
    .spine()
    .add(SpineItem::new("content"));
 
builder
    .catalog()
    .set_title("Catalog Title")
    .add(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§

Source §

impl EpubBuilder<EpubVersion3>

Source

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

Source

pub fn add_rootfile( &mut self, rootfile: impl AsRef<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.

Source

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

Source

pub fn add_manifest( &mut self, manifest_source: impl Into<String>, 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.
If the manifest item ID already exists in the manifest, the manifest item will be overwritten.

Source

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

Source

pub fn set_catalog_title(&mut self, title: impl Into<String>) -> &mut Self

Set catalog title

§Parameters

title: Catalog title

Source

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

Source

pub fn add_content( &mut self, target_path: impl AsRef<str>, content: ContentBuilder, ) -> &mut Self

Add content

The content builder can be used to generate content for the book. It is recommended to use the content-builder feature to use this function.

§Parameters

target_path: The path to the resource file within the EPUB container
content: The content builder to generate content

Source

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

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)

Source

pub fn rootfile(&mut self) -> &mut RootfileBuilder

Get a mutable reference to the rootfile builder

Allows direct manipulation of rootfile entries.

§Return

&mut RootfileBuilder: Mutable reference to the rootfile builder

Source

pub fn metadata(&mut self) -> &mut MetadataBuilder

Get a mutable reference to the metadata builder

Allows direct manipulation of metadata items.

§Return

&mut MetadataBuilder: Mutable reference to the metadata builder

Source

pub fn manifest(&mut self) -> &mut ManifestBuilder

Get a mutable reference to the manifest builder

Allows direct manipulation of manifest items.

§Return

&mut ManifestBuilder: Mutable reference to the manifest builder

Source

pub fn spine(&mut self) -> &mut SpineBuilder

Get a mutable reference to the spine builder

Allows direct manipulation of spine items.

§Return

&mut SpineBuilder: Mutable reference to the spine builder

Source

pub fn catalog(&mut self) -> &mut CatalogBuilder

Get a mutable reference to the catalog builder

Allows direct manipulation of navigation/catalog items.

§Return

&mut CatalogBuilder: Mutable reference to the catalog builder

Source

pub fn content(&mut self) -> &mut DocumentBuilder

Get a mutable reference to the content builder

Allows direct manipulation of content documents.

§Return

&mut DocumentBuilder: Mutable reference to the document builder

Source

pub fn make(self, output_path: impl AsRef<Path>) -> 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

Source

pub fn build( self, output_path: impl AsRef<Path>, ) -> 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

Source

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.