package cursor
import "golang.org/x/tools/internal/astutil/cursor"
Package cursor augments inspector.Inspector with Cursor functionality allowing more flexibility and control during inspection.
This package is a temporary private extension of inspector until proposal #70859 is accepted, and which point it will be moved into the inspector package, and Root will become a method of Inspector.
Index ¶
- type Cursor
- func Root(in *inspector.Inspector) Cursor
- func (c Cursor) Ancestors(types ...ast.Node) iter.Seq[Cursor]
- func (c Cursor) Child(n ast.Node) Cursor
- func (c Cursor) Children() iter.Seq[Cursor]
- func (c Cursor) Edge() (edge.Kind, int)
- func (c Cursor) FindNode(n ast.Node) (Cursor, bool)
- func (c Cursor) FindPos(start, end token.Pos) (Cursor, bool)
- func (c Cursor) FirstChild() (Cursor, bool)
- func (c Cursor) Inspect(types []ast.Node, f func(c Cursor, push bool) (descend bool))
- func (c Cursor) LastChild() (Cursor, bool)
- func (c Cursor) NextSibling() (Cursor, bool)
- func (c Cursor) Node() ast.Node
- func (c Cursor) Parent() Cursor
- func (c Cursor) Preorder(types ...ast.Node) iter.Seq[Cursor]
- func (c Cursor) PrevSibling() (Cursor, bool)
- func (c Cursor) Stack(stack []Cursor) []Cursor
- func (c Cursor) String() string
Types ¶
type Cursor ¶
type Cursor struct {
// contains filtered or unexported fields
}
A Cursor represents an ast.Node. It is immutable.
Two Cursors compare equal if they represent the same node.
Call Root to obtain a valid cursor.
func Root ¶
Root returns a cursor for the virtual root node, whose children are the files provided to [New].
Its Cursor.Node and Cursor.Stack methods return nil.
func (Cursor) Ancestors ¶
Ancestors returns an iterator over the ancestors of the current node, starting with Cursor.Parent.
Ancestors must not be called on the Root node (whose Cursor.Node returns nil).
The types argument, if non-empty, enables type-based filtering of events: the sequence includes only ancestors whose type matches an element of the types slice.
func (Cursor) Child ¶
Child returns the cursor for n, which must be a direct child of c's Node.
Child must not be called on the Root node (whose Cursor.Node returns nil).
func (Cursor) Children ¶
Children returns an iterator over the direct children of the current node, if any.
When using Children, NextChild, and PrevChild, bear in mind that a Node's children may come from different fields, some of which may be lists of nodes without a distinguished intervening container such as ast.BlockStmt.
For example, ast.CaseClause has a field List of expressions and a field Body of statements, so the children of a CaseClause are a mix of expressions and statements. Other nodes that have "uncontained" list fields include:
- ast.ValueSpec (Names, Values) - ast.CompositeLit (Type, Elts) - ast.IndexListExpr (X, Indices) - ast.CallExpr (Fun, Args) - ast.AssignStmt (Lhs, Rhs)
So, do not assume that the previous sibling of an ast.Stmt is also an ast.Stmt, or if it is, that they are executed sequentially, unless you have established that, say, its parent is a BlockStmt or its Cursor.Edge is edge.BlockStmt_List. For example, given "for S1; ; S2 {}", the predecessor of S2 is S1, even though they are not executed in sequence.
func (Cursor) Edge ¶
Edge returns the identity of the field in the parent node that holds this cursor's node, and if it is a list, the index within it.
For example, f(x, y) is a CallExpr whose three children are Idents. f has edge kind edge.CallExpr_Fun and index -1. x and y have kind edge.CallExpr_Args and indices 0 and 1, respectively.
Edge must not be called on the Root node (whose Cursor.Node returns nil).
If called on a child of the Root node, it returns (edge.Invalid, -1).
func (Cursor) FindNode ¶
FindNode returns the cursor for node n if it belongs to the subtree rooted at c. It returns zero if n is not found.
func (Cursor) FindPos ¶
FindPos returns the cursor for the innermost node n in the tree rooted at c such that n.Pos() <= start && end <= n.End(). It returns zero if none is found. Precondition: start <= end.
See also [astutil.PathEnclosingInterval], which tolerates adjoining whitespace.
func (Cursor) FirstChild ¶
FirstChild returns the first direct child of the current node, or zero if it has no children.
func (Cursor) Inspect ¶
Inspect visits the nodes of the subtree represented by c in depth-first order. It calls f(n, true) for each node n before it visits n's children. If f returns true, Inspect invokes f recursively for each of the non-nil children of the node, followed by a call of f(n, false).
Each node is represented by a Cursor that allows access to the Node, but may also be used to start a new traversal, or to obtain the stack of nodes enclosing the cursor.
The complete traversal sequence is determined by ast.Inspect. The types argument, if non-empty, enables type-based filtering of events. The function f if is called only for nodes whose type matches an element of the types slice.
func (Cursor) LastChild ¶
LastChild returns the last direct child of the current node, or zero if it has no children.
func (Cursor) NextSibling ¶
NextSibling returns the cursor for the next sibling node in the same list (for example, of files, decls, specs, statements, fields, or expressions) as the current node. It returns (zero, false) if the node is the last node in the list, or is not part of a list.
NextSibling must not be called on the Root node.
See note at Cursor.Children.
func (Cursor) Node ¶
Node returns the node at the current cursor position, or nil for the cursor returned by [Inspector.Root].
func (Cursor) Parent ¶
Parent returns the parent of the current node.
Parent must not be called on the Root node (whose Cursor.Node returns nil).
func (Cursor) Preorder ¶
Preorder returns an iterator over the nodes of the subtree represented by c in depth-first order. Each node in the sequence is represented by a Cursor that allows access to the Node, but may also be used to start a new traversal, or to obtain the stack of nodes enclosing the cursor.
The traversal sequence is determined by ast.Inspect. The types argument, if non-empty, enables type-based filtering of events. The function f if is called only for nodes whose type matches an element of the types slice.
If you need control over descent into subtrees, or need both pre- and post-order notifications, use Cursor.Inspect
func (Cursor) PrevSibling ¶
PrevSibling returns the cursor for the previous sibling node in the same list (for example, of files, decls, specs, statements, fields, or expressions) as the current node. It returns zero if the node is the first node in the list, or is not part of a list.
It must not be called on the Root node.
See note at Cursor.Children.
func (Cursor) Stack ¶
Stack returns the stack of enclosing nodes, outermost first: from the ast.File down to the current cursor's node.
To amortize allocation, it appends to the provided slice, which must be empty.
Stack must not be called on the Root node.
func (Cursor) String ¶
String returns information about the cursor's node, if any.
Source Files ¶
cursor.go hooks.go
- Version
- v0.30.0 (latest)
- Published
- Feb 10, 2025
- Platform
- linux/amd64
- Imports
- 9 packages
- Last checked
- 8 hours ago –
Tools for package owners.