astquery

README

astquery

astquery selects a node set from AST by XPath.

astquery uses antchfx/xpath. You can see a document of xpath expressions at antchfx/xpath's repository.

You can also use field of a node as an attributes such as @Name for *ast.Ident. In addtion you can use the follows as an attribute:

• @type: type of a node
• @pos: token.Position of a node in string value
• @src: source code representation of a node with "go/format".Node

CLI Tool

Install

$ go get -u github.com/gostaticanalysis/astquery/cmd/astquery

How to use

Select a node set

$ astquery '//*[@type="CallExpr"]/Fun[@type="Ident" and @Name="panic"]' fmt

Select attributes

# Find calling panic in fmt package
$ astquery '//*[@type="CallExpr"]/Fun[@type="Ident" and @Name="panic"]/@pos' fmt
/usr/local/go/src/fmt/format.go:266:3
/usr/local/go/src/fmt/print.go:553:4
/usr/local/go/src/fmt/scan.go:240:2
/usr/local/go/src/fmt/scan.go:244:2
/usr/local/go/src/fmt/scan.go:253:5
/usr/local/go/src/fmt/scan.go:508:3
/usr/local/go/src/fmt/scan.go:1064:4

# Find with src code snipet
$ astquery '//*[starts-with(@src, "panic") and @type="CallExpr"]/@src' fmt
panic("fmt: unknown base; can't happen")
panic(err)
panic(scanError{err})
panic(scanError{errors.New(err)})
panic(e)
panic(io.EOF)
panic(e)

Analyzer

see: examples of analysis.Analyzer

func run(pass *analysis.Pass) (interface{}, error) {
	e := pass.ResultOf[astquery.Analyzer].(*astquery.Evaluator)
	ns, err := e.Select("//*[@type='CallExpr']/Fun[@type='Ident' and @Name='panic']")
	if err != nil {
		return nil, err
	}

	for _, n := range ns {
		pass.Reportf(n.Pos(), "don't panic")
	}

	return nil, nil
}

Documentation

Index

• Variables
• type Evaluator
  • func New(fset *token.FileSet, files []*ast.File, in *inspector.Inspector) *Evaluator
  • func (e *Evaluator) Eval(expr string) (interface{}, error)
  • func (e *Evaluator) Select(expr string) ([]ast.Node, error)
  • func (e *Evaluator) SelectOne(expr string) (ast.Node, error)
• type Inspector
  • func NewInspector(files []*ast.File) *Inspector
  • func (in *Inspector) Children(n ast.Node) []ast.Node
  • func (in *Inspector) Index(n ast.Node) int
  • func (in *Inspector) Name(n ast.Node) string
  • func (in *Inspector) Parent(n ast.Node) ast.Node
  • func (in *Inspector) Path(n ast.Node) []ast.Node
  • func (in *Inspector) Stack(n ast.Node) []ast.Node
• type NodeNavigator
  • func NewNodeNavigator(fset *token.FileSet, files []*ast.File, in *inspector.Inspector) *NodeNavigator
  • func (n *NodeNavigator) Copy() xpath.NodeNavigator
  • func (n *NodeNavigator) LocalName() string
  • func (n *NodeNavigator) MoveTo(to xpath.NodeNavigator) bool
  • func (n *NodeNavigator) MoveToChild() bool
  • func (n *NodeNavigator) MoveToFirst() bool
  • func (n *NodeNavigator) MoveToNext() bool
  • func (n *NodeNavigator) MoveToNextAttribute() bool
  • func (n *NodeNavigator) MoveToParent() bool
  • func (n *NodeNavigator) MoveToPrevious() bool
  • func (n *NodeNavigator) MoveToRoot()
  • func (n *NodeNavigator) Node() ast.Node
  • func (n *NodeNavigator) NodeType() xpath.NodeType
  • func (n *NodeNavigator) Prefix() string
  • func (n *NodeNavigator) Value() string

Variables

var Analyzer = &analysis.Analyzer{
	Name: "astquery",
	Doc:  "search nodes by xpath",
	Run:  new(analyzer).run,
	Requires: []*analysis.Analyzer{
		inspect.Analyzer,
	},
	ResultType: reflect.TypeOf(new(Evaluator)),
}

Analyzer provides *astquery.Evaluator as a result.

Example:

func run(pass *analysis.Pass) (interface{}, error) {
	e := pass.ResultOf[astquery.Analyzer].(*astquery.Evaluator)
	ns, err := e.Select("//*[@type='CallExpr']/Fun[@type='Ident' and @Name='panic']")
	if err != nil {
		return nil, err
	}

	for _, n := range ns {
		pass.Reportf(n.Pos(), "don't panic")
	}

	return nil, nil
}

Types

type Evaluator

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

Evaluator evals and selects AST's nodes by XPath.

func New

func New(fset *token.FileSet, files []*ast.File, in *inspector.Inspector) *Evaluator

New creates an Evaluator. If the given inspector is not nil macher use it.

func (*Evaluator) Eval

func (e *Evaluator) Eval(expr string) (interface{}, error)

Eval returns the result of the expression. The result type of the expression is one of the follow: bool,float64,string,[]ast.Node.

func (*Evaluator) Select

func (e *Evaluator) Select(expr string) ([]ast.Node, error)

Select selects a node set which match the XPath expr.

func (*Evaluator) SelectOne

func (e *Evaluator) SelectOne(expr string) (ast.Node, error)

SelectOne selects a node set which match the XPath expr and return the first node.

type Inspector

type Inspector struct {
	*inspector.Inspector
}

Inspector is wrapper of *golang.org/x/go/ast/inspector.Inspector.

func NewInspector

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

NewInspector creates an Inspector.

func (*Inspector) Children

func (in *Inspector) Children(n ast.Node) []ast.Node

Children returns children of the given node.

func (*Inspector) Index

func (in *Inspector) Index(n ast.Node) int

Index returns parent's field index.

func (*Inspector) Name

func (in *Inspector) Name(n ast.Node) string

Name returns parent's field name.

func (*Inspector) Parent

func (in *Inspector) Parent(n ast.Node) ast.Node

Parent returns a parent node of the given node.

func (*Inspector) Path

func (in *Inspector) Path(n ast.Node) []ast.Node

Path returns a path to the given node from the root node. The path's first element is the given node and last element is the root node.

func (*Inspector) Stack

func (in *Inspector) Stack(n ast.Node) []ast.Node

Stack returns a stack which contains between the root node and the given node. The stack's first element is the root node and last element is the given node.

type NodeNavigator

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

NodeNavigator implements xpath.NodeNavigator.

func NewNodeNavigator

func NewNodeNavigator(fset *token.FileSet, files []*ast.File, in *inspector.Inspector) *NodeNavigator

NewNodeNavigator creates a NodeNavigator. If in is not nil NodeNavigator use the given inspector.

func (*NodeNavigator) Copy

func (n *NodeNavigator) Copy() xpath.NodeNavigator

func (*NodeNavigator) LocalName

func (n *NodeNavigator) LocalName() string

func (*NodeNavigator) MoveTo

func (n *NodeNavigator) MoveTo(to xpath.NodeNavigator) bool

func (*NodeNavigator) MoveToChild

func (n *NodeNavigator) MoveToChild() bool

func (*NodeNavigator) MoveToFirst

func (n *NodeNavigator) MoveToFirst() bool

func (*NodeNavigator) MoveToNext

func (n *NodeNavigator) MoveToNext() bool

func (*NodeNavigator) MoveToNextAttribute

func (n *NodeNavigator) MoveToNextAttribute() bool

func (*NodeNavigator) MoveToParent

func (n *NodeNavigator) MoveToParent() bool

func (*NodeNavigator) MoveToPrevious

func (n *NodeNavigator) MoveToPrevious() bool

func (*NodeNavigator) MoveToRoot

func (n *NodeNavigator) MoveToRoot()

func (*NodeNavigator) Node

func (n *NodeNavigator) Node() ast.Node

func (*NodeNavigator) NodeType

func (n *NodeNavigator) NodeType() xpath.NodeType

func (*NodeNavigator) Prefix

func (n *NodeNavigator) Prefix() string

func (*NodeNavigator) Value

func (n *NodeNavigator) Value() string