Struct DocumentBuilder 

pub struct DocumentBuilder { /* private fields */ }

Constructs a Document one node at a time. The parser uses this internally; consumers building trees by hand use the same.

The builder owns a Bump. Allocated nodes live for the lifetime of the builder (and, after build(), of the resulting Document).

Build flow

let b = DocumentBuilder::new();
let root = b.new_element(b.alloc_str("catalog"));
// … allocate more nodes, link them via append_child / append_attribute …
b.set_root(root);
let doc = b.build();

set_root returns immediately (no borrow on the builder is held past the call), so the subsequent build() is free to consume self even though root borrowed from the builder during construction.

Implementations

impl DocumentBuilder

pub fn new() -> Self

pub fn with_capacity(capacity: usize) -> Self

Pre-allocate capacity bytes for the arena. Useful when parsing large documents — avoids the initial small-chunk allocations.

pub fn set_source(&self, bytes: Box<[u8]>)

Stash an owned source buffer that arena strings may borrow from. The parser calls this with the (possibly transcoded) input bytes so that subsequent alloc_str_borrow calls can hand back zero-copy &str slices into these bytes instead of memcpy’ing them into the arena.

Ownership transfers to the Document on build, so the borrowed slices stay valid for the document’s lifetime. Calling set_source twice on the same builder is allowed and frees the prior buffer.

pub fn source(&self) -> Option<&[u8]>

Return the stashed source bytes, if any. Returns a slice whose lifetime is bounded by &self — but in practice the bytes live at a stable heap address until build moves ownership of them to the Document.

pub fn set_version(&self, v: impl Into<String>)

Set the XML declaration version (e.g. "1.0", "1.1"). Default is "1.0". Plumbed into Document::version on build.

pub fn set_encoding(&self, e: impl Into<String>)

Set the XML declaration encoding (e.g. "UTF-8"). Default is "UTF-8". Plumbed into Document::encoding on build.

pub fn set_base_url(&self, uri: Option<String>)

Set the URI the document is being loaded from. Plumbed into Document::base_url on build.

pub fn set_standalone(&self, s: Option<bool>)

Set the XML declaration standalone="…" value. None means the declaration did not include standalone; Some(true) / Some(false) correspond to standalone="yes" / standalone="no".

pub fn set_html_metadata(&self, m: Option<HtmlMeta>)

Attach HTML-specific document metadata. Used by the HTML parser sink to record quirks-mode and DOCTYPE info; XML callers leave this as None (the default). Plumbed into Document::html_metadata on build.

pub fn bump(&self) -> &Bump

Direct access to the underlying Bump. Use sparingly — most allocation should go through the typed new_element etc. methods.

pub fn alloc_str<'a>(&'a self, s: &str) -> &'a str

Copy s into the arena and return an arena-lifetime slice. When the caller can prove s already lives at least as long as the eventual Document (e.g. it borrows from the input string slice that the caller will keep alive), alloc_str_borrow is cheaper — no copy.

pub unsafe fn alloc_str_borrow<'a>(&'a self, s: &'a str) -> &'a str

Pass through a &str that the caller has guaranteed lives at least until the Document drops. Typically the input source slice. Zero-copy.

Safety

The caller must guarantee s outlives the returned reference. In practice this means s borrows from the same input the parser is reading and the Document will be tied to that same input via the caller’s outer lifetime. For untrusted lifetimes use alloc_str.

pub fn new_element<'a>(&'a self, name: &'a str) -> &'a mut Node<'a>

pub fn new_text<'a>(&'a self, content: &'a str) -> &'a mut Node<'a>

pub fn new_cdata<'a>(&'a self, content: &'a str) -> &'a mut Node<'a>

pub fn new_comment<'a>(&'a self, content: &'a str) -> &'a mut Node<'a>

pub fn new_pi<'a>( &'a self, target: &'a str, content: Option<&'a str>, ) -> &'a mut Node<'a>

Build a processing-instruction node. content is None for a PI with no data section (<?foo?>) and Some — possibly "" — for one that has one (<?foo?> created via xmlNewDocPI with an empty string). The distinction is libxml2’s NULL-vs-empty content and governs the trailing space the serializer emits.

pub fn new_dtd_decl<'a>(&'a self, content: &'a str) -> &'a mut Node<'a>

Build a DTD internal-subset declaration node. content is the raw markup declarations (each newline-terminated), emitted verbatim by the serializer inside the DOCTYPE’s [ … ]. Held as the single child of the internal-subset DTD node.

pub fn new_fragment<'a>(&'a self) -> &'a mut Node<'a>

Allocate an empty document-fragment node. Used by the libxml2 compat shim’s xmlNewDocFragment; the fragment is a transparent container that holds an ordered child list before being grafted into a real document subtree.

pub fn new_entity_ref<'a>( &'a self, name: &'a str, content: &'a str, ) -> &'a mut Node<'a>

Build an unresolved entity-reference node. name is the entity’s NCName (e.g. "foo" for &foo;); content is the literal source form including the leading & and trailing ;, which the serializer writes verbatim to round-trip the reference back to source. Emitted by the parser only when ParseOptions::resolve_entities is false.

pub fn new_attribute<'a>( &'a self, name: &'a str, value: &'a str, ) -> &'a mut Attribute<'a>

pub fn new_namespace<'a>( &'a self, prefix: Option<&'a str>, href: &'a str, ) -> &'a Namespace<'a>

pub fn append_child<'a>(&'a self, parent: &'a Node<'a>, child: &'a Node<'a>)

Append child as the last child of parent. Sets parent/sibling pointers consistently.

Panics

Panics if child is already attached somewhere (its parent is not None) — callers should detach first. We treat double-attach as a builder bug, not a recoverable error.

pub fn append_attribute<'a>( &'a self, element: &'a Node<'a>, attr: &'a Attribute<'a>, )

Append attr to the end of element’s attribute list. Sets the attribute’s parent and links siblings.

pub fn detach<'a>(&'a self, child: &'a Node<'a>)

Detach child from its current parent (no-op if already detached). Repairs sibling links on the parent’s child list.

pub fn attach_prolog_orphan<'a>(&'a self, node: &'a Node<'a>)

Record an orphan leaf (comment / PI) that appeared in the document’s prolog (before the root element opened). Linked as root.prev_sibling chain on build.

pub fn attach_epilogue_orphan<'a>(&'a self, node: &'a Node<'a>)

Record an orphan leaf (comment / PI) that appeared in the document’s epilogue (after </root>). Linked as root.next_sibling chain on build.

pub fn set_root<'a>(&'a self, root: &'a Node<'a>)

Mark root as the document’s root element. Call before build. The borrow on &self only lives for this call, so subsequent build() can freely consume the builder.

pub fn build(self) -> Document

Finalize the build. Must be called after set_root.

Panics

Panics if set_root was never called.

Trait Implementations

impl Default for DocumentBuilder

fn default() -> Self

Returns the “default value” for a type.

impl Drop for DocumentBuilder

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.