Struct Document 

pub struct Document {
    pub version: Option<YamlVersion>,
    pub tag_handles: Vec<TagHandle>,
    /* private fields */
}

A parsed YAML document: an arena of nodes reachable from a single root.

Fields

version: Option<YamlVersion>

The %YAML directive, if the document carried one.

tag_handles: Vec<TagHandle>

The %TAG directives, in the order they appeared.

Implementations

impl Document

pub fn new() -> Self

An empty document with no root.

pub fn new_asdf() -> Self

An empty document carrying the directives ASDF conventionally writes.

pub fn node_count(&self) -> usize

The number of nodes in the arena.

This counts every node including those only reachable through an alias, so it is not the same as the number of distinct tree positions.

pub fn root(&self) -> Option<NodeId>

The document’s root node, if it has one.

pub fn set_root(&mut self, id: NodeId)

Set the document’s root node.

pub fn add(&mut self, node: Node) -> NodeId

Add a node to the arena and return its id.

pub fn node(&self, id: NodeId) -> &Node

Borrow a node.

Panics

Panics if id did not come from this document.

pub fn node_mut(&mut self, id: NodeId) -> &mut Node

Mutably borrow a node.

Panics

Panics if id did not come from this document.

pub fn get(&self, id: NodeId) -> Option<&Node>

Borrow a node if the id is in range.

pub fn resolve(&self, id: NodeId) -> NodeId

Follow aliases until reaching a non-alias node.

Alias chains are bounded by the arena size, so a cycle – which a conforming YAML document cannot contain, but a hand-edited one might – terminates rather than looping forever.

pub fn resolved(&self, id: NodeId) -> &Node

Borrow a node, following aliases first.

pub fn tag_of(&self, id: NodeId) -> Option<&Tag>

The effective tag of a node, following aliases.

An alias node carries no tag of its own, so the tag of its target is what callers mean when they ask.

pub fn add_scalar(&mut self, value: impl Into<String>) -> NodeId

Add a plain scalar node.

pub fn add_scalar_styled( &mut self, value: impl Into<String>, style: ScalarStyle, ) -> NodeId

Add a scalar node with an explicit style.

pub fn add_sequence(&mut self, items: Vec<NodeId>) -> NodeId

Add a sequence node built from existing nodes.

pub fn add_mapping(&mut self, pairs: Vec<(NodeId, NodeId)>) -> NodeId

Add a mapping node built from existing key/value node pairs.

pub fn sequence_items(&self, id: NodeId) -> Option<&[NodeId]>

The items of a sequence node, following aliases.

pub fn mapping_entries(&self, id: NodeId) -> Option<&[Entry]>

The entries of a mapping node, following aliases.

pub fn mapping_get(&self, id: NodeId, key: &str) -> Option<NodeId>

Look up a mapping value by string key, following aliases.

Where a key appears more than once – which YAML permits and ASDF files occasionally contain – the first occurrence wins, matching how a streaming reader would see it.

pub fn mapping_set( &mut self, id: NodeId, key: &str, value: NodeId, ) -> Option<NodeId>

Insert or replace a mapping entry by string key.

Returns the previous value node when the key was already present.

pub fn mapping_remove(&mut self, id: NodeId, key: &str) -> Option<NodeId>

Remove a mapping entry by string key, returning the value node.

pub fn sequence_get(&self, id: NodeId, index: i64) -> Option<NodeId>

Index into a sequence, following aliases and accepting negative indices that count back from the end.

pub fn container_len(&self, id: NodeId) -> Option<usize>

The number of children of a container node, or None for scalars.

impl Document

pub fn lookup_from(&self, start: NodeId, path: &Path) -> Option<NodeId>

Resolve a path against a starting node.

Aliases are followed at each step, so a path may descend through a shared node.

pub fn lookup(&self, path: &Path) -> Option<NodeId>

Resolve a path against the document root.

pub fn lookup_str(&self, path: &str) -> Option<NodeId>

Parse and resolve a path in one step.

pub fn parent_of(&self, id: NodeId) -> Option<NodeId>

The container that holds id, searching down from the root.

A node reachable by more than one route reports the first parent found in document order. Aliases are not followed: an alias node is its own child of whatever holds it, and the node it points at is reported under its defining position.

pub fn path_of(&self, id: NodeId) -> Option<String>

The path from the root to id, in the syntax Path::parse accepts.

Absolute, so /history/extensions/0 rather than history/extensions/0, and a sequence index is written plainly rather than bracketed – that is the form libasdf reports and the one its own tests expect. A bare numeric component is unambiguous on the way back in, since it is read as an index only when the container it addresses is a sequence.

The root itself is /. Returns None when id is not reachable from the root, which is the case for a node built but not yet attached.

impl Document

pub fn insert_at( &mut self, path: &Path, value: NodeId, ) -> Result<Option<NodeId>, PathError>

Insert value at path, creating intermediate mappings as needed.

This mirrors libasdf’s asdf_node_insert_at with materialisation on: setting powers/squares in an empty tree creates the powers mapping on the way. Returns the node that was replaced, if any.

Intermediate steps are only ever created as mappings, since a bare path component gives no way to say “make a sequence here”. A component that names an existing sequence still indexes into it.

pub fn insert_at_str( &mut self, path: &str, value: NodeId, ) -> Result<Option<NodeId>, PathError>

Parse and insert in one step.

pub fn sequence_set( &mut self, id: NodeId, index: i64, value: NodeId, ) -> Option<NodeId>

Replace a sequence element, or append when the index is one past the end. Returns the element that was replaced.

pub fn remove_at_str(&mut self, path: &str) -> Option<NodeId>

Remove whatever is at path, returning it.

pub fn sequence_remove(&mut self, id: NodeId, index: i64) -> Option<NodeId>

Remove a sequence element, returning it.

Trait Implementations

impl Clone for Document

fn clone(&self) -> Document

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Document

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

Formats the value using the given formatter.

impl Default for Document

fn default() -> Self

Returns the “default value” for a type.