Struct Tree

Source

pub struct Tree<T, F>where
    T: Copy,
    F: Flavor,
{ /* private fields */ }

Expand description

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§

Source §

impl<T, F> Tree<T, F>
where T: Copy, F: Flavor,

Source

pub const fn span(&self) -> &Span<F::Index>

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));

Source

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);

Source

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());

Source

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);

Source

pub fn children(&self) -> Children<'_, T, F> ⓘ

Get all root nodes in the tree.

See Children for documentation.

Source

pub fn walk(&self) -> Walk<'_, T, F> ⓘ

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

See Walk for documentation.

Source

pub fn walk_events(&self) -> WalkEvents<'_, T, F> ⓘ

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

See WalkEvents for documentation.

Source

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

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");

Source

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

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");

Source

pub fn get(&self, id: F::Pointer) -> Option<Node<'_, T, F>>

Get the ndoe at the given index.

Note that an id might be re-used across different trees. This behavior is never unsafe, but is not well-defined.

§Examples

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

let node = tree.first().and_then(|n| n.last()).ok_or("missing ident")?;
assert_eq!(node.value(), "ident");

let id = node.id();
let node = tree.get(id).ok_or("missing ident")?;
assert_eq!(node.value(), "ident");

Source

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);

Source

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

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");

Source

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

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");