Struct Document 

pub struct Document { /* private fields */ }

Implementations

impl Document

pub fn parse(input: &[u8], format: Format) -> Result<Self, Error>

pub fn parse_str(input: &str, format: Format) -> Result<Self, Error>

pub fn parse_with( input: &[u8], format: Format, extensions: MarkdownExtensions, ) -> Result<Self, Error>

Like Document::parse, plus Markdown extensions to enable (ignored for other formats) — the read-path counterpart of Editor::new_ext. Enable MarkdownExtensions::html_elements here to make embedded HTML (<img>, <picture>, …) queryable via Document::query instead of arriving as opaque raw HTML.

pub fn parse_str_with( input: &str, format: Format, extensions: MarkdownExtensions, ) -> Result<Self, Error>

Document::parse_with for a &str.

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

Render the document to HTML. For Djot/Markdown this is the rich rendering path that resolves reference/footnote side tables.

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

Serialize the document to target’s own syntax: a round-trip when target names the document’s own format, cross-format conversion otherwise (e.g. parse Markdown, serialize as Djot). Returns Error::UnsupportedFormat when the requested direction has no serializer (today: converting into XML from another format).

Prefer this over Document::serialize: serializing is a question about where the bytes are going, so it takes a Target. The older spelling takes a Format and still works — every Format is a Target — but it cannot name an export-only target, and this one can.

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

Serialize the document to format’s own source syntax.

The original spelling of Document::serialize_to, kept for compatibility and defined in terms of it. It types the output axis as Format, which is the input vocabulary; reach for serialize_to in new code.

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

Encode the document’s AST as pretty-printed JSON (the same encoding as twig convert -o ast).

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

Resolve a CSS-lite selector (e.g. heading[level=2], link[dest^="http"], code, list > item) against the document, returning one QueryMatch per matching node in document order. A malformed selector yields Error::InvalidArgument.

This is the general replacement for scanning code spans by hand: a verbatim / code_block / raw_inline / raw_block selector recovers those, and every other node kind is reachable too.

pub fn span(&mut self, node: NodeId) -> Result<Range<usize>, Error>

Return the whole source span of node without running a selector query.

pub fn content_span( &mut self, node: NodeId, ) -> Result<Option<Range<usize>>, Error>

Return the interior span of node, or None when the node has no recorded content span.

pub fn cell_extent(&mut self, node: NodeId) -> Result<Option<(u32, u32)>, Error>

The grid extent of the cell at node — how many (columns, rows) it occupies — or None when the node is not a cell. Both are at least 1, and (1, 1) is the ordinary one-square cell; anything larger is a merged cell from a format with a real grid (HTML’s colspan/rowspan, an rST grid table). GFM and djot pipe tables always report (1, 1).

HTML’s rowspan="0" (“to the end of the row group”) is not a count and reports 1; the source spelling survives on the node’s attributes.

This is an accessor rather than a FlatNode field because the C struct it snapshots is ABI-frozen — see Document::span for the same shape.

pub fn nodes(&mut self) -> Result<Vec<FlatNode>, Error>

Snapshot the whole tree as a flat FlatNode array (the JSON-free read path for a renderer), indexed so nodes[i].id == NodeId(i). Walk it via the parent/first_child/next_sibling links; the root is the node whose parent is None.

pub fn children( &mut self, node: Option<NodeId>, ) -> Result<Vec<QueryMatch>, Error>

The direct children of node as QueryMatches (id, span, kind) — None enumerates the document root’s children (the top-level blocks). The cheap enumeration an incremental renderer walks to decide which blocks to re-marshal with Document::subtree. A childless node yields an empty vec.

pub fn subtree(&mut self, node: NodeId) -> Result<Vec<FlatNode>, Error>

Snapshot the subtree rooted at node as a self-contained FlatNode array with local ids: array[0] is the root, every link is an index into the returned vec (or None), and spans stay absolute. The root’s parent and next_sibling are None, so a walk from index 0 stays inside the subtree. Error::InvalidArgument if node is out of range.

pub fn node_at(&mut self, offset: usize) -> Result<Option<QueryMatch>, Error>

The deepest node whose span contains byte offset (with offset equal to the source length treated as inside the root) — hit-testing and cursor context. Ok(None) if no node covers the offset; Error::InvalidArgument if offset exceeds the source length.

pub fn ancestors_at(&mut self, offset: usize) -> Result<Vec<QueryMatch>, Error>

The chain of nodes containing byte offset, root-first down to the deepest (the node Document::node_at returns) — the ancestor path for a breadcrumb. Empty if no node covers the offset.

Trait Implementations

impl Debug for Document

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

Formats the value using the given formatter.

impl Drop for Document

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.