Struct Builder 

pub struct Builder { /* private fields */ }

Programmatic construction of a document — the write-path mirror of Document::parse. Build the tree bottom-up (add children, then the container, wiring them with Builder::set_children); every add* method returns the new node’s NodeId. Then render, serialize, query, or dump the subtree rooted at any id, on demand, without consuming the builder. All input strings are copied, so caller buffers need not outlive a call.

Implementations

impl Builder

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

Create an empty builder.

pub fn add(&mut self, kind: VoidKind) -> Result<NodeId, Error>

Add a void-payload node (attach children later with Builder::set_children).

pub fn add_text(&mut self, kind: TextKind, text: &str) -> Result<NodeId, Error>

Add a single-string-payload node (a str, code span, url, comment, …).

pub fn add_heading(&mut self, level: u32) -> Result<NodeId, Error>

Add a heading of the given level (attach its inline children afterward).

pub fn add_code_block( &mut self, lang: Option<&str>, text: &str, ) -> Result<NodeId, Error>

Add a code block, with an optional info-string language.

pub fn add_raw_block( &mut self, format: &str, text: &str, ) -> Result<NodeId, Error>

Add a raw block targeting format (e.g. "html").

pub fn add_metadata(&mut self, lang: &str, text: &str) -> Result<NodeId, Error>

Add a document-metadata block written in config language lang.

pub fn add_raw_inline( &mut self, format: &str, text: &str, ) -> Result<NodeId, Error>

Add a raw inline targeting format.

pub fn add_smart_punctuation( &mut self, kind: SmartPunctuation, text: &str, ) -> Result<NodeId, Error>

Add a smart-punctuation node of kind. text is accepted for ABI compatibility but ignored by the underlying builder: the node’s spelling is always the canonical one for kind (e.g. "---" for an em dash), never a caller-supplied one.

pub fn add_link( &mut self, destination: Option<&str>, reference: Option<&str>, ) -> Result<NodeId, Error>

Add a link with an optional destination and/or reference label (attach the link text as children).

pub fn add_image( &mut self, destination: Option<&str>, reference: Option<&str>, ) -> Result<NodeId, Error>

Add an image — like Builder::add_link, but children are the alt text.

pub fn add_directive( &mut self, form: DirectiveForm, name: &str, ) -> Result<NodeId, Error>

Add a generic directive of the given form and name.

pub fn add_element(&mut self, name: &str) -> Result<NodeId, Error>

Add a generic named element (the escape hatch for HTML/XML tags).

pub fn add_processing_instruction( &mut self, target: &str, data: &str, ) -> Result<NodeId, Error>

Add an XML processing instruction (<?target data?>).

pub fn add_footnote(&mut self, label: &str) -> Result<NodeId, Error>

Add a footnote definition with the given label.

pub fn add_citation(&mut self, label: &str) -> Result<NodeId, Error>

Add a citation definition — reStructuredText’s .. [CIT2002] .... Holds blocks, like a footnote; the two differ in which name registry resolves them, which is why this is its own call and not a flag on Builder::add_footnote.

pub fn add_substitution(&mut self, label: &str) -> Result<NodeId, Error>

Add a substitution definition — reStructuredText’s .. |name| image:: p.png. Unlike a footnote or citation, its children are INLINE nodes.

pub fn add_reference( &mut self, label: &str, destination: &str, ) -> Result<NodeId, Error>

Add a link/image reference definition (label → destination).

pub fn add_bullet_list( &mut self, style: BulletStyle, tight: bool, ) -> Result<NodeId, Error>

Add a bullet list.

pub fn add_ordered_list( &mut self, numbering: OrderedNumbering, delim: OrderedDelim, tight: bool, start: Option<u32>, ) -> Result<NodeId, Error>

Add an ordered list, with an optional explicit start number.

pub fn add_task_list(&mut self, tight: bool) -> Result<NodeId, Error>

Add a task list.

pub fn add_task_list_item(&mut self, checked: bool) -> Result<NodeId, Error>

Add a task-list item with the given checkbox state.

pub fn add_row(&mut self, head: bool) -> Result<NodeId, Error>

Add a table row (head marks a header row).

pub fn add_cell( &mut self, head: bool, alignment: Alignment, ) -> Result<NodeId, Error>

Add a one-square table cell (head marks a header cell).

pub fn add_cell_spanning( &mut self, head: bool, alignment: Alignment, colspan: u32, rowspan: u32, ) -> Result<NodeId, Error>

Add a table cell occupying colspan columns and rowspan rows — a grid table’s merged cell. Both must be at least 1 (Error::InvalidArgument otherwise); (1, 1) is exactly Builder::add_cell. Read back with Document::cell_extent.

pub fn set_children( &mut self, parent: NodeId, children: &[NodeId], ) -> Result<(), Error>

Set parent’s children to children (in order), replacing any it had. Each child id should appear in exactly one set_children call.

pub fn set_attrs( &mut self, id: NodeId, attrs: &[(&str, Option<&str>)], ) -> Result<(), Error>

Attach {...} attributes to id ((key, Some(value)), or (key, None) for a bare attribute), replacing any it had. An empty slice clears them.

pub fn render_html(&mut self, root: NodeId) -> Result<Vec<u8>, Error>

Render the subtree rooted at root to HTML (generic whole-vocabulary printer — a built tree has no djot/Markdown side tables).

pub fn serialize_to( &mut self, root: NodeId, target: Target, ) -> Result<Vec<u8>, Error>

Serialize the subtree rooted at root to target’s syntax. Returns Error::UnsupportedFormat when the target can’t represent the built tree (e.g. semantic kinds into XML).

Prefer this over Builder::serialize, for the reason Document::serialize_to gives.

pub fn serialize( &mut self, root: NodeId, format: Format, ) -> Result<Vec<u8>, Error>

Serialize the subtree rooted at root to format’s source syntax.

The original spelling of Builder::serialize_to, kept for compatibility and defined in terms of it.

pub fn ast_json(&mut self, root: NodeId) -> Result<Vec<u8>, Error>

Encode the subtree rooted at root as pretty-printed JSON.

pub fn query( &mut self, root: NodeId, selector: &str, ) -> Result<Vec<QueryMatch>, Error>

Resolve a selector against the subtree rooted at root (same grammar as Document::query).

Trait Implementations

impl Debug for Builder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Builder

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.