Struct BlockBuilder 

pub struct BlockBuilder { /* private fields */ }

Block Builder

A builder for constructing content blocks of various types.

Example

use lib_epub::{builder::content::BlockBuilder, types::{BlockType, Footnote}};

let mut builder = BlockBuilder::new(BlockType::Text);
builder.set_content("Hello, world!").add_footnote(Footnote {
    content: "This is a footnote.".to_string(),
    locate: 13,               
});

builder.build()?;

Notes

• Not all fields are required for all block types. Required fields vary by block type.
• The build() method will validate that required fields are set for the specified block type.

Implementations

impl BlockBuilder

pub fn new(block_type: BlockType) -> Self

Creates a new BlockBuilder instance

Initializes a BlockBuilder with the specified block type.

Parameters

• block_type: The type of block to construct

pub fn set_content(&mut self, content: &str) -> &mut Self

Sets the text content of the block

Used for Text, Quote, and Title block types.

Parameters

• content: The text content to set

pub fn set_title_level(&mut self, level: usize) -> &mut Self

Sets the heading level for a Title block

Only applicable to Title block types. Valid range is 1 to 6. If the level is outside the valid range, this method silently ignores the setting and returns self unchanged.

Parameters

• level: The heading level (1-6), corresponding to h1-h6 HTML tags

pub fn set_url(&mut self, url: &PathBuf) -> Result<&mut Self, EpubError>

Sets the media file path

Used for Image, Audio, and Video block types. This method validates that the file is a recognized image, audio, or video type.

Parameters

• url: The path to the media file

Return

• Ok(&mut self): If the file type is valid
• Err(EpubError): The file does not exist or the file format is not image, audio, or video

pub fn set_alt(&mut self, alt: &str) -> &mut Self

Sets the alternative text for an image

Only applicable to Image block types. Alternative text is displayed when the image cannot be loaded.

Parameters

• alt: The alternative text for the image

pub fn set_caption(&mut self, caption: &str) -> &mut Self

Sets the caption for the block

Used for Image, Audio, Video, and MathML block types. The caption is displayed below the media or element.

Parameters

• caption: The caption text to display

pub fn set_fallback(&mut self, fallback: &str) -> &mut Self

Sets the fallback text for audio or video content

Used for Audio and Video block types. The fallback text is displayed when the media file cannot be played.

Parameters

• fallback: The fallback text content

pub fn set_mathml_element(&mut self, element_str: &str) -> &mut Self

Sets the raw MathML element string

Only applicable to MathML block types. This method accepts the raw MathML markup data without validation. The user is responsible for ensuring the MathML is well-formed.

Parameters

• element_str: The raw MathML markup string

pub fn set_fallback_image( &mut self, fallback_image: PathBuf, ) -> Result<&mut Self, EpubError>

Sets the fallback image for MathML content

Only applicable to MathML block types. The fallback image is displayed when the MathML markup cannot be rendered. This method validates that the file is a recognized image type.

Parameters

• fallback_image: The path to the fallback image file

Return

• Ok(self): If the file type is valid
• Err(EpubError): If validation fails

pub fn add_footnote(&mut self, footnote: Footnote) -> &mut Self

Adds a footnote to the block

Adds a single footnote to the block’s footnotes collection. The footnote must reference a valid position within the content.

Parameters

• footnote: The footnote to add

pub fn set_footnotes(&mut self, footnotes: Vec<Footnote>) -> &mut Self

Sets all footnotes for the block

Replaces the current footnotes collection with the provided one. All footnotes must reference valid positions within the content.

Parameters

• footnotes: The vector of footnotes to set

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

Removes the last footnote

Removes and discards the last footnote from the footnotes collection. If the collection is empty, this method has no effect.

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

Clears all footnotes

Removes all footnotes from the block’s footnotes collection.

pub fn build(self) -> Result<Block, EpubError>

Builds the block

Constructs a Block instance based on the configured parameters and block type. This method validates that all required fields are set for the specified block type and validates the footnotes to ensure they reference valid content positions.

Return

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