pub struct Cursor<'a>(/* private fields */);Expand description
An AST cursor.
Implementations§
Source§impl<'a> Cursor<'a>
impl<'a> Cursor<'a>
Sourcepub fn goto_next_sibling(&mut self) -> bool
pub fn goto_next_sibling(&mut self) -> bool
Moves to the next sibling; false when there is none.
Sourcepub fn goto_first_child(&mut self) -> bool
pub fn goto_first_child(&mut self) -> bool
Moves to the first child; false when there is none.
Sourcepub fn goto_first_child_for_byte(&mut self, byte: usize) -> Option<usize>
pub fn goto_first_child_for_byte(&mut self, byte: usize) -> Option<usize>
Moves to the first child that ends after byte and returns its
index in Node::children order, or None when no child does.
“Ends after” is strict, so a zero-width child at byte — a
MISSING token the parser inserted during error recovery — is
skipped and the cursor lands on its successor. That is the one way
this differs from children().position(..), which finds such a
node; a caller resolving a node’s own index must therefore check
Cursor::node against it, as both call sites here do.
The index is what makes this worth having over a sibling scan:
tree-sitter stores a repeat() child list under balanced hidden
nodes and skips each by its cached visible-child count, so this
is O(log n) in the sibling count where children().position(..)
is O(n) — the difference between a linear and a quadratic walk
when every child of a wide list asks for its own index.
Only for such a list. The seek steps through the children in
order and can skip only a hidden subtree, so over a flat child
array — an ERROR that recovery built by skipping tokens has no
hidden levels — it is the same O(index) scan (#1584). So it is
over whatever precedes a repeat() in a node that parsed: the
comments between a list’s opening token and its first element
are the list’s own children, not the repeat’s (#1868).
Sourcepub fn goto_parent(&mut self) -> bool
pub fn goto_parent(&mut self) -> bool
Moves to the parent; false when there is none.
The node the cursor was built on (Node::cursor) or last
reset to is the ceiling: from there this returns
false and leaves the cursor where it is, even when the node has
a parent in the tree. A traversal that descends and climbs back
through one cursor therefore cannot wander above its subtree.
Sourcepub fn field_name(&self) -> Option<&'static str>
pub fn field_name(&self) -> Option<&'static str>
The grammar field through which the parent reaches the node the
cursor currently sits on, or None when it occupies no field —
most punctuation, an extra such as a comment, or the node the
cursor started on, whose parent it cannot see. Anonymous tokens
can sit in a field: a binary_expression’s + is its
operator.
Reflects the cursor’s position: it is answered from the path
the cursor descended, so a field inherited through a hidden
grammar node is resolved the same way Node::field_name_for_child
resolves it — both stop at the nearest visible ancestor and
both answer None for an extra. The two are different
algorithms, though: this one climbs the cursor’s stack and
stops at the first extra entry, while the index lookup
descends and reads the field map at each hidden level. They
agree wherever every extra is a leaf or a visible rule, which
holds for every pinned grammar; a hidden extra wrapper with
visible children is the one shape that could split them.