func FileExports(src *File) bool

FileExports trims the AST for a Go source file in place such that only exported nodes remain: all top-level identifiers which are not exported and their associated information (such as type, initial value, or function body) are removed. Non-exported fields and methods of exported types are stripped. The [File.Comments] list is not changed.

FileExports reports whether there are exported declarations.

func FilterDecl(decl Decl, f Filter) bool

FilterDecl trims the AST for a Go declaration in place by removing all names (including struct field and interface method names, but not from parameter lists) that don't pass through the filter f.

FilterDecl reports whether there are any declared names left after filtering.

func FilterFile(src *File, f Filter) bool

FilterFile trims the AST for a Go file in place by removing all names from top-level declarations (including struct field and interface method names, but not from parameter lists) that don't pass through the filter f. If the declaration is empty afterwards, the declaration is removed from the AST. Import declarations are always removed. The [File.Comments] list is not changed.

FilterFile reports whether there are any top-level declarations left after filtering.

Fprint prints the (sub-)tree starting at AST node x to w. If fset != nil, position information is interpreted relative to that file set. Otherwise positions are printed as integer values (file set specific offsets).

A non-nil FieldFilter f may be provided to control the output: struct fields for which f(fieldname, fieldvalue) is true are printed; all others are filtered from the output. Unexported struct fields are never printed.

func Inspect(node Node, f func(Node) bool)

Inspect traverses an AST in depth-first order: It starts by calling f(node); node must not be nil. If f returns true, Inspect invokes f recursively for each of the non-nil children of node, followed by a call of f(nil).

In many cases it may be more convenient to use Preorder, which returns an iterator over the sequence of nodes, or PreorderStack, which (like Inspect) provides control over descent into subtrees, but additionally reports the stack of enclosing nodes.

package main

import (
	"fmt"
	"go/ast"
	"go/parser"
	"go/token"
)

func main() {
	// src is the input for which we want to inspect the AST.
	src := `
package p
const c = 1.0
var X = f(3.14)*2 + c
`

	// Create the AST by parsing src.
	fset := token.NewFileSet() // positions are relative to fset
	f, err := parser.ParseFile(fset, "src.go", src, 0)
	if err != nil {
		panic(err)
	}

	// Inspect the AST and print all identifiers and literals.
	ast.Inspect(f, func(n ast.Node) bool {
		var s string
		switch x := n.(type) {
		case *ast.BasicLit:
			s = x.Value
		case *ast.Ident:
			s = x.Name
		}
		if s != "" {
			fmt.Printf("%s:\t%s\n", fset.Position(n.Pos()), s)
		}
		return true
	})

}

Output:

src.go:2:9:	p
src.go:3:7:	c
src.go:3:11:	1.0
src.go:4:5:	X
src.go:4:9:	f
src.go:4:11:	3.14
src.go:4:17:	2
src.go:4:21:	c

IsExported reports whether name starts with an upper-case letter.

func IsGenerated(file *File) bool

IsGenerated reports whether the file was generated by a program, not handwritten, by detecting the special comment described at https://go.dev/s/generatedcode.

The syntax tree must have been parsed with the [parser.ParseComments] flag. Example:

f, err := parser.ParseFile(fset, filename, src, parser.ParseComments|parser.PackageClauseOnly)
if err != nil { ... }
gen := ast.IsGenerated(f)

NotNilFilter is a FieldFilter that returns true for field values that are not nil; it returns false otherwise.

Preorder returns an iterator over all the nodes of the syntax tree beneath (and including) the specified root, in depth-first preorder.

For greater control over the traversal of each subtree, use Inspect or PreorderStack.

package main

import (
	"fmt"
	"go/ast"
	"go/parser"
	"go/token"
)

func main() {
	src := `
package p

func f(x, y int) {
	print(x + y)
}
`

	fset := token.NewFileSet()
	f, err := parser.ParseFile(fset, "", src, 0)
	if err != nil {
		panic(err)
	}

	// Print identifiers in order
	for n := range ast.Preorder(f) {
		id, ok := n.(*ast.Ident)
		if !ok {
			continue
		}
		fmt.Println(id.Name)
	}

}

Output:

p
f
x
y
int
print
x
y

func PreorderStack(root Node, stack []Node, f func(n Node, stack []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 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.)

Print prints x to standard output, skipping nil fields. Print(fset, x) is the same as Fprint(os.Stdout, fset, x, NotNilFilter).

package main

import (
	"go/ast"
	"go/parser"
	"go/token"
)

func main() {
	// src is the input for which we want to print the AST.
	src := `
package main
func main() {
	println("Hello, World!")
}
`

	// Create the AST by parsing src.
	fset := token.NewFileSet() // positions are relative to fset
	f, err := parser.ParseFile(fset, "", src, 0)
	if err != nil {
		panic(err)
	}

	// Print the AST.
	ast.Print(fset, f)

}

Output:

     0  *ast.File {
     1  .  Package: 2:1
     2  .  Name: *ast.Ident {
     3  .  .  NamePos: 2:9
     4  .  .  Name: "main"
     5  .  }
     6  .  Decls: []ast.Decl (len = 1) {
     7  .  .  0: *ast.FuncDecl {
     8  .  .  .  Name: *ast.Ident {
     9  .  .  .  .  NamePos: 3:6
    10  .  .  .  .  Name: "main"
    11  .  .  .  .  Obj: *ast.Object {
    12  .  .  .  .  .  Kind: func
    13  .  .  .  .  .  Name: "main"
    14  .  .  .  .  .  Decl: *(obj @ 7)
    15  .  .  .  .  }
    16  .  .  .  }
    17  .  .  .  Type: *ast.FuncType {
    18  .  .  .  .  Func: 3:1
    19  .  .  .  .  Params: *ast.FieldList {
    20  .  .  .  .  .  Opening: 3:10
    21  .  .  .  .  .  Closing: 3:11
    22  .  .  .  .  }
    23  .  .  .  }
    24  .  .  .  Body: *ast.BlockStmt {
    25  .  .  .  .  Lbrace: 3:13
    26  .  .  .  .  List: []ast.Stmt (len = 1) {
    27  .  .  .  .  .  0: *ast.ExprStmt {
    28  .  .  .  .  .  .  X: *ast.CallExpr {
    29  .  .  .  .  .  .  .  Fun: *ast.Ident {
    30  .  .  .  .  .  .  .  .  NamePos: 4:2
    31  .  .  .  .  .  .  .  .  Name: "println"
    32  .  .  .  .  .  .  .  }
    33  .  .  .  .  .  .  .  Lparen: 4:9
    34  .  .  .  .  .  .  .  Args: []ast.Expr (len = 1) {
    35  .  .  .  .  .  .  .  .  0: *ast.BasicLit {
    36  .  .  .  .  .  .  .  .  .  ValuePos: 4:10
    37  .  .  .  .  .  .  .  .  .  ValueEnd: 4:25
    38  .  .  .  .  .  .  .  .  .  Kind: STRING
    39  .  .  .  .  .  .  .  .  .  Value: "\"Hello, World!\""
    40  .  .  .  .  .  .  .  .  }
    41  .  .  .  .  .  .  .  }
    42  .  .  .  .  .  .  .  Ellipsis: -
    43  .  .  .  .  .  .  .  Rparen: 4:25
    44  .  .  .  .  .  .  }
    45  .  .  .  .  .  }
    46  .  .  .  .  }
    47  .  .  .  .  Rbrace: 5:1
    48  .  .  .  }
    49  .  .  }
    50  .  }
    51  .  FileStart: 1:1
    52  .  FileEnd: 5:3
    53  .  Scope: *ast.Scope {
    54  .  .  Objects: map[string]*ast.Object (len = 1) {
    55  .  .  .  "main": *(obj @ 11)
    56  .  .  }
    57  .  }
    58  .  Unresolved: []*ast.Ident (len = 1) {
    59  .  .  0: *(obj @ 29)
    60  .  }
    61  .  GoVersion: ""
    62  }

SortImports sorts runs of consecutive import lines in import blocks in f. It also removes duplicate imports when it is possible to do so without data loss.

func Walk(v Visitor, node Node)

Walk traverses an AST in depth-first order: It starts by calling v.Visit(node); node must not be nil. If the visitor w returned by v.Visit(node) is not nil, Walk is invoked recursively with visitor w for each of the non-nil children of node, followed by a call of w.Visit(nil).

type ArrayType struct {
	Lbrack token.Pos 
	Len    Expr      
	Elt    Expr      
}

An ArrayType node represents an array or slice type.

An AssignStmt node represents an assignment or a short variable declaration.

type BadDecl struct {
	From, To token.Pos 
}

A BadDecl node is a placeholder for a declaration containing syntax errors for which a correct declaration node cannot be created.

type BadExpr struct {
	From, To token.Pos 
}

A BadExpr node is a placeholder for an expression containing syntax errors for which a correct expression node cannot be created.

type BadStmt struct {
	From, To token.Pos 
}

A BadStmt node is a placeholder for statements containing syntax errors for which no correct statement nodes can be created.

A BasicLit node represents a literal of basic type.

Note that for the CHAR and STRING kinds, the literal is stored with its quotes. For example, for a double-quoted STRING, the first and the last rune in the Value field will be ". The strconv.Unquote and strconv.UnquoteChar functions can be used to unquote STRING and CHAR values, respectively.

For raw string literals (Kind == token.STRING && Value[0] == '`'), the Value field contains the string text without carriage returns (\r) that may have been present in the source.

A BinaryExpr node represents a binary expression.

A BlockStmt node represents a braced statement list.

A BranchStmt node represents a break, continue, goto, or fallthrough statement.

A CallExpr node represents an expression followed by an argument list.

A CaseClause represents a case of an expression or type switch statement.

type ChanDir ¶

The direction of a channel type is indicated by a bit mask including one or both of the following constants.

const (
	SEND ChanDir = 1 << iota
	RECV
)

A ChanType node represents a channel type.

A CommClause node represents a case of a select statement.

A Comment node represents a single //-style or /*-style comment.

The Text field contains the comment text without carriage returns (\r) that may have been present in the source. Because a comment's end position is computed using len(Text), the position reported by Comment.End does not match the true source end position for comments containing carriage returns.

type CommentGroup struct {
}

A CommentGroup represents a sequence of comments with no other tokens and no empty lines between.

type CommentMap map[Node][]*CommentGroup

A CommentMap maps an AST node to a list of comment groups associated with it. See NewCommentMap for a description of the association.

func (cmap CommentMap) Comments() []*CommentGroup

func (cmap CommentMap) Filter(node Node) CommentMap

func (cmap CommentMap) Update(old, new Node) Node

A CompositeLit node represents a composite literal.

type Decl interface {
	Node
	
}

All declaration nodes implement the Decl interface.

type DeclStmt struct {
	Decl Decl 
}

A DeclStmt node represents a declaration in a statement list.

type DeferStmt struct {
	Defer token.Pos 
	Call  *CallExpr
}

A DeferStmt node represents a defer statement.

A Directive is a comment of this form:

//tool:name args

For example, this directive:

//go:generate stringer -type Op -trimprefix Op

would have Tool "go", Name "generate", and Args "stringer -type Op -trimprefix Op".

While Args does not have a strict syntax, by convention it is a space-separated sequence of unquoted words, '"'-quoted Go strings, or '`'-quoted raw strings.

See https://go.dev/doc/comment#directives for specification.

A DirectiveArg is an argument to a directive comment.

type Ellipsis struct {
	Ellipsis token.Pos 
	Elt      Expr      
}

An Ellipsis node stands for the "..." type in a parameter list or the "..." length in an array type.

An EmptyStmt node represents an empty statement. The "position" of the empty statement is the position of the immediately following (explicit or implicit) semicolon.

type Expr interface {
	Node
	
}

All expression nodes implement the Expr interface.

func Unparen(e Expr) Expr

type ExprStmt struct {
	X Expr 
}

An ExprStmt node represents a (stand-alone) expression in a statement list.

type Field struct {
	Doc     *CommentGroup 
	Names   []*Ident      
	Type    Expr          
	Tag     *BasicLit     
}

A Field represents a Field declaration list in a struct type, a method list in an interface type, or a parameter/result declaration in a signature. [Field.Names] is nil for unnamed parameters (parameter lists which only contain types) and embedded struct fields. In the latter case, the field name is the type name.

A FieldFilter may be provided to Fprint to control the output.

A FieldList represents a list of Fields, enclosed by parentheses, curly braces, or square brackets.

func (f *FieldList) NumFields() int

type File struct {
	Doc     *CommentGroup 
	Package token.Pos     
	Name    *Ident        
	Decls   []Decl        

	FileStart, FileEnd token.Pos       
	Scope              *Scope          
	Imports            []*ImportSpec   
	Unresolved         []*Ident        
	GoVersion          string          
}

A File node represents a Go source file.

The Comments list contains all comments in the source file in order of appearance, including the comments that are pointed to from other nodes via Doc and Comment fields.

For correct printing of source code containing comments (using packages go/format and go/printer), special care must be taken to update comments when a File's syntax tree is modified: For printing, comments are interspersed between tokens based on their position. If syntax tree nodes are removed or moved, relevant comments in their vicinity must also be removed (from the [File.Comments] list) or moved accordingly (by updating their positions). A CommentMap may be used to facilitate some of these operations.

Whether and how a comment is associated with a node depends on the interpretation of the syntax tree by the manipulating program: except for Doc and Comment comments directly associated with nodes, the remaining comments are "free-floating" (see also issues #18593, #20744).

func MergePackageFiles(pkg *Package, mode MergeMode) *File

type ForStmt struct {
	For  token.Pos 
	Init Stmt      
	Cond Expr      
	Post Stmt      
	Body *BlockStmt
}

A ForStmt represents a for statement.

type FuncDecl struct {
	Doc  *CommentGroup 
	Recv *FieldList    
	Name *Ident        
	Type *FuncType     
	Body *BlockStmt    
}

A FuncDecl node represents a function declaration.

type FuncLit struct {
	Type *FuncType  
	Body *BlockStmt 
}

A FuncLit node represents a function literal.

type FuncType struct {
	Func       token.Pos  
	TypeParams *FieldList 
	Params     *FieldList 
	Results    *FieldList 
}

A FuncType node represents a function type.

A GenDecl node (generic declaration node) represents an import, constant, type or variable declaration. A valid Lparen position (Lparen.IsValid()) indicates a parenthesized declaration.

Relationship between Tok value and Specs element type:

token.IMPORT  *ImportSpec
token.CONST   *ValueSpec
token.TYPE    *TypeSpec
token.VAR     *ValueSpec

A GoStmt node represents a go statement.

An Ident node represents an identifier.

func (id *Ident) IsExported() bool

type IfStmt struct {
	If   token.Pos 
	Init Stmt      
	Cond Expr      
	Body *BlockStmt
	Else Stmt 
}

An IfStmt node represents an if statement.

type ImportSpec struct {
	Doc     *CommentGroup 
	Name    *Ident        
	Path    *BasicLit     
	EndPos  token.Pos     
}

An ImportSpec node represents a single package import.

An IncDecStmt node represents an increment or decrement statement.

An IndexExpr node represents an expression followed by an index.

An IndexListExpr node represents an expression followed by multiple indices.

type InterfaceType struct {
	Interface  token.Pos  
	Methods    *FieldList 
	Incomplete bool       
}

An InterfaceType node represents an interface type.

type KeyValueExpr struct {
	Key   Expr
	Colon token.Pos 
	Value Expr
}

A KeyValueExpr node represents (key : value) pairs in composite literals.

type LabeledStmt struct {
	Label *Ident
	Colon token.Pos 
	Stmt  Stmt
}

A LabeledStmt node represents a labeled statement.

type MapType struct {
	Map   token.Pos 
	Key   Expr
	Value Expr
}

A MapType node represents a map type.

All node types implement the Node interface.

ObjKind describes what an Object represents.

const (
	Bad ObjKind = iota 
	Pkg                
	Con                
	Typ                
	Var                
	Fun                
	Lbl                
)

A ParenExpr node represents a parenthesized expression.

A RangeStmt represents a for statement with a range clause.

type ReturnStmt struct {
	Return  token.Pos 
	Results []Expr    
}

A ReturnStmt node represents a return statement.

type SelectStmt struct {
	Select token.Pos  
	Body   *BlockStmt 
}

A SelectStmt node represents a select statement.

type SelectorExpr struct {
	X   Expr   
	Sel *Ident 
}

A SelectorExpr node represents an expression followed by a selector.

type SendStmt struct {
	Chan  Expr
	Arrow token.Pos 
	Value Expr
}

A SendStmt node represents a send statement.

A SliceExpr node represents an expression followed by slice indices.

type Spec interface {
	Node
	
}

The Spec type stands for any of *ImportSpec, *ValueSpec, and *TypeSpec.

type StarExpr struct {
	Star token.Pos 
	X    Expr      
}

A StarExpr node represents an expression of the form "*" Expression. Semantically it could be a unary "*" expression, or a pointer type.

type Stmt interface {
	Node
	
}

All statement nodes implement the Stmt interface.

type StructType struct {
	Struct     token.Pos  
	Fields     *FieldList 
	Incomplete bool       
}

A StructType node represents a struct type.

type SwitchStmt struct {
	Switch token.Pos  
	Init   Stmt       
	Tag    Expr       
	Body   *BlockStmt 
}

A SwitchStmt node represents an expression switch statement.

A TypeAssertExpr node represents an expression followed by a type assertion.

type TypeSpec struct {
	Doc        *CommentGroup 
	Name       *Ident        
	TypeParams *FieldList    
	Assign     token.Pos     
	Type       Expr          
}

A TypeSpec node represents a type declaration (TypeSpec production).

type TypeSwitchStmt struct {
	Switch token.Pos  
	Init   Stmt       
	Assign Stmt       
	Body   *BlockStmt 
}

A TypeSwitchStmt node represents a type switch statement.

A UnaryExpr node represents a unary expression. Unary "*" expressions are represented via StarExpr nodes.

type ValueSpec struct {
	Doc     *CommentGroup 
	Names   []*Ident      
	Type    Expr          
	Values  []Expr        
}

A ValueSpec node represents a constant or variable declaration (ConstSpec or VarSpec production).

type Visitor interface {
	Visit(node Node) (w Visitor)
}

A Visitor's Visit method is invoked for each node encountered by Walk. If the result visitor w is not nil, Walk visits each of the children of node with the visitor w, followed by a call of w.Visit(nil).