Struct ryml::Tree

pub struct Tree<'a> { /* private fields */ }

Represents a parsed YAML tree

Implementations

impl<'a> Tree<'a>

pub fn parse(text: impl AsRef<str>) -> Result<Tree<'a>, Error>

Create a new tree and parse into its root.
The immutable YAML source is first copied to the tree’s arena, and parsed from there.

pub fn parse_in_place(text: impl AsMut<str> + 'a) -> Result<Tree<'a>, Error>

Create a new tree and parse into its root.
A mutable reference to the YAML source is passed to the tree parser, and parsed in-situ.

pub fn emit(&self) -> Result<String, Error>

Emit tree as YAML to an owned string.

pub fn emit_json(&self) -> Result<String, Error>

Emit tree as JSON to an owned string.

pub fn emit_to_buffer(&self, buf: &mut [u8]) -> Result<usize, Error>

Emit tree as YAML to the given buffer. Returns the number of bytes written.

pub fn emit_json_to_buffer(&self, buf: &mut [u8]) -> Result<usize, Error>

Emit tree as JSON to the given buffer. Returns the number of bytes written.

pub fn emit_to_writer<W: Write + Seek>(
    &self,
    writer: &mut W
) -> Result<usize, Error>

Emit tree as YAML to the given writer. Returns the number of bytes written.

pub fn emit_json_to_writer<W: Write + Seek>(
    &self,
    writer: &mut W
) -> Result<usize, Error>

Emit tree as JSON to the given writer. Returns the number of bytes written.

pub fn root_id(&self) -> Result<usize, Error>

Get the node to the root node.

pub fn root_ref<'t>(&'t self) -> Result<NodeRef<'a, 't, '_, &'t Self>, Error>

Get a NodeRef to the root node.

pub fn root_ref_mut<'t>(
    &'t mut self
) -> Result<NodeRef<'a, 't, '_, &'t mut Tree<'a>>, Error>

Get a mutable NodeRef to the root node.

pub fn get<'t>(
    &'t self,
    index: usize
) -> Result<NodeRef<'a, 't, '_, &'t Self>, Error>

Get a NodeRef to the given node, if it exists.

pub fn get_mut<'t>(
    &'t mut self,
    index: usize
) -> Result<NodeRef<'a, 't, '_, &'t mut Self>, Error>

Get a mutable NodeRef to the given node, if it exists.

pub fn len(&self) -> usize

Get the total number of nodes.

pub fn is_empty(&self) -> bool

Returns true if the tree is empty.

pub fn capacity(&self) -> usize

Get the capacity of the tree.

pub fn slack(&self) -> Result<usize, Error>

Get the unused capacity of the tree.

pub fn arena_len(&self) -> usize

Get the size of the internal string arena.

pub fn arena_is_empty(&self) -> bool

Returns true is the internal string arena is empty.

pub fn arena_capacity(&self) -> usize

Get the capacity of the internal string arena.

pub fn arena_slack(&self) -> Result<usize, Error>

Get the unused capacity of the internal string arena.

pub fn reserve(&mut self, node_capacity: usize)

Reserves capacity to hold at least capacity nodes.

pub fn reserve_arena(&mut self, arena_capacity: usize)

Ensures the tree’s internal string arena is at least the given capacity.

Note: Growing the arena may cause relocation of the entire existing arena, and thus change the contents of individual nodes.

pub fn clear(&mut self)

Clear the tree and zero every node.

Note: Does not clear the arena. See also clear_arena.

pub fn clear_arena(&mut self)

Clear the internal string arena.

pub fn resolve(&mut self) -> Result<(), Error>

Resolve references (aliases <- anchors) in the tree.

Dereferencing is opt-in; after parsing, Tree::resolve() has to be called explicitly for obtaining resolved references in the tree. This method will resolve all references and substitute the anchored values in place of the reference.

This method first does a full traversal of the tree to gather all anchors and references in a separate collection, then it goes through that collection to locate the names, which it does by obeying the YAML standard diktat that “an alias node refers to the most recent node in the serialization having the specified anchor”

So, depending on the number of anchor/alias nodes, thit is a potentially expensive operation, with a best-case linear complexity (from the initial traversal). This potential cost is the reason for requiring an explicit call.

pub fn node_type(&self, node: usize) -> Result<NodeType, Error>

Get the type of the given node, if it exists.

pub fn node_type_as_str(&self, node: usize) -> Result<&str, Error>

Get the type name of the given node, if it exists.

pub fn key(&self, node: usize) -> Result<&str, Error>

Get the text of the given node, if it exists and is a key.

pub fn key_tag(&self, node: usize) -> Result<&str, Error>

Get the text of the tag on the key of the given node, if it exists and is a tagged key.

pub fn key_ref(&self, node: usize) -> Result<&str, Error>

Get the text of the reference on the key of the given node, if it exists and is a reference.

pub fn key_anchor(&self, node: usize) -> Result<&str, Error>

Get the text of the anchor on the key of the given node, if it exists and is an anchor.

pub fn key_scalar(&self, node: usize) -> Result<&NodeScalar<'_>, Error>

Get the whole scalar key of the given node, if it exists and is a scalar key.

pub fn val(&self, node: usize) -> Result<&str, Error>

Get the text of the given node, if it exists and is a value.

pub fn val_tag(&self, node: usize) -> Result<&str, Error>

Get the text of the tag on the value of the given node, if it exists and is a tagged value.

pub fn val_ref(&self, node: usize) -> Result<&str, Error>

Get the text of the reference on the value of the given node, if it exists and is a reference.

pub fn val_anchor(&self, node: usize) -> Result<&str, Error>

Get the text of the anchor on the value of the given node, if it exists and is an anchor.

pub fn val_scalar(&self, node: usize) -> Result<&NodeScalar<'_>, Error>

Get the whole scalar value of the given node, if it exists and is a scalar value.

pub fn is_root(&self, node: usize) -> Result<bool, Error>

If the given node exists, returns true if it is a root.

pub fn is_stream(&self, node: usize) -> Result<bool, Error>

If the given node exists, returns true if it is a stream.

pub fn is_doc(&self, node: usize) -> Result<bool, Error>

If the given node exists, returns true if it is a doc.

pub fn is_container(&self, node: usize) -> Result<bool, Error>

If the given node exists, returns true if it is a container.

pub fn is_map(&self, node: usize) -> Result<bool, Error>

If the given node exists, returns true if it is a map.

pub fn is_seq(&self, node: usize) -> Result<bool, Error>

If the given node exists, returns true if it is a seq.

pub fn has_val(&self, node: usize) -> Result<bool, Error>

If the given node exists, returns true if it has a value.

pub fn has_key(&self, node: usize) -> Result<bool, Error>

If the given node exists, returns true if it has a key.

pub fn is_val(&self, node: usize) -> Result<bool, Error>

If the given node exists, returns true if it is a value.

pub fn is_keyval(&self, node: usize) -> Result<bool, Error>

If the given node exists, returns true if it is a keyval.

pub fn has_key_tag(&self, node: usize) -> Result<bool, Error>

If the given node exists, returns true if it has a tagged key.

pub fn has_val_tag(&self, node: usize) -> Result<bool, Error>

If the given node exists, returns true if it has a tagged value.

pub fn has_key_anchor(&self, node: usize) -> Result<bool, Error>

If the given node exists, returns true if it has an anchor key.

pub fn has_val_anchor(&self, node: usize) -> Result<bool, Error>

If the given node exists, returns true if it has an anchor value.

pub fn is_key_ref(&self, node: usize) -> Result<bool, Error>

If the given node exists, returns true if it is a key_ref.

pub fn is_val_ref(&self, node: usize) -> Result<bool, Error>

If the given node exists, returns true if it is a val_ref.

pub fn is_ref(&self, node: usize) -> Result<bool, Error>

If the given node exists, returns true if it is a ref.

pub fn is_anchor_or_ref(&self, node: usize) -> Result<bool, Error>

If the given node exists, returns true if it is a anchor_or_ref.

pub fn is_key_quoted(&self, node: usize) -> Result<bool, Error>

If the given node exists, returns true if it is a key_quoted.

pub fn is_val_quoted(&self, node: usize) -> Result<bool, Error>

If the given node exists, returns true if it is a val_quoted.

pub fn is_quoted(&self, node: usize) -> Result<bool, Error>

If the given node exists, returns true if it is a quoted.

pub fn is_anchor(&self, node: usize) -> Result<bool, Error>

If the given node exists, returns true if it is a anchor.

pub fn parent_is_seq(&self, node: usize) -> Result<bool, Error>

If the given node exists, returns true if the parent is a sequence.

pub fn parent_is_map(&self, node: usize) -> Result<bool, Error>

If the given node exists, returns true if the parent is a map.

pub fn is_node_empty(&self, node: usize) -> Result<bool, Error>

If the given node exists, returns true if it is empty.

pub fn has_anchor(&self, node: usize, anchor: &str) -> Result<bool, Error>

If the given node exists, returns true if it has an anchor.

pub fn has_parent(&self, node: usize) -> Result<bool, Error>

If the given node exists, returns true if it has a parent.

pub fn has_child(&self, node: usize, key: &str) -> Result<bool, Error>

If the given node exists, returns true if it has a child.

pub fn has_children(&self, node: usize) -> Result<bool, Error>

If the given node exists, returns true if it has children.

pub fn has_sibling(&self, node: usize, key: &str) -> Result<bool, Error>

If the given node exists, returns true if it has a sibling.

pub fn has_siblings(&self, node: usize) -> Result<bool, Error>

If the given node exists, returns true if it has siblings.

Note: This corresponds to has_other_siblings() in the C++ API, as the plain has_siblings() function always returns true by counting the node itself, which seems rather pointless and is not the obvious meaning of a method by the name.

pub fn parent(&self, node: usize) -> Result<usize, Error>

If the given node exists and has a parent, returns the parent node.

pub fn prev_sibling(&self, node: usize) -> Result<usize, Error>

If the given node exists and has a previous sibling, returns the index to the sibling node.

pub fn next_sibling(&self, node: usize) -> Result<usize, Error>

If the given node exists and has a next sibling, returns the index to the sibling node.

pub fn num_children(&self, node: usize) -> Result<usize, Error>

If the given node exists and has children, returns the number of children.

pub fn child_pos(&self, node: usize, child: usize) -> Result<usize, Error>

If the given node exists and has the given child, returns the position of the child in the parent node.

pub fn first_child(&self, node: usize) -> Result<usize, Error>

If the given node exists and has children, returns the index of the first child node.

pub fn last_child(&self, node: usize) -> Result<usize, Error>

If the given node exists and has children, returns the index to the last child node.

pub fn child_at(&self, node: usize, pos: usize) -> Result<usize, Error>

If the given node exists and has a child at the given position, returns the index to the child node.

pub fn find_child(&self, node: usize, key: &str) -> Result<usize, Error>

If the given node exists and has a child at the given key, returns the index to the child node.

pub fn num_siblings(&self, node: usize) -> Result<usize, Error>

If the given node exists and has siblings, returns the number of siblings.

pub fn num_other_siblings(&self, node: usize) -> Result<usize, Error>

If the given node exists and has other siblings, returns the number of other siblings.

pub fn sibling_pos(&self, node: usize, sibling: usize) -> Result<usize, Error>

If the given node exists and has the given sibling, get position of the sibling in in the parent.

pub fn first_sibling(&self, node: usize) -> Result<usize, Error>

If the given node exists and has siblings, returns the index to the first sibling node.

pub fn last_sibling(&self, node: usize) -> Result<usize, Error>

If the given node exists and has siblings, returns the index to the last sibling node.

pub fn sibling_at(&self, node: usize, pos: usize) -> Result<usize, Error>

If the given node exists and has a sibling as the given position, returns the index to the sibling node.

pub fn find_sibling(&self, node: usize, key: &str) -> Result<usize, Error>

If the given node exists and has a sibling at the given key, returns the index to the sibling node.

pub fn to_keyval(&mut self, node: usize, key: &str, val: &str) -> Result<(), Error>

Turn the given node into a key-value pair.

pub fn to_keyval_with_flags(
    &mut self,
    node: usize,
    key: &str,
    val: &str,
    more_flags: NodeType
) -> Result<(), Error>

Turn the given node into a key-value pair with additional flags.

pub fn to_map_by_key(&mut self, node: usize, key: &str) -> Result<(), Error>

Turn the given node with the given key into a map.

pub fn to_map_with_key_and_flags(
    &mut self,
    node: usize,
    key: &str,
    more_flags: NodeType
) -> Result<(), Error>

Turn the given node with the given key into a map with additional flags.

pub fn to_seq_by_key(&mut self, node: usize, key: &str) -> Result<(), Error>

Turn the given node with the given key into a sequence.

pub fn to_seq_with_key_and_flags(
    &mut self,
    node: usize,
    key: &str,
    more_flags: NodeType
) -> Result<(), Error>

Turn the given node with the given key into a sequence with additional flags.

pub fn to_val(&mut self, node: usize, val: &str) -> Result<(), Error>

Turn the given node into a value.

pub fn to_val_with_flags(
    &mut self,
    node: usize,
    val: &str,
    more_flags: NodeType
) -> Result<(), Error>

Turn the given node into a value with additional flags.

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

Turn the given node into a stream.

pub fn to_stream_with_flags(
    &mut self,
    node: usize,
    more_flags: NodeType
) -> Result<(), Error>

Turn the given node into a stream with additional flags.

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

Turn the given node into a map.

pub fn to_map_with_flags(
    &mut self,
    node: usize,
    more_flags: NodeType
) -> Result<(), Error>

Turn the given node into a map with additional flags.

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

Turn the given node into a sequence.

pub fn to_seq_with_flags(
    &mut self,
    node: usize,
    more_flags: NodeType
) -> Result<(), Error>

Turn the given node into a sequence with additional flags.

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

Turn the given node into a doc.

pub fn to_doc_with_flags(
    &mut self,
    node: usize,
    more_flags: NodeType
) -> Result<(), Error>

Turn the given node into a doc with additional flags.

pub fn set_key_tag(&mut self, node: usize, tag: &str) -> Result<(), Error>

Set the tag on the key of the given node.

pub fn set_key_anchor(&mut self, node: usize, anchor: &str) -> Result<(), Error>

Set the anchor on the key of the given node.

pub fn set_val_anchor(&mut self, node: usize, anchor: &str) -> Result<(), Error>

Set the anchor on the value of the given node.

pub fn set_key_ref(&mut self, node: usize, refr: &str) -> Result<(), Error>

Set the ref on the key of the given node.

pub fn set_val_ref(&mut self, node: usize, refr: &str) -> Result<(), Error>

Set the ref on the value of the given node.

pub fn set_val_tag(&mut self, node: usize, tag: &str) -> Result<(), Error>

Set the tag on the value of the given node.

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

Remove the anchor on the key of the given node.

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

Remove the anchor on the value of the given node.

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

Remove the reference on the key of the given node.

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

Remove the reference on the value of the given node.

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

Remove the reference on the anchor of the given node.

pub fn insert_child(
    &mut self,
    parent: usize,
    after: usize
) -> Result<usize, Error>

Insert a new node as the child of the given parent at the given position, returning its index.

pub fn prepend_child(&mut self, parent: usize) -> Result<usize, Error>

Insert a new node as the first child of the given parent, returning its index.

pub fn append_child(&mut self, parent: usize) -> Result<usize, Error>

Insert a new node as the last child of the given parent, returning its index.

pub fn insert_sibling(
    &mut self,
    node: usize,
    after: usize
) -> Result<usize, Error>

Insert a new node as the sibling of the given node, returning its index.

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

Insert a new node as the first sibling of the given node, returning its index.

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

Insert a new node as the last sibling of the given node, returning its index.

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

Remove the given node from its parent, including any children.

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

Remove all children from a given node, leaving the node itself.

pub fn reorder(&mut self) -> Result<(), Error>

Reorder the tree in memory so that all the nodes are stored in a linear sequence when visited in depth-first order. This will invalidate existing ids/indicies, since the node id is its position in the node array.

pub fn change_type(
    &mut self,
    node: usize,
    new_type: NodeType
) -> Result<bool, Error>

Change the type of a node, resetting its contents if necessary and returning whether the change was possible.

pub fn duplicate(
    &mut self,
    node: usize,
    new_parent: usize,
    after: usize
) -> Result<usize, Error>

Recursively duplicate the given node, returning the index to the duplicate.

pub fn duplicate_from_tree(
    &mut self,
    tree: &Self,
    node: usize,
    parent: usize,
    after: usize
) -> Result<usize, Error>

Recursively duplicate the given node from a different tree, returning the index to the duplicate.

pub fn duplicate_children(
    &mut self,
    node: usize,
    parent: usize,
    after: usize
) -> Result<usize, Error>

Recursively duplicate the children of the given node (but not the node itself), returning the index of the last duplicated child.

pub fn duplicate_children_from_tree(
    &mut self,
    tree: &Self,
    node: usize,
    parent: usize,
    after: usize
) -> Result<usize, Error>

Recursively duplicate the children of the given node (but not the node itself) from a different tree, returning the index of the last duplicated child.

pub fn duplicate_contents(
    &mut self,
    node: usize,
    dest_index: usize
) -> Result<(), Error>

Duplicate the contents of a given node to the given index.

pub fn duplicate_contents_from_tree(
    &mut self,
    tree: &Self,
    node: usize,
    dest_index: usize
) -> Result<(), Error>

Duplicate the contents of a given node from another tree to the given index.

pub fn duplicate_children_no_rep(
    &mut self,
    node: usize,
    parent: usize,
    after: usize
) -> Result<usize, Error>

Duplicate the node’s children (but not the node) in a new parent, but omit repetitions where a duplicated node has the same key (in maps) or value (in sequences). If one of the duplicated children has the same key (in maps) or value (in sequences) as one of the parent’s children, the one that is placed closest to the end will prevail.

pub fn move_node(&mut self, node: usize, after: usize) -> Result<(), Error>

Change the node’s position in the parent.

pub fn move_node_to_new_parent(
    &mut self,
    node: usize,
    new_parent: usize,
    after: usize
) -> Result<(), Error>

Change the node’s parent and position.

pub fn move_node_from_tree(
    &mut self,
    tree: &mut Self,
    node: usize,
    new_parent: usize,
    after: usize
) -> Result<usize, Error>

Change the node’s parent (in a different tree) and position, returning the new index.

Trait Implementations

impl<'s, 't> AsMut<Tree<'s>> for Tree<'s> where
    's: 't, 

fn as_mut(&mut self) -> &mut Tree<'s>

Converts this type into a mutable reference of the (usually inferred) input type.

impl<'s, 't> AsRef<Tree<'s>> for Tree<'s> where
    's: 't, 

fn as_ref(&self) -> &Tree<'s>

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for Tree<'_>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Tree<'_>

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

Formats the value using the given formatter.

impl Default for Tree<'_>

fn default() -> Self

Returns the “default value” for a type.

impl PartialEq<Tree<'_>> for Tree<'_>

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl Eq for Tree<'_>