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.
Implementations§
Source§impl EpubBuilder<EpubVersion3>
impl EpubBuilder<EpubVersion3>
Sourcepub fn new() -> Result<Self, EpubError>
pub fn new() -> Result<Self, EpubError>
Create a new EpubBuilder instance
§Return
Ok(EpubBuilder): Builder instance created successfullyErr(EpubError): Error occurred during builder initialization
Sourcepub fn add_rootfile(&mut self, rootfile: &str) -> Result<&mut Self, EpubError>
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.
Sourcepub fn add_metadata(&mut self, item: MetadataItem) -> &mut Self
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
Sourcepub fn add_manifest(
&mut self,
manifest_source: &str,
manifest_item: ManifestItem,
) -> Result<&mut Self, EpubError>
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 pathmanifest_item- Manifest item information
§Return
Ok(&mut Self)- Successful addition, returns a reference to itselfErr(EpubError)- Error occurred during the addition process
§Notes
- At least one rootfile must be added before adding manifest items.
Sourcepub fn add_spine(&mut self, item: SpineItem) -> &mut Self
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
Sourcepub fn set_catalog_title(&mut self, title: &str) -> &mut Self
pub fn set_catalog_title(&mut self, title: &str) -> &mut Self
Sourcepub fn add_catalog_item(&mut self, item: NavPoint) -> &mut Self
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
Sourcepub fn set_catalog(&mut self, catalog: Vec<NavPoint>) -> &mut Self
pub fn set_catalog(&mut self, catalog: Vec<NavPoint>) -> &mut Self
Sourcepub fn build<P: AsRef<Path>>(
self,
output_path: P,
) -> Result<EpubDoc<BufReader<File>>, EpubError>
pub fn build<P: AsRef<Path>>( self, output_path: P, ) -> Result<EpubDoc<BufReader<File>>, EpubError>
Sourcepub fn from<R: Read + Seek>(doc: &mut EpubDoc<R>) -> Result<Self, EpubError>
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 anEpubDocinstance that contains the parsed EPUB data
§Return
Ok(EpubBuilder): Successfully created builder instance populated with the document’s dataErr(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.