Struct ParseTree 

pub struct ParseTree<C> { /* private fields */ }

A tree of source regions grown by the Engine.

The root covers the whole program; each node holds a Span, a context value C, and a Status. The engine grows the tree round by round: every Unparsed node (and every Failed node with passes left) is offered to the pass scheduled for its round, which either expands it into children, accepts it, or fails it for a later pass to retry.

Nodes are stored in an arena and referenced by stable NodeIds, which makes incremental re-parses (invalidating only subtrees overlapping an edit) straightforward in a future revision.

Examples

use increparse::{ParseTree, Span};

let tree: ParseTree<()> = ParseTree::new(0, Span::new(0, 11, 0), ());
assert_eq!(tree.len(), 1);
assert_eq!(tree.status(tree.root()), increparse::Status::Unparsed);

Implementations

impl<C> ParseTree<C>

pub fn new(source_rev: u64, root_span: Span, root_ctx: C) -> ParseTree<C>

Creates a tree whose root covers root_span of source revision source_rev, carrying root_ctx.

pub fn from_source(source: &str, source_rev: u64, root_ctx: C) -> ParseTree<C>

Creates a tree whose root covers all of source at revision source_rev — the common case, with no hand-built root span.

pub fn node_at(&self, offset: usize) -> Option<NodeId>

The deepest node whose span contains offset — the natural query behind hover, go-to-definition, and friends.

Containment is half-open: offset must satisfy span.start <= offset < span.end, so zero-width regions never match and clicking the last byte of a region still finds it. Ties between equal-span siblings go to the first child.

Returns None if the offset is outside the root’s span.

Panics

Panics if the root is not part of this tree (cannot happen for trees built through the public API).

pub fn source_rev(&self) -> u64

The source revision this tree was built against.

pub fn root(&self) -> NodeId

The root node.

pub fn len(&self) -> usize

Total number of live nodes in the tree.

pub fn is_empty(&self) -> bool

Returns true if the tree has no nodes at all.

A freshly constructed tree always contains its root, so this is only observable on trees built through interior paths; it exists to pair with len.

pub fn is_root_only(&self) -> bool

Returns true if the tree contains only the root.

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

The region of the source covered by id.

Panics

Panics if id is not part of this tree.

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

The context carried by id.

Panics

Panics if id is not part of this tree.

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

The lifecycle status of id.

Panics

Panics if id is not part of this tree.

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

The round index id will be (or was last) processed at.

Panics

Panics if id is not part of this tree.

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

How many passes have tried and failed to parse id.

Panics

Panics if id is not part of this tree.

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

The parent of id, or None for the root.

Panics

Panics if id is not part of this tree.

pub fn children(&self, id: NodeId) -> &[NodeId]

The children of id, in the order the pass produced them.

Panics

Panics if id is not part of this tree.

pub fn nodes(&self) -> impl Iterator<Item = NodeId>

An iterator over every live node id in the tree, in creation order.

Nodes dropped by an incremental re-parse (see edit) are not yielded; their ids remain reserved and must not be reused.

pub fn text<'a>(&self, source: &'a str, id: NodeId) -> &'a str

The slice of source covered by id.

Panics

Panics if id is not part of this tree, or if the node’s span is out of bounds for source.

pub fn edit(&mut self, edit: Edit)

Applies a text edit in place: every live span is remapped into the new coordinates and tagged with a fresh source revision, and every node the edit could have changed is reset to Unparsed for re-parsing on the next run.

A touched node restarts at its home round (the round whose pass first processed it), with its failure history cleared — edited text gets a genuinely fresh chance at every pass, including ones it had previously exhausted.

Touched nodes keep their children attached: the next run re-expands their parents and matches the new children against the old ones, so unchanged regions are reused instead of re-parsed (see the Session docs).

pub fn status_counts(&self) -> StatusCounts

Per-status node counts for the whole tree (live nodes only).

pub fn is_pending(&self, id: NodeId, max_rounds: usize) -> bool

Returns true if id still has work a pass could do within max_rounds rounds: it is Unparsed, or Failed with a retry left in the schedule.

Panics

Panics if id is not part of this tree.

pub fn is_settled(&self, id: NodeId, max_rounds: usize) -> bool

Returns true if id and all of its descendants have no work left within max_rounds rounds.

Panics

Panics if id is not part of this tree.

pub fn pending(&self, max_rounds: usize) -> Vec<NodeId>

Every node id with work remaining within max_rounds rounds.

Trait Implementations

impl<C> Debug for ParseTree<C>

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

Formats the value using the given formatter.