Struct syntree::Tree

pub struct Tree<T, I, W>where
    I: Index,
    W: Width,{ /* private fields */ }

A syntax tree.

A tree is constructed through a Builder or by modifying an existing tree through a ChangeSet.

Type parameters and bounds

The three type parameters of the tree determines the following properties:

• T is the data stored in the tree.
• I determines the numerical bounds of spans stored in the tree through the Index trait, if set to Empty the tree does not store any spans.
• W determines the bounds of pointers in the tree through the Width trait, this decides how many elements that can be stored in the tree.

To use the default values, use the Builder::new constructor.

Implementations

impl<T, I, W> Tree<T, I, W>where I: Index, W: Width,

pub const fn span(&self) -> &Span<I>

Get the span of the current node. The span of a node is the complete span of all its children.

Examples

use syntree::Span;

let tree = syntree::tree! {
    "root" => {
        "number" => {
            ("lit", 5)
        },
        "ident" => {
            ("lit", 3)
        }
    },
    "root2" => {
        ("whitespace", 5)
    }
};

assert_eq!(tree.span(), Span::new(0, 13));

pub fn len(&self) -> usize

The total number of elements in the tree.

Examples

let mut tree: syntree::Builder<(), _, _> = syntree::Builder::new();
let tree = tree.build()?;

assert_eq!(tree.len(), 0);

let mut tree = syntree::tree! {
    "root" => {
        "child" => {
            ("token", 2)
        },
        ("whitespace", 1),
        "child2" => {}
    }
};

assert_eq!(tree.len(), 5);

pub fn is_empty(&self) -> bool

Check if the current tree is empty. In that it doesn’t have any childrens at the root of the tree.

Examples

let mut tree: syntree::Builder<(), _, _> = syntree::Builder::new();
let tree = tree.build()?;
assert!(tree.is_empty());

pub fn capacity(&self) -> usize

Get the capacity of the tree.

Examples

let mut tree: syntree::Builder<(), _, _> = syntree::Builder::new();
let tree = tree.build()?;

assert_eq!(tree.capacity(), 0);

let mut tree = syntree::tree! {
    "root" => {
        "child" => {
            ("token", 2)
        },
        ("whitespace", 1),
        "child2" => {}
    }
};

assert!(tree.capacity() >= 5);

pub fn children(&self) -> Children<'_, T, I, W>

Get all root nodes in the tree.

See Children for documentation.

pub fn walk(&self) -> Walk<'_, T, I, W>

Walk the tree forwards in a depth-first fashion visiting every node once.

See Walk for documentation.

pub fn walk_events(&self) -> WalkEvents<'_, T, I, W>

Walk the tree forwards in a depth-first fashion emitting events indicating how the tree is being traversed.

See WalkEvents for documentation.

pub fn first(&self) -> Option<Node<'_, T, I, W>>

Get the first child node in the tree.

Examples

let tree = syntree::tree! {
    "root" => {},
    "root2" => {}
};

let root = tree.first().ok_or("missing root")?;
assert_eq!(*root.value(), "root");

pub fn last(&self) -> Option<Node<'_, T, I, W>>

Get the last child node in the tree.

Examples

let tree = syntree::tree! {
    "root" => {},
    "root2" => {}
};

let root = tree.last().ok_or("missing root")?;
assert_eq!(*root.value(), "root2");

pub fn range(&self) -> Range<usize>

Access the Span of the node as a Range.

Examples

let tree = syntree::tree! {
    "root" => {
        "number" => {
            ("lit", 5)
        },
        "ident" => {
            ("lit", 3)
        }
    },
    "root2" => {
        ("whitespace", 5)
    }
};

assert_eq!(tree.range(), 0..13);

pub fn node_with_range(&self, span: Range<usize>) -> Option<Node<'_, T, I, W>>

Query for the node that matches the given range.

This query finds the node which contains the entirety of the given Range.

Examples

let tree = syntree::tree! {
    "root" => {
        "child1" => {
            ("token1", 3)
        },
        "child2" => {
            "nested1" => {
                ("token1", 4),
            },
            ("token4", 1),
        },
        "child3" => {
            ("token5", 5)
        }
    },
    "root2" => {}
};

let node = tree.node_with_range(0..0).ok_or("missing 0")?;
assert_eq!(*node.value(), "child1");

let node = tree.node_with_range(0..3).ok_or("missing 0")?;
assert_eq!(*node.value(), "child1");

let node = tree.node_with_range(3..3).ok_or("missing 3")?;
assert_eq!(*node.value(), "nested1");

let node = tree.node_with_range(3..7).ok_or("missing 3..7")?;
assert_eq!(*node.value(), "nested1");

let node = tree.node_with_range(7..7).ok_or("missing 7")?;
assert_eq!(*node.value(), "child2");

let node = tree.node_with_range(7..8).ok_or("missing 7..8")?;
assert_eq!(*node.value(), "child2");

let node = tree.node_with_range(8..8).ok_or("missing 8")?;
assert_eq!(*node.value(), "child3");

let node = tree.node_with_range(8..13).ok_or("missing 9")?;
assert_eq!(*node.value(), "child3");

let node = tree.node_with_range(2..4).ok_or("missing 2..4")?;
assert_eq!(*node.value(), "root");

Range queries work as expected with checkpoints:

let mut tree = syntree::Builder::new();

let c = tree.checkpoint()?;
tree.open("child")?;
tree.token("lit", 3)?;
tree.close()?;
tree.close_at(&c, "root")?;
tree.token("sibling", 3)?;

let tree = tree.build()?;

let child = tree.node_with_range(0..3).ok_or("missing at 0..3")?;
assert_eq!(*child.value(), "child");

pub fn node_with_span(&self, span: Span<I>) -> Option<Node<'_, T, I, W>>

Query the tree for the first node which encapsulates the whole span.

This query finds the node which contains the entirety of the given Span.

Examples

use syntree::Span;

let tree = syntree::tree! {
    "root" => {
        "child1" => {
            ("token1", 3)
        },
        "child2" => {
            "nested1" => {
                ("token1", 4),
            },
            ("token4", 1),
        },
        "child3" => {
            ("token5", 5)
        }
    },
    "root2" => {}
};

let node = tree.node_with_span(Span::point(0)).ok_or("missing 0")?;
assert_eq!(*node.value(), "child1");

let node = tree.node_with_span(Span::new(0, 3)).ok_or("missing 0")?;
assert_eq!(*node.value(), "child1");

let node = tree.node_with_span(Span::point(3)).ok_or("missing 3")?;
assert_eq!(*node.value(), "nested1");

let node = tree.node_with_span(Span::new(3, 7)).ok_or("missing 3..7")?;
assert_eq!(*node.value(), "nested1");

let node = tree.node_with_span(Span::point(7)).ok_or("missing 7")?;
assert_eq!(*node.value(), "child2");

let node = tree.node_with_span(Span::new(7, 8)).ok_or("missing 7..8")?;
assert_eq!(*node.value(), "child2");

let node = tree.node_with_span(Span::point(8)).ok_or("missing 8")?;
assert_eq!(*node.value(), "child3");

let node = tree.node_with_span(Span::new(8, 13)).ok_or("missing 9")?;
assert_eq!(*node.value(), "child3");

let node = tree.node_with_span(Span::new(2, 4)).ok_or("missing 2..4")?;
assert_eq!(*node.value(), "root");

Range queries work as expected with checkpoints:

use syntree::{Span, Builder};

let mut tree = Builder::new();

let c = tree.checkpoint()?;

tree.open("child1")?;
tree.token("lit", 3)?;
tree.close()?;

tree.open("child2")?;
tree.token("lit", 2)?;
tree.close()?;

tree.close_at(&c, "root")?;

let tree = tree.build()?;

let child = tree.node_with_span(Span::point(0)).ok_or("missing at point 5")?;
assert_eq!(*child.value(), "child1");

let child = tree.node_with_span(Span::new(0, 3)).ok_or("missing at 0..3")?;
assert_eq!(*child.value(), "child1");

let child = tree.node_with_span(Span::new(3, 5)).ok_or("missing at 3..5")?;
assert_eq!(*child.value(), "child2");

let child = tree.node_with_span(Span::new(4, 5)).ok_or("missing at 4..5")?;
assert_eq!(*child.value(), "child2");

let child = tree.node_with_span(Span::new(3, 4)).ok_or("missing at 3..4")?;
assert_eq!(*child.value(), "child2");

let child = tree.node_with_span(Span::point(3)).ok_or("missing at point 5")?;
assert_eq!(*child.value(), "child2");

let child = tree.node_with_span(Span::new(2, 5)).ok_or("missing at 2..5")?;
assert_eq!(*child.value(), "root");

Trait Implementations

impl<T, I, W> Clone for Tree<T, I, W>where T: Clone, I: Index, I::Indexes<W::Pointer>: Clone, W: Width, W::Pointer: Clone,

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T, I, W> Debug for Tree<T, I, W>where T: Debug, I: Index + Debug, W: Width,

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

Formats the value using the given formatter.

impl<T, I, W> Default for Tree<T, I, W>where I: Index, W: Width,

fn default() -> Self

Returns the “default value” for a type.

impl<T, I, A, B> PartialEq<Tree<T, I, A>> for Tree<T, I, B>where T: PartialEq, I: Index + PartialEq, A: Width, B: Width,

fn eq(&self, other: &Tree<T, I, A>) -> 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 !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T, I, W> Eq for Tree<T, I, W>where T: Eq, I: Index + Eq, W: Width,