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) Children() iter.Seq[Cursor]
• 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 ¶

func Root(in *inspector.Inspector) Cursor

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) Children ¶

func (c Cursor) Children() iter.Seq[Cursor]

Children returns an iterator over the direct children of the current node, if any.

func (Cursor) FindNode ¶

func (c Cursor) FindNode(n ast.Node) (Cursor, bool)

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 ¶

func (c Cursor) FindPos(start, end token.Pos) (Cursor, bool)

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 ¶

func (c Cursor) FirstChild() (Cursor, bool)

FirstChild returns the first direct child of the current node, or zero if it has no children.

func (Cursor) Inspect ¶

func (c Cursor) Inspect(types []ast.Node, f func(c Cursor, push bool) (descend bool))

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 ¶

func (c Cursor) LastChild() (Cursor, bool)

LastChild returns the last direct child of the current node, or zero if it has no children.

func (Cursor) NextSibling ¶

func (c Cursor) NextSibling() (Cursor, bool)

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 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.

func (Cursor) Node ¶

func (c Cursor) Node() ast.Node

Node returns the node at the current cursor position, or nil for the cursor returned by [Inspector.Root].

func (Cursor) Parent ¶

func (c Cursor) Parent() Cursor

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 ¶

func (c Cursor) Preorder(types ...ast.Node) iter.Seq[Cursor]

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 ¶

func (c Cursor) PrevSibling() (Cursor, bool)

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.

func (Cursor) Stack ¶

func (c Cursor) Stack(stack []Cursor) []Cursor

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.

TODO(adonovan): perhaps this should be replaced by:

func (Cursor) Ancestors(filter []ast.Node) iter.Seq[Cursor]

returning a filtering iterator up the parent chain. This finesses the question of allocation entirely.

func (Cursor) String ¶

func (c Cursor) String() string

String returns information about the cursor's node, if any.

Source Files ¶

cursor.go hooks.go