# package ast

`import "go/ast"`

Package ast declares the types used to represent syntax trees for Go packages.

ast.go commentmap.go filter.go import.go print.go resolve.go scope.go walk.go

## func FileExports

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

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

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.

## func FilterPackage

FilterPackage trims the AST for a Go package 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. The pkg.Files list is not changed, so that file names and top-level package comments don't get lost.

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

## func Fprint

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

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).

Example

This example demonstrates how to inspect the AST of a Go program.

Code:play

    // 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

## func IsExported

IsExported reports whether name is an exported Go symbol (that is, whether it begins with an upper-case letter).

## func NotNilFilter

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

## func PackageExports

PackageExports trims the AST for a Go package in place such that only exported nodes remain. The pkg.Files list is not changed, so that file names and top-level package comments don't get lost.

PackageExports reports whether there are exported declarations; it returns false otherwise.

## func Print

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

Example

This example shows what an AST looks like when printed for debugging.

Code:play

    // 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  .  .  .  .  .  .  .  .  .  Kind: STRING
        38  .  .  .  .  .  .  .  .  .  Value: "\"Hello, World!\""
        39  .  .  .  .  .  .  .  .  }
        40  .  .  .  .  .  .  .  }
        41  .  .  .  .  .  .  .  Ellipsis: -
        42  .  .  .  .  .  .  .  Rparen: 4:25
        43  .  .  .  .  .  .  }
        44  .  .  .  .  .  }
        45  .  .  .  .  }
        46  .  .  .  .  Rbrace: 5:1
        47  .  .  .  }
        48  .  .  }
        49  .  }
        50  .  Scope: *ast.Scope {
        51  .  .  Objects: map[string]*ast.Object (len = 1) {
        52  .  .  .  "main": *(obj @ 11)
        53  .  .  }
        54  .  }
        55  .  Unresolved: []*ast.Ident (len = 1) {
        56  .  .  0: *(obj @ 29)
        57  .  }
        58  }

## func SortImports

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

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

An ArrayType node represents an array or slice type.

### func (*ArrayType) End

### func (*ArrayType) Pos

## type AssignStmt

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

### func (*AssignStmt) End

### func (*AssignStmt) Pos

## type BadDecl

A BadDecl node is a placeholder for declarations containing syntax errors for which no correct declaration nodes can be created.

### func (*BadDecl) End

### func (*BadDecl) Pos

## type BadExpr

A BadExpr node is a placeholder for expressions containing syntax errors for which no correct expression nodes can be created.

### func (*BadExpr) End

### func (*BadExpr) Pos

## type BadStmt

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

### func (*BadStmt) End

### func (*BadStmt) Pos

## type BasicLit

A BasicLit node represents a literal of basic type.

### func (*BasicLit) End

### func (*BasicLit) Pos

## type BinaryExpr

A BinaryExpr node represents a binary expression.

### func (*BinaryExpr) End

### func (*BinaryExpr) Pos

## type BlockStmt

A BlockStmt node represents a braced statement list.

### func (*BlockStmt) End

### func (*BlockStmt) Pos

## type BranchStmt

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

### func (*BranchStmt) End

### func (*BranchStmt) Pos

## type CallExpr

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

### func (*CallExpr) End

### func (*CallExpr) Pos

## type CaseClause

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

### func (*CaseClause) End

### func (*CaseClause) Pos

## type ChanDir

The direction of a channel type is indicated by one of the following constants.

## type ChanType

A ChanType node represents a channel type.

### func (*ChanType) End

### func (*ChanType) Pos

## type CommClause

A CommClause node represents a case of a select statement.

### func (*CommClause) End

### func (*CommClause) Pos

## type Comment

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

### func (*Comment) End

### func (*Comment) Pos

## type CommentGroup

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

### func (*CommentGroup) End

### func (*CommentGroup) Pos

### func (*CommentGroup) Text

Text returns the text of the comment. Comment markers (//, /*, and */), the first space of a line comment, and leading and trailing empty lines are removed. Multiple empty lines are reduced to one, and trailing space on lines is trimmed. Unless the result is empty, it is newline-terminated.

## type CommentMap

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

Example

This example illustrates how to remove a variable declaration in a Go program while maintaining correct comment association using an ast.CommentMap.

Code:

    // src is the input for which we create the AST that we
    // are going to manipulate.
    src := `
    // This is the package comment.
    package main

    // This comment is associated with the hello constant.
    const hello = "Hello, World!" // line comment 1

    // This comment is associated with the foo variable.
    var foo = hello // line comment 2

    // This comment is associated with the main function.
    func main() {
    	fmt.Println(hello) // line comment 3
    }
    `

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

    // Create an ast.CommentMap from the ast.File's comments.
    // This helps keeping the association between comments
    // and AST nodes.
    cmap := ast.NewCommentMap(fset, f, f.Comments)

    // Remove the first variable declaration from the list of declarations.
    f.Decls = removeFirstVarDecl(f.Decls)

    // Use the comment map to filter comments that don't belong anymore
    // (the comments associated with the variable declaration), and create
    // the new comments list.
    f.Comments = cmap.Filter(f).Comments()

    // Print the modified AST.
    var buf bytes.Buffer
    if err := format.Node(&buf, fset, f); err != nil {
        panic(err)
    }
    fmt.Printf("%s", buf.Bytes())

Output:

    // This is the package comment.
    package main

    // This comment is associated with the hello constant.
    const hello = "Hello, World!" // line comment 1

    // This comment is associated with the main function.
    func main() {
    	fmt.Println(hello) // line comment 3
    }

### func NewCommentMap

NewCommentMap creates a new comment map by associating comment groups of the comments list with the nodes of the AST specified by node.

A comment group g is associated with a node n if:

    - g starts on the same line as n ends
    - g starts on the line immediately following n, and there is
      at least one empty line after g and before the next node
    - g starts before n and is not associated to the node before n
      via the previous rules

NewCommentMap tries to associate a comment group to the "largest" node possible: For instance, if the comment is a line comment trailing an assignment, the comment is associated with the entire assignment rather than just the last operand in the assignment.

### func (CommentMap) Comments

Comments returns the list of comment groups in the comment map. The result is sorted in source order.

### func (CommentMap) Filter

Filter returns a new comment map consisting of only those entries of cmap for which a corresponding node exists in the AST specified by node.

### func (CommentMap) String

### func (CommentMap) Update

Update replaces an old node in the comment map with the new node and returns the new node. Comments that were associated with the old node are associated with the new node.

## type CompositeLit

A CompositeLit node represents a composite literal.

### func (*CompositeLit) End

### func (*CompositeLit) Pos

## type Decl

All declaration nodes implement the Decl interface.

## type DeclStmt

A DeclStmt node represents a declaration in a statement list.

### func (*DeclStmt) End

### func (*DeclStmt) Pos

## type DeferStmt

A DeferStmt node represents a defer statement.

### func (*DeferStmt) End

### func (*DeferStmt) Pos

## type Ellipsis

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

### func (*Ellipsis) End

### func (*Ellipsis) Pos

## type EmptyStmt

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

### func (*EmptyStmt) End

### func (*EmptyStmt) Pos

## type Expr

All expression nodes implement the Expr interface.

## type ExprStmt

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

### func (*ExprStmt) End

### func (*ExprStmt) Pos

## type Field

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.

### func (*Field) End

### func (*Field) Pos

## type FieldFilter

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

## type FieldList

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

### func (*FieldList) End

### func (*FieldList) NumFields

NumFields returns the number of (named and anonymous fields) in a FieldList.

### func (*FieldList) Pos

## type File

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.

### func MergePackageFiles

MergePackageFiles creates a file AST by merging the ASTs of the files belonging to a package. The mode flags control merging behavior.

### func (*File) End

### func (*File) Pos

## type Filter

## type ForStmt

A ForStmt represents a for statement.

### func (*ForStmt) End

### func (*ForStmt) Pos

## type FuncDecl

A FuncDecl node represents a function declaration.

### func (*FuncDecl) End

### func (*FuncDecl) Pos

## type FuncLit

A FuncLit node represents a function literal.

### func (*FuncLit) End

### func (*FuncLit) Pos

## type FuncType

A FuncType node represents a function type.

### func (*FuncType) End

### func (*FuncType) Pos

## type GenDecl

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

### func (*GenDecl) End

### func (*GenDecl) Pos

## type GoStmt

A GoStmt node represents a go statement.

### func (*GoStmt) End

### func (*GoStmt) Pos

## type Ident

An Ident node represents an identifier.

### func NewIdent

NewIdent creates a new Ident without position. Useful for ASTs generated by code other than the Go parser.

### func (*Ident) End

### func (*Ident) IsExported

IsExported reports whether id is an exported Go symbol (that is, whether it begins with an uppercase letter).

### func (*Ident) Pos

### func (*Ident) String

## type IfStmt

An IfStmt node represents an if statement.

### func (*IfStmt) End

### func (*IfStmt) Pos

## type ImportSpec

An ImportSpec node represents a single package import.

### func (*ImportSpec) End

### func (*ImportSpec) Pos

## type Importer

An Importer resolves import paths to package Objects. The imports map records the packages already imported, indexed by package id (canonical import path). An Importer must determine the canonical import path and check the map to see if it is already present in the imports map. If so, the Importer can return the map entry. Otherwise, the Importer should load the package data for the given path into a new *Object (pkg), record pkg in the imports map, and then return pkg.

## type IncDecStmt

An IncDecStmt node represents an increment or decrement statement.

### func (*IncDecStmt) End

### func (*IncDecStmt) Pos

## type IndexExpr

An IndexExpr node represents an expression followed by an index.

### func (*IndexExpr) End

### func (*IndexExpr) Pos

## type InterfaceType

An InterfaceType node represents an interface type.

### func (*InterfaceType) End

### func (*InterfaceType) Pos

## type KeyValueExpr

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

### func (*KeyValueExpr) End

### func (*KeyValueExpr) Pos

## type LabeledStmt

A LabeledStmt node represents a labeled statement.

### func (*LabeledStmt) End

### func (*LabeledStmt) Pos

## type MapType

A MapType node represents a map type.

### func (*MapType) End

### func (*MapType) Pos

## type MergeMode

The MergeMode flags control the behavior of MergePackageFiles.

## type Node

All node types implement the Node interface.

## type ObjKind

ObjKind describes what an object represents.

The list of possible Object kinds.

### func (ObjKind) String

## type Object

An Object describes a named language entity such as a package, constant, type, variable, function (incl. methods), or label.

The Data fields contains object-specific data:

    Kind    Data type         Data value
    Pkg     *Scope            package scope
    Con     int               iota for the respective declaration

### func NewObj

NewObj creates a new object of a given kind and name.

### func (*Object) Pos

Pos computes the source position of the declaration of an object name. The result may be an invalid position if it cannot be computed (obj.Decl may be nil or not correct).

## type Package

A Package node represents a set of source files collectively building a Go package.

### func NewPackage

NewPackage creates a new Package node from a set of File nodes. It resolves unresolved identifiers across files and updates each file's Unresolved list accordingly. If a non-nil importer and universe scope are provided, they are used to resolve identifiers not declared in any of the package files. Any remaining unresolved identifiers are reported as undeclared. If the files belong to different packages, one package name is selected and files with different package names are reported and then ignored. The result is a package node and a scanner.ErrorList if there were errors.

### func (*Package) End

### func (*Package) Pos

## type ParenExpr

A ParenExpr node represents a parenthesized expression.

### func (*ParenExpr) End

### func (*ParenExpr) Pos

## type RangeStmt

A RangeStmt represents a for statement with a range clause.

### func (*RangeStmt) End

### func (*RangeStmt) Pos

## type ReturnStmt

A ReturnStmt node represents a return statement.

### func (*ReturnStmt) End

### func (*ReturnStmt) Pos

## type Scope

A Scope maintains the set of named language entities declared in the scope and a link to the immediately surrounding (outer) scope.

### func NewScope

NewScope creates a new scope nested in the outer scope.

### func (*Scope) Insert

Insert attempts to insert a named object obj into the scope s. If the scope already contains an object alt with the same name, Insert leaves the scope unchanged and returns alt. Otherwise it inserts obj and returns nil.

### func (*Scope) Lookup

Lookup returns the object with the given name if it is found in scope s, otherwise it returns nil. Outer scopes are ignored.

### func (*Scope) String

Debugging support

## type SelectStmt

An SelectStmt node represents a select statement.

### func (*SelectStmt) End

### func (*SelectStmt) Pos

## type SelectorExpr

A SelectorExpr node represents an expression followed by a selector.

### func (*SelectorExpr) End

### func (*SelectorExpr) Pos

## type SendStmt

A SendStmt node represents a send statement.

### func (*SendStmt) End

### func (*SendStmt) Pos

## type SliceExpr

An SliceExpr node represents an expression followed by slice indices.

### func (*SliceExpr) End

### func (*SliceExpr) Pos

## type Spec

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

## type StarExpr

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

### func (*StarExpr) End

### func (*StarExpr) Pos

## type Stmt

All statement nodes implement the Stmt interface.

## type StructType

A StructType node represents a struct type.

### func (*StructType) End

### func (*StructType) Pos

## type SwitchStmt

A SwitchStmt node represents an expression switch statement.

### func (*SwitchStmt) End

### func (*SwitchStmt) Pos

## type TypeAssertExpr

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

### func (*TypeAssertExpr) End

### func (*TypeAssertExpr) Pos

## type TypeSpec

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

### func (*TypeSpec) End

### func (*TypeSpec) Pos

## type TypeSwitchStmt

An TypeSwitchStmt node represents a type switch statement.

### func (*TypeSwitchStmt) End

### func (*TypeSwitchStmt) Pos

## type UnaryExpr

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

### func (*UnaryExpr) End

### func (*UnaryExpr) Pos

## type ValueSpec

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

### func (*ValueSpec) End

### func (*ValueSpec) Pos

## type 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).