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. This representation is sometimes called a "balanced parenthesis tree."

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.