const (
// for BranchStmt
Break = _Break
Continue = _Continue
Fallthrough = _Fallthrough
Goto = _Goto
// for CallStmt
Go = _Go
Defer = _Defer
)
PosMax is the largest line or column value that can be represented without loss. Incoming values (arguments) larger than PosMax will be set to PosMax.
Keep this consistent with maxLineCol in go/scanner.
const PosMax = 1 << 30
func CommentMap(src io.Reader, rx *regexp.Regexp) (res map[uint][]Error)
CommentMap collects all comments in the given src with comment text that matches the supplied regular expression rx and returns them as []Error lists in a map indexed by line number. The comment text is the comment with any comment markers ("//", "/*", or "*/") stripped. The position for each Error is the position of the token immediately preceding the comment and the Error message is the comment text, with all comments that are on the same line collected in a slice, in source order. If there is no preceding token (the matching comment appears at the beginning of the file), then the recorded position is unknown (line, col = 0, 0). If there are no matching comments, the result is nil.
func CommentsDo(src io.Reader, handler func(line, col uint, text string))
CommentsDo parses the given source and calls the provided handler for each comment or error. If the text provided to handler starts with a '/' it is the comment text; otherwise it is the error message.
func Fdump(w io.Writer, n Node) (err error)
Fdump dumps the structure of the syntax tree rooted at n to w. It is intended for debugging purposes; no specific output format is guaranteed.
func Fprint(w io.Writer, x Node, form Form) (n int, err error)
Fprint prints node x to w in the specified form. It returns the number of bytes written, and whether there was an error.
func Inspect(root Node, f func(Node) bool)
Inspect traverses an AST in pre-order: it starts by calling f(root); root must not be nil. If f returns true, Inspect invokes f recursively for each of the non-nil children of root, followed by a call of f(nil).
See Walk for caveats about shared nodes.
func String(n Node) string
String is a convenience function that prints n in ShortForm and returns the printed string.
func Walk(root Node, v Visitor)
Walk traverses an AST in pre-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).
Some nodes may be shared among multiple parent nodes (e.g., types in field lists such as type T in "a, b, c T"). Such shared nodes are walked multiple times. TODO(gri) Revisit this design. It may make sense to walk those nodes only once. A place where this matters is types2.TestResolveIdents.
[Len]Elem
type ArrayType struct {
// TODO(gri) consider using Name{"..."} instead of nil (permits attaching of comments)
Len Expr // nil means Len is ...
Elem Expr
// contains filtered or unexported fields
}
X.(Type)
type AssertExpr struct {
X Expr
Type Expr
// contains filtered or unexported fields
}
type AssignStmt struct {
Op Operator // 0 means no operation
Lhs, Rhs Expr // Rhs == nil means Lhs++ (Op == Add) or Lhs-- (Op == Sub)
// contains filtered or unexported fields
}
Placeholder for an expression that failed to parse correctly and where we can't provide a better node.
type BadExpr struct {
// contains filtered or unexported fields
}
Value
type BasicLit struct {
Value string
Kind LitKind
Bad bool // true means the literal Value has syntax errors
// contains filtered or unexported fields
}
type BlockStmt struct {
List []Stmt
Rbrace Pos
// contains filtered or unexported fields
}
type BranchStmt struct {
Tok token // Break, Continue, Fallthrough, or Goto
Label *Name
// Target is the continuation of the control flow after executing
// the branch; it is computed by the parser if CheckBranches is set.
// Target is a *LabeledStmt for gotos, and a *SwitchStmt, *SelectStmt,
// or *ForStmt for breaks and continues, depending on the context of
// the branch. Target is not set for fallthroughs.
Target Stmt
// contains filtered or unexported fields
}
Fun(ArgList[0], ArgList[1], ...)
type CallExpr struct {
Fun Expr
ArgList []Expr // nil means no arguments
HasDots bool // last argument is followed by ...
// contains filtered or unexported fields
}
type CallStmt struct {
Tok token // Go or Defer
Call Expr
DeferAt Expr // argument to runtime.deferprocat
// contains filtered or unexported fields
}
type CaseClause struct {
Cases Expr // nil means default clause
Body []Stmt
Colon Pos
// contains filtered or unexported fields
}
func (n *CaseClause) Pos() Pos
func (n *CaseClause) SetPos(pos Pos)
type ChanDir uint
const (
SendOnly ChanDir
RecvOnly
)
chan Elem
<-chan Elem chan<- Elem
type ChanType struct {
Dir ChanDir // 0 means no direction
Elem Expr
// contains filtered or unexported fields
}
type CommClause struct {
Comm SimpleStmt // send or receive stmt; nil means default clause
Body []Stmt
Colon Pos
// contains filtered or unexported fields
}
func (n *CommClause) Pos() Pos
func (n *CommClause) SetPos(pos Pos)
type Comment struct {
Kind CommentKind
Text string
Next *Comment
}
TODO(gri) Consider renaming to CommentPos, CommentPlacement, etc. Kind = Above doesn't make much sense.
type CommentKind uint
const (
Above CommentKind = iota
Below
Left
Right
)
Type { ElemList[0], ElemList[1], ... }
type CompositeLit struct {
Type Expr // nil means no literal type
ElemList []Expr
NKeys int // number of elements with keys
Rbrace Pos
// contains filtered or unexported fields
}
NameList NameList = Values NameList Type = Values
type ConstDecl struct {
Group *Group // nil means not part of a group
Pragma Pragma
NameList []*Name
Type Expr // nil means no type
Values Expr // nil means no values
// contains filtered or unexported fields
}
type Decl interface {
Node
// contains filtered or unexported methods
}
type DeclStmt struct {
DeclList []Decl
// contains filtered or unexported fields
}
...Elem
type DotsType struct {
Elem Expr
// contains filtered or unexported fields
}
type EmptyStmt struct {
// contains filtered or unexported fields
}
Error describes a syntax error. Error implements the error interface.
type Error struct {
Pos Pos
Msg string
}
func (err Error) Error() string
An ErrorHandler is called for each error encountered reading a .go file.
type ErrorHandler func(err error)
type Expr interface {
Node
// contains filtered or unexported methods
}
func UnpackListExpr(x Expr) []Expr
UnpackListExpr unpacks a *ListExpr into a []Expr.
func Unparen(x Expr) Expr
Unparen returns e with any enclosing parentheses stripped.
type ExprStmt struct {
X Expr
// contains filtered or unexported fields
}
Name Type
Type
type Field struct {
Name *Name // nil means anonymous field/parameter (structs/parameters), or embedded element (interfaces)
Type Expr // field names declared in a list share the same Type (identical pointers)
// contains filtered or unexported fields
}
func (n *Field) Pos() Pos
func (n *Field) SetPos(pos Pos)
package PkgName; DeclList[0], DeclList[1], ...
type File struct {
Pragma Pragma
PkgName *Name
DeclList []Decl
EOF Pos
GoVersion string
// contains filtered or unexported fields
}
func Parse(base *PosBase, src io.Reader, errh ErrorHandler, pragh PragmaHandler, mode Mode) (_ *File, first error)
Parse parses a single Go source file from src and returns the corresponding syntax tree. If there are errors, Parse will return the first error found, and a possibly partially constructed syntax tree, or nil.
If errh != nil, it is called with each error encountered, and Parse will process as much source as possible. In this case, the returned syntax tree is only nil if no correct package clause was found. If errh is nil, Parse will terminate immediately upon encountering the first error, and the returned syntax tree is nil.
If pragh != nil, it is called with each pragma encountered.
func ParseFile(filename string, errh ErrorHandler, pragh PragmaHandler, mode Mode) (*File, error)
ParseFile behaves like Parse but it reads the source from the named file.
func (n *File) Pos() Pos
func (n *File) SetPos(pos Pos)
type ForStmt struct {
Init SimpleStmt // incl. *RangeClause
Cond Expr
Post SimpleStmt
Body *BlockStmt
// contains filtered or unexported fields
}
Form controls print formatting.
type Form uint
const (
LineForm Form // use spaces instead of linebreaks where possible
ShortForm // like LineForm but print "…" for non-empty function or composite literal bodies
)
func Name Type { Body } func Name Type func Receiver Name Type { Body } func Receiver Name Type
type FuncDecl struct {
Pragma Pragma
Recv *Field // nil means regular function
Name *Name
TParamList []*Field // nil means no type parameters
Type *FuncType
Body *BlockStmt // nil means no body (forward declaration)
// contains filtered or unexported fields
}
func Type { Body }
type FuncLit struct {
Type *FuncType
Body *BlockStmt
// contains filtered or unexported fields
}
type FuncType struct {
ParamList []*Field
ResultList []*Field
// contains filtered or unexported fields
}
All declarations belonging to the same group point to the same Group node.
type Group struct {
// contains filtered or unexported fields
}
type IfStmt struct {
Init SimpleStmt
Cond Expr
Then *BlockStmt
Else Stmt // either nil, *IfStmt, or *BlockStmt
// contains filtered or unexported fields
}
Path
LocalPkgName Path
type ImportDecl struct {
Group *Group // nil means not part of a group
Pragma Pragma
LocalPkgName *Name // including "."; nil means no rename present
Path *BasicLit // Path.Bad || Path.Kind == StringLit; nil means no path
// contains filtered or unexported fields
}
X[Index] X[T1, T2, ...] (with Ti = Index.(*ListExpr).ElemList[i])
type IndexExpr struct {
X Expr
Index Expr
// contains filtered or unexported fields
}
interface { MethodList[0]; MethodList[1]; ... }
type InterfaceType struct {
MethodList []*Field
// contains filtered or unexported fields
}
Key: Value
type KeyValueExpr struct {
Key, Value Expr
// contains filtered or unexported fields
}
type LabeledStmt struct {
Label *Name
Stmt Stmt
// contains filtered or unexported fields
}
ElemList[0], ElemList[1], ...
type ListExpr struct {
ElemList []Expr
// contains filtered or unexported fields
}
type LitKind uint8
TODO(gri) With the 'i' (imaginary) suffix now permitted on integer and floating-point numbers, having a single ImagLit does not represent the literal kind well anymore. Remove it?
const (
IntLit LitKind = iota
FloatLit
ImagLit
RuneLit
StringLit
)
map[Key]Value
type MapType struct {
Key, Value Expr
// contains filtered or unexported fields
}
Mode describes the parser mode.
type Mode uint
Modes supported by the parser.
const (
CheckBranches Mode = 1 << iota // check correct use of labels, break, continue, and goto statements
)
Value
type Name struct {
Value string
// contains filtered or unexported fields
}
func NewName(pos Pos, value string) *Name
type Node interface {
// Pos() returns the position associated with the node as follows:
// 1) The position of a node representing a terminal syntax production
// (Name, BasicLit, etc.) is the position of the respective production
// in the source.
// 2) The position of a node representing a non-terminal production
// (IndexExpr, IfStmt, etc.) is the position of a token uniquely
// associated with that production; usually the left-most one
// ('[' for IndexExpr, 'if' for IfStmt, etc.)
Pos() Pos
SetPos(Pos)
// contains filtered or unexported methods
}
type Operation struct {
Op Operator
X, Y Expr // Y == nil means unary expression
// contains filtered or unexported fields
}
type Operator uint
const (
// Def is the : in :=
Def Operator // :
Not // !
Recv // <-
Tilde // ~
// precOrOr
OrOr // ||
// precAndAnd
AndAnd // &&
// precCmp
Eql // ==
Neq // !=
Lss // <
Leq // <=
Gtr // >
Geq // >=
// precAdd
Add // +
Sub // -
Or // |
Xor // ^
// precMul
Mul // *
Div // /
Rem // %
And // &
AndNot // &^
Shl // <<
Shr // >>
)
func (i Operator) String() string
(X)
type ParenExpr struct {
X Expr
// contains filtered or unexported fields
}
A Pos represents an absolute (line, col) source position with a reference to position base for computing relative (to a file, or line directive) position information. Pos values are intentionally light-weight so that they can be created without too much concern about space use.
type Pos struct {
// contains filtered or unexported fields
}
func EndPos(n Node) Pos
EndPos returns the approximate end position of n in the source. For some nodes (*Name, *BasicLit) it returns the position immediately following the node; for others (*BlockStmt, *SwitchStmt, etc.) it returns the position of the closing '}'; and for some (*ParenExpr) the returned position is the end position of the last enclosed expression. Thus, EndPos should not be used for exact demarcation of the end of a node in the source; it is mostly useful to determine scope ranges where there is some leeway.
func MakePos(base *PosBase, line, col uint) Pos
MakePos returns a new Pos for the given PosBase, line and column.
func StartPos(n Node) Pos
StartPos returns the start position of n.
func (pos Pos) Base() *PosBase
func (p Pos) Cmp(q Pos) int
Cmp compares the positions p and q and returns a result r as follows:
r < 0: p is before q r == 0: p and q are the same position (but may not be identical) r > 0: p is after q
If p and q are in different files, p is before q if the filename of p sorts lexicographically before the filename of q.
func (pos Pos) Col() uint
func (pos Pos) FileBase() *PosBase
FileBase returns the PosBase of the file containing pos, skipping over intermediate PosBases from //line directives. The result is nil if pos doesn't have a file base.
func (pos Pos) IsKnown() bool
func (pos Pos) Line() uint
func (pos Pos) Pos() Pos
func (pos Pos) RelCol() uint
func (pos Pos) RelFilename() string
func (pos Pos) RelLine() uint
func (pos Pos) String() string
A PosBase represents the base for relative position information: At position pos, the relative position is filename:line:col.
type PosBase struct {
// contains filtered or unexported fields
}
func NewFileBase(filename string) *PosBase
NewFileBase returns a new PosBase for the given filename. A file PosBase's position is relative to itself, with the position being filename:1:1.
func NewLineBase(pos Pos, filename string, trimmed bool, line, col uint) *PosBase
NewLineBase returns a new PosBase for a line directive "line filename:line:col" relative to pos, which is the position of the character immediately following the comment containing the line directive. For a directive in a line comment, that position is the beginning of the next line (i.e., the newline character belongs to the line comment).
func NewTrimmedFileBase(filename string, trimmed bool) *PosBase
NewTrimmedFileBase is like NewFileBase, but allows specifying Trimmed.
func (base *PosBase) Col() uint
func (base *PosBase) Filename() string
func (base *PosBase) IsFileBase() bool
func (base *PosBase) Line() uint
func (base *PosBase) Pos() (_ Pos)
func (base *PosBase) Trimmed() bool
A Pragma value augments a package, import, const, func, type, or var declaration. Its meaning is entirely up to the PragmaHandler, except that nil is used to mean “no pragma seen.”
type Pragma interface{}
A PragmaHandler is used to process //go: directives while scanning. It is passed the current pragma value, which starts out being nil, and it returns an updated pragma value. The text is the directive, with the "//" prefix stripped. The current pragma is saved at each package, import, const, func, type, or var declaration, into the File, ImportDecl, ConstDecl, FuncDecl, TypeDecl, or VarDecl node.
If text is the empty string, the pragma is being returned to the handler unused, meaning it appeared before a non-declaration. The handler may wish to report an error. In this case, pos is the current parser position, not the position of the pragma itself. Blank specifies whether the line is blank before the pragma.
type PragmaHandler func(pos Pos, blank bool, text string, current Pragma) Pragma
type RangeClause struct {
Lhs Expr // nil means no Lhs = or Lhs :=
Def bool // means :=
X Expr // range X
// contains filtered or unexported fields
}
type ReturnStmt struct {
Results Expr // nil means no explicit return values
// contains filtered or unexported fields
}
type SelectStmt struct {
Body []*CommClause
Rbrace Pos
// contains filtered or unexported fields
}
X.Sel
type SelectorExpr struct {
X Expr
Sel *Name
// contains filtered or unexported fields
}
type SendStmt struct {
Chan, Value Expr // Chan <- Value
// contains filtered or unexported fields
}
type SimpleStmt interface {
Stmt
// contains filtered or unexported methods
}
X[Index[0] : Index[1] : Index[2]]
type SliceExpr struct {
X Expr
Index [3]Expr
// Full indicates whether this is a simple or full slice expression.
// In a valid AST, this is equivalent to Index[2] != nil.
// TODO(mdempsky): This is only needed to report the "3-index
// slice of string" error when Index[2] is missing.
Full bool
// contains filtered or unexported fields
}
[]Elem
type SliceType struct {
Elem Expr
// contains filtered or unexported fields
}
type Stmt interface {
Node
// contains filtered or unexported methods
}
struct { FieldList[0] TagList[0]; FieldList[1] TagList[1]; ... }
type StructType struct {
FieldList []*Field
TagList []*BasicLit // i >= len(TagList) || TagList[i] == nil means no tag for field i
// contains filtered or unexported fields
}
type SwitchStmt struct {
Init SimpleStmt
Tag Expr // incl. *TypeSwitchGuard
Body []*CaseClause
Rbrace Pos
// contains filtered or unexported fields
}
type Token uint
A Type represents a type of Go. All types implement the Type interface. (This type originally lived in types2. We moved it here so we could depend on it from other packages without introducing an import cycle.)
type Type interface {
// Underlying returns the underlying type of a type.
// Underlying types are never Named, TypeParam, or Alias types.
//
// See https://go.dev/ref/spec#Underlying_types.
Underlying() Type
// String returns a string representation of a type.
String() string
}
A TypeAndValue records the type information, constant value if known, and various other flags associated with an expression. This type is similar to types2.TypeAndValue, but exposes none of types2's internals.
type TypeAndValue struct {
Type Type
Value constant.Value
// contains filtered or unexported fields
}
func (f TypeAndValue) Addressable() bool
func (f TypeAndValue) Assignable() bool
func (f TypeAndValue) HasOk() bool
func (f TypeAndValue) IsBuiltin() bool
func (f TypeAndValue) IsNil() bool
func (f TypeAndValue) IsRuntimeHelper() bool
func (f TypeAndValue) IsType() bool
func (f TypeAndValue) IsValue() bool
func (f TypeAndValue) IsVoid() bool
func (f *TypeAndValue) SetAddressable()
func (f *TypeAndValue) SetAssignable()
func (f *TypeAndValue) SetHasOk()
func (f *TypeAndValue) SetIsBuiltin()
func (f *TypeAndValue) SetIsNil()
func (f *TypeAndValue) SetIsRuntimeHelper()
func (f *TypeAndValue) SetIsType()
func (f *TypeAndValue) SetIsValue()
func (f *TypeAndValue) SetIsVoid()
Name Type
type TypeDecl struct {
Group *Group // nil means not part of a group
Pragma Pragma
Name *Name
TParamList []*Field // nil means no type parameters
Alias bool
Type Expr
// contains filtered or unexported fields
}
X.(type) Lhs := X.(type)
type TypeSwitchGuard struct {
Lhs *Name // nil means no Lhs :=
X Expr // X.(type)
// contains filtered or unexported fields
}
NameList Type NameList Type = Values NameList = Values
type VarDecl struct {
Group *Group // nil means not part of a group
Pragma Pragma
NameList []*Name
Type Expr // nil means no type
Values Expr // nil means no values
// contains filtered or unexported fields
}
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).
type Visitor interface {
Visit(node Node) (w Visitor)
}