astutil

Documentation

Overview

Package astutil provides various AST utility functions for gopls.

Index

• func CloneNode[T ast.Node](n T) T
• func Deprecation(doc *ast.CommentGroup) string
• func Equal(x, y ast.Node, identical func(x, y *ast.Ident) bool) bool
• func FlatFields(list *ast.FieldList) iter.Seq2[*ast.Ident, *ast.Field]
• func NodeContains(n ast.Node, pos token.Pos) bool
• func PosInStringLiteral(lit *ast.BasicLit, offset int) (token.Pos, error)
• func PreorderStack(root ast.Node, stack []ast.Node, f func(n ast.Node, stack []ast.Node) bool)
• func PurgeFuncBodies(src []byte) []byte
• func RangeInStringLiteral(lit *ast.BasicLit, start, end int) (token.Pos, token.Pos, error)
• func UnpackRecv(rtyp ast.Expr) (ptr bool, rname *ast.Ident, tparams []*ast.Ident)
• type Directive
  • func Directives(g *ast.CommentGroup) (res []*Directive)

Functions

func CloneNode

func CloneNode[T ast.Node](n T) T

CloneNode returns a deep copy of a Node. It omits pointers to ast.{Scope,Object} variables.

func Deprecation

func Deprecation(doc *ast.CommentGroup) string

Deprecation returns the paragraph of the doc comment that starts with the conventional "Deprecation: " marker, as defined by https://go.dev/wiki/Deprecated, or "" if the documented symbol is not deprecated.

func Equal

func Equal(x, y ast.Node, identical func(x, y *ast.Ident) bool) bool

Equal reports whether two nodes are structurally equal, ignoring fields of type token.Pos, ast.Object, and ast.Scope, and comments.

The operands x and y may be nil. A nil slice is not equal to an empty slice.

The provided function determines whether two identifiers should be considered identical.

func FlatFields

func FlatFields(list *ast.FieldList) iter.Seq2[*ast.Ident, *ast.Field]

FlatFields 'flattens' an ast.FieldList, returning an iterator over each (name, field) combination in the list. For unnamed fields, the identifier is nil.

func NodeContains

func NodeContains(n ast.Node, pos token.Pos) bool

NodeContains reports whether the Pos/End range of node n encloses the given position pos.

It is inclusive of both end points, to allow hovering (etc) when the cursor is immediately after a node.

For unfortunate historical reasons, the Pos/End extent of an ast.File runs from the start of its package declaration---excluding copyright comments, build tags, and package documentation---to the end of its last declaration, excluding any trailing comments. So, as a special case, if n is an ast.File, NodeContains uses n.FileStart <= pos && pos <= n.FileEnd to report whether the position lies anywhere within the file.

Precondition: n must not be nil.

func PosInStringLiteral

func PosInStringLiteral(lit *ast.BasicLit, offset int) (token.Pos, error)

PosInStringLiteral returns the position within a string literal corresponding to the specified byte offset within the logical string that it denotes.

func PreorderStack

func PreorderStack(root ast.Node, stack []ast.Node, f func(n ast.Node, stack []ast.Node) bool)

PreorderStack traverses the tree rooted at root, calling f before visiting each node.

Each call to f provides the current node and traversal stack, consisting of the original value of stack appended with all nodes from root to n, excluding n itself. (This design allows calls to PreorderStack to be nested without double counting.)

If f returns false, the traversal skips over that subtree. Unlike ast.Inspect, no second call to f is made after visiting node n. In practice, the second call is nearly always used only to pop the stack, and it is surprisingly tricky to do this correctly; see https://go.dev/issue/73319.

TODO(adonovan): replace with ast.PreorderStack when go1.25 is assured.

func PurgeFuncBodies

func PurgeFuncBodies(src []byte) []byte

PurgeFuncBodies returns a copy of src in which the contents of each outermost {...} region except struct and interface types have been deleted. This reduces the amount of work required to parse the top-level declarations.

PurgeFuncBodies does not preserve newlines or position information. Also, if the input is invalid, parsing the output of PurgeFuncBodies may result in a different tree due to its effects on parser error recovery.

func RangeInStringLiteral

func RangeInStringLiteral(lit *ast.BasicLit, start, end int) (token.Pos, token.Pos, error)

RangeInStringLiteral calculates the positional range within a string literal corresponding to the specified start and end byte offsets within the logical string.

func UnpackRecv

func UnpackRecv(rtyp ast.Expr) (ptr bool, rname *ast.Ident, tparams []*ast.Ident)

UnpackRecv unpacks a receiver type expression, reporting whether it is a pointer receiver, along with the type name identifier and any receiver type parameter identifiers.

Copied (with modifications) from go/types.

Types

type Directive

type Directive struct {
	Pos  token.Pos // of preceding "//"
	Tool string
	Name string
	Args string // may contain internal spaces
}

A directive is a comment line with special meaning to the Go toolchain or another tool. It has the form:

//tool:name args

The "tool:" portion is missing for the three directives named line, extern, and export.

See https://go.dev/doc/comment#Syntax for details of Go comment syntax and https://pkg.go.dev/cmd/compile#hdr-Compiler_Directives for details of directives used by the Go compiler.

func Directives

func Directives(g *ast.CommentGroup) (res []*Directive)

Directives returns the directives within the comment.