inspector

Documentation

Overview

Package inspector provides helper functions for traversal over the syntax trees of a package, including node filtering by type, and materialization of the traversal stack.

During construction, the inspector does a complete traversal and builds a list of push/pop events and their node type. Subsequent method calls that request a traversal scan this list, rather than walk the AST, and perform type filtering using efficient bit sets.

Experiments suggest the inspector's traversals are about 2.5x faster than ast.Inspect, but it may take around 5 traversals for this benefit to amortize the inspector's construction cost. If efficiency is the primary concern, do not use Inspector for one-off traversals.

Index

• func All[N interface{ ... }, S any](in *Inspector) iter.Seq[N]
• type Inspector
  • func New(files []*ast.File) *Inspector
  • func (in *Inspector) Nodes(types []ast.Node, f func(n ast.Node, push bool) (proceed bool))
  • func (in *Inspector) Preorder(types []ast.Node, f func(ast.Node))
  • func (in *Inspector) PreorderSeq(types ...ast.Node) iter.Seq[ast.Node]
  • func (in *Inspector) WithStack(types []ast.Node, ...)

Functions

func All

func All[N interface {
	*S
	ast.Node
}, S any](in *Inspector) iter.Seq[N]

All[N] returns an iterator over all the nodes of type N. N must be a pointer-to-struct type that implements ast.Node.

Example:

for call := range All[*ast.CallExpr](in) { ... }

Types

type Inspector

type Inspector struct {
	// contains filtered or unexported fields
}

An Inspector provides methods for inspecting (traversing) the syntax trees of a package.

func New

func New(files []*ast.File) *Inspector

New returns an Inspector for the specified syntax trees.

func (*Inspector) Nodes

func (in *Inspector) Nodes(types []ast.Node, f func(n ast.Node, push bool) (proceed bool))

Nodes visits the nodes of the files supplied to New in depth-first order. It calls f(n, true) for each node n before it visits n's children. If f returns true, Nodes invokes f recursively for each of the non-nil children of the node, followed by a call of f(n, false).

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 (*Inspector) Preorder

func (in *Inspector) Preorder(types []ast.Node, f func(ast.Node))

Preorder visits all the nodes of the files supplied to New in depth-first order. It calls f(n) for each node n before it visits n's children.

The complete traversal sequence is determined by ast.Inspect. The types argument, if non-empty, enables type-based filtering of events. The function f is called only for nodes whose type matches an element of the types slice.

func (*Inspector) PreorderSeq

func (in *Inspector) PreorderSeq(types ...ast.Node) iter.Seq[ast.Node]

PreorderSeq returns an iterator that visits all the nodes of the files supplied to New in depth-first order. It visits each node n before n's children. The complete traversal sequence is determined by ast.Inspect.

The types argument, if non-empty, enables type-based filtering of events: only nodes whose type matches an element of the types slice are included in the sequence.

func (*Inspector) WithStack

func (in *Inspector) WithStack(types []ast.Node, f func(n ast.Node, push bool, stack []ast.Node) (proceed bool))

WithStack visits nodes in a similar manner to Nodes, but it supplies each call to f an additional argument, the current traversal stack. The stack's first element is the outermost node, an *ast.File; its last is the innermost, n.