Trait SyntaxTree 

pub trait SyntaxTree: Identifiable {
    type Node: Node;
    type NodeIterator<'tree>: Iterator<Item = NodeRef> + FusedIterator + 'tree
       where Self: 'tree;
    type ErrorIterator<'tree>: Iterator<Item = ErrorRef> + FusedIterator + 'tree
       where Self: 'tree;

    // Required methods
    fn root_node_ref(&self) -> NodeRef;
    fn node_refs(&self) -> Self::NodeIterator<'_>;
    fn error_refs(&self) -> Self::ErrorIterator<'_>;
    fn has_node(&self, entry: &Entry) -> bool;
    fn get_node(&self, entry: &Entry) -> Option<&Self::Node>;
    fn get_node_mut(&mut self, entry: &Entry) -> Option<&mut Self::Node>;
    fn has_error(&self, entry: &Entry) -> bool;
    fn get_error(&self, entry: &Entry) -> Option<&SyntaxError>;

    // Provided methods
    fn root(&self) -> &Self::Node
       where Self: Sized { ... }
    fn nodes(&self) -> NodeIter<'_, Self> 
       where Self: Sized { ... }
    fn errors(&self) -> ErrorIter<'_, Self> 
       where Self: Sized { ... }
    fn traverse_tree(&self, visitor: &mut impl Visitor)
       where Self: Sized { ... }
    fn traverse_subtree(&self, top: &NodeRef, visitor: &mut impl Visitor)
       where Self: Sized { ... }
}

An object that provides access to the syntax structure of a compilation unit.

The syntax structure consists of a set of nodes forming an abstract syntax tree, and a set of syntax errors that may occur during parsing or incremental reparsing.

In Lady Deirdre, instances of these objects are owned by the compilation units, rather than by the syntax tree nodes. This ownership structure allows compilation units to have full control over the syntax structure, especially for the purpose of incremental reparsing.

Syntax tree nodes reference their children, parents, and other nodes through a system of versioned indices (Entry).

This trait provides a low-level interface to borrow instance of syntax nodes and the syntax errors by index from the compilation unit.

Higher-level referential objects, such as NodeRef and ErrorRef, offer a more convenient interface for borrowing these objects from the SyntaxTree.

Additionally, the SyntaxTree interface provides higher-level functions to retrieve the syntax tree root node, iterate through all nodes and errors currently managed by the compilation unit, and perform a depth-first traversal of the syntax tree.

Typically, manual implementation of this trait is unnecessary unless creating a new type of compilation unit manager.

To create a wrapper of an existing compilation unit, a Syntax facade-interface can be utilized, which auto-implements this trait through delegation.

Required Associated Types

type Node: Node

Specifies the type of the tree node.

Node::Token inherently specifies the lexical grammar of the language.

Node::parse inherently specifies the syntax parser of the language.

type NodeIterator<'tree>: Iterator<Item = NodeRef> + FusedIterator + 'tree where Self: 'tree

Specifies the type of the iterator that walks through all node NodeRef references currently managed by this SyntaxTree instance.

type ErrorIterator<'tree>: Iterator<Item = ErrorRef> + FusedIterator + 'tree where Self: 'tree

Specifies the type of the iterator that walks through all syntax error ErrorRef references currently managed by this SyntaxTree instance.

Required Methods

fn root_node_ref(&self) -> NodeRef

Returns a NodeRef reference to the root node of this syntax tree.

fn node_refs(&self) -> Self::NodeIterator<'_>

Returns an iterator of the NodeRef references over all nodes currently managed by this syntax tree.

The order of iteration is not specified.

fn error_refs(&self) -> Self::ErrorIterator<'_>

Returns an iterator of the ErrorRef references over all syntax errors currently managed by this syntax tree.

The order of iteration is not specified.

fn has_node(&self, entry: &Entry) -> bool

Checks if the node referred to by the versioned index exists in this syntax tree.

fn get_node(&self, entry: &Entry) -> Option<&Self::Node>

Provides immutable access to the node referred to by the versioned index.

If the index parameter entry is not valid, returns None.

fn get_node_mut(&mut self, entry: &Entry) -> Option<&mut Self::Node>

Provides mutable access to the node referred to by the versioned index.

If the index parameter entry is not valid, returns None.

fn has_error(&self, entry: &Entry) -> bool

Checks if the syntax error referred to by the versioned index exists in this syntax tree.

fn get_error(&self, entry: &Entry) -> Option<&SyntaxError>

Provides access to the syntax error referred to by the versioned index.

If the index parameter entry is not valid, returns None.

Provided Methods

fn root(&self) -> &Self::Node

where Self: Sized,

Provides access to the root node of the syntax tree.

Panic

Depending on the implementation, this function may panic if the SyntaxTree does not have a root node.

However, all objects within this crate that implement the SyntaxTree trait always have the root node regardless of the input. Therefore, they would never panic.

fn nodes(&self) -> NodeIter<'_, Self>

where Self: Sized,

Returns an iterator over all nodes currently managed by this syntax tree.

The order of iteration is not specified.

fn errors(&self) -> ErrorIter<'_, Self>

where Self: Sized,

Returns an iterator over all syntax errors currently managed by this syntax tree.

The order of iteration is not specified.

fn traverse_tree(&self, visitor: &mut impl Visitor)

where Self: Sized,

Performs a depth-first traverse of the syntax tree starting from the root node.

The visitor object will be called on each node entering and leaving events, as well as the token entering event.

The traverse algorithm will not visit descending nodes of the tree branch if the Visitor::enter_node returns false. Thus, the visitor can control the descending process.

The algorithm relies on the AbstractNode::children_iter function to determine the node’s children to descend to, which in turn relies on the node’s captures description.

In other words, the traverser will only visit the nodes for which you have specified #[child] attribute:

#[derive(Node)]
enum MyNode {
    #[rule(...)]
    SomeVariant {
        #[child]
        child_1: NodeRef, // will be visited
        #[child]
        child_2: NodeRef, // will be visited
        not_a_child: NodeRef, // will not be visited
    }
}

fn traverse_subtree(&self, top: &NodeRef, visitor: &mut impl Visitor)

where Self: Sized,

Performs a depth-first traverse of a branch of the syntax tree.

The top parameter specifies a reference into the top node of the branch.

For details, see SyntaxTree::traverse_tree.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl<F: Syntax> SyntaxTree for F

type Node = <<F as Syntax>::Syntax as SyntaxTree>::Node

type NodeIterator<'tree> = <<F as Syntax>::Syntax as SyntaxTree>::NodeIterator<'tree> where Self: 'tree

type ErrorIterator<'tree> = <<F as Syntax>::Syntax as SyntaxTree>::ErrorIterator<'tree> where Self: 'tree

impl<N: Node> SyntaxTree for Document<N>

type Node = N

type NodeIterator<'document> = DocumentNodeIter<'document, N>

type ErrorIterator<'document> = DocumentErrorIter<'document, N>

impl<N: Node> SyntaxTree for ImmutableSyntaxTree<N>

type Node = N

type NodeIterator<'tree> = NodeIter

type ErrorIterator<'tree> = ErrorIter

impl<N: Node> SyntaxTree for MutableUnit<N>

type Node = N

type NodeIterator<'tree> = MutableNodeIter<'tree, N>

type ErrorIterator<'tree> = MutableErrorIter<'tree>