syntax

package standard library
go1.23.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 1, 2024 License: BSD-3-Clause Imports: 11 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// for BranchStmt
	Break       = _Break
	Continue    = _Continue
	Fallthrough = _Fallthrough
	Goto        = _Goto

	// for CallStmt
	Go    = _Go
	Defer = _Defer
)
View Source
const PosMax = 1 << 30

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.

Variables

This section is empty.

Functions

func CommentMap added in go1.21.0

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 added in go1.17

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

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

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 added in go1.18

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

func String(n Node) string

String is a convenience function that prints n in ShortForm and returns the printed string.

func Walk added in go1.17

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.

Types

type ArrayType

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
}

[Len]Elem

type AssertExpr

type AssertExpr struct {
	X    Expr
	Type Expr
	// contains filtered or unexported fields
}

X.(Type)

type AssignStmt

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
}

type BadExpr added in go1.9

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

Placeholder for an expression that failed to parse correctly and where we can't provide a better node.

type BasicLit

type BasicLit struct {
	Value string
	Kind  LitKind
	Bad   bool // true means the literal Value has syntax errors
	// contains filtered or unexported fields
}

Value

type BlockStmt

type BlockStmt struct {
	List   []Stmt
	Rbrace Pos
	// contains filtered or unexported fields
}

type BranchStmt

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
}

type CallExpr

type CallExpr struct {
	Fun     Expr
	ArgList []Expr // nil means no arguments
	HasDots bool   // last argument is followed by ...
	// contains filtered or unexported fields
}

Fun(ArgList[0], ArgList[1], ...)

type CallStmt

type CallStmt struct {
	Tok     token // Go or Defer
	Call    Expr
	DeferAt Expr // argument to runtime.deferprocat
	// contains filtered or unexported fields
}

type CaseClause

type CaseClause struct {
	Cases Expr // nil means default clause
	Body  []Stmt
	Colon Pos
	// contains filtered or unexported fields
}

func (*CaseClause) Pos added in go1.9

func (n *CaseClause) Pos() Pos

func (*CaseClause) SetPos added in go1.22.0

func (n *CaseClause) SetPos(pos Pos)

type ChanDir

type ChanDir uint
const (
	SendOnly ChanDir
	RecvOnly
)

type ChanType

type ChanType struct {
	Dir  ChanDir // 0 means no direction
	Elem Expr
	// contains filtered or unexported fields
}
chan Elem

<-chan Elem chan<- Elem

type CommClause

type CommClause struct {
	Comm  SimpleStmt // send or receive stmt; nil means default clause
	Body  []Stmt
	Colon Pos
	// contains filtered or unexported fields
}

func (*CommClause) Pos added in go1.9

func (n *CommClause) Pos() Pos

func (*CommClause) SetPos added in go1.22.0

func (n *CommClause) SetPos(pos Pos)

type Comment

type Comment struct {
	Kind CommentKind
	Text string
	Next *Comment
}

type CommentKind

type CommentKind uint

TODO(gri) Consider renaming to CommentPos, CommentPlacement, etc. Kind = Above doesn't make much sense.

const (
	Above CommentKind = iota
	Below
	Left
	Right
)

type CompositeLit

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
}

Type { ElemList[0], ElemList[1], ... }

type ConstDecl

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
}

NameList NameList = Values NameList Type = Values

type Decl

type Decl interface {
	Node
	// contains filtered or unexported methods
}

type DeclStmt

type DeclStmt struct {
	DeclList []Decl
	// contains filtered or unexported fields
}

type DotsType

type DotsType struct {
	Elem Expr
	// contains filtered or unexported fields
}

...Elem

type EmptyStmt

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

type Error

type Error struct {
	Pos Pos
	Msg string
}

Error describes a syntax error. Error implements the error interface.

func (Error) Error

func (err Error) Error() string

type ErrorHandler

type ErrorHandler func(err error)

An ErrorHandler is called for each error encountered reading a .go file.

type Expr

type Expr interface {
	Node
	// contains filtered or unexported methods
}

func UnpackListExpr added in go1.22.0

func UnpackListExpr(x Expr) []Expr

UnpackListExpr unpacks a *ListExpr into a []Expr.

func Unparen added in go1.22.0

func Unparen(x Expr) Expr

Unparen returns e with any enclosing parentheses stripped.

type ExprStmt

type ExprStmt struct {
	X Expr
	// contains filtered or unexported fields
}

type Field

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
}

Name Type

Type

func (*Field) Pos added in go1.9

func (n *Field) Pos() Pos

func (*Field) SetPos added in go1.22.0

func (n *Field) SetPos(pos Pos)

type File

type File struct {
	Pragma    Pragma
	PkgName   *Name
	DeclList  []Decl
	EOF       Pos
	GoVersion string
	// contains filtered or unexported fields
}

package PkgName; DeclList[0], DeclList[1], ...

func Parse

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

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 (*File) Pos added in go1.9

func (n *File) Pos() Pos

func (*File) SetPos added in go1.22.0

func (n *File) SetPos(pos Pos)

type ForStmt

type ForStmt struct {
	Init SimpleStmt // incl. *RangeClause
	Cond Expr
	Post SimpleStmt
	Body *BlockStmt
	// contains filtered or unexported fields
}

type Form added in go1.17

type Form uint

Form controls print formatting.

const (
	LineForm  Form // use spaces instead of linebreaks where possible
	ShortForm      // like LineForm but print "…" for non-empty function or composite literal bodies
)

type FuncDecl

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 Name Type { Body } func Name Type func Receiver Name Type { Body } func Receiver Name Type

type FuncLit

type FuncLit struct {
	Type *FuncType
	Body *BlockStmt
	// contains filtered or unexported fields
}

func Type { Body }

type FuncType

type FuncType struct {
	ParamList  []*Field
	ResultList []*Field
	// contains filtered or unexported fields
}

type Group

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

All declarations belonging to the same group point to the same Group node.

type IfStmt

type IfStmt struct {
	Init SimpleStmt
	Cond Expr
	Then *BlockStmt
	Else Stmt // either nil, *IfStmt, or *BlockStmt
	// contains filtered or unexported fields
}

type ImportDecl

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
}
Path

LocalPkgName Path

type IndexExpr

type IndexExpr struct {
	X     Expr
	Index Expr
	// contains filtered or unexported fields
}

X[Index] X[T1, T2, ...] (with Ti = Index.(*ListExpr).ElemList[i])

type InterfaceType

type InterfaceType struct {
	MethodList []*Field
	// contains filtered or unexported fields
}

interface { MethodList[0]; MethodList[1]; ... }

type KeyValueExpr

type KeyValueExpr struct {
	Key, Value Expr
	// contains filtered or unexported fields
}

Key: Value

type LabeledStmt

type LabeledStmt struct {
	Label *Name
	Stmt  Stmt
	// contains filtered or unexported fields
}

type ListExpr

type ListExpr struct {
	ElemList []Expr
	// contains filtered or unexported fields
}

ElemList[0], ElemList[1], ...

type LitKind

type LitKind uint8
const (
	IntLit LitKind = iota
	FloatLit
	ImagLit
	RuneLit
	StringLit
)

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?

type MapType

type MapType struct {
	Key, Value Expr
	// contains filtered or unexported fields
}

map[Key]Value

type Mode

type Mode uint

Mode describes the parser mode.

const (
	CheckBranches Mode = 1 << iota // check correct use of labels, break, continue, and goto statements
)

Modes supported by the parser.

type Name

type Name struct {
	Value string
	// contains filtered or unexported fields
}

Value

func NewName added in go1.17

func NewName(pos Pos, value string) *Name

type Node

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

type Operation struct {
	Op   Operator
	X, Y Expr // Y == nil means unary expression
	// contains filtered or unexported fields
}

type Operator

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 (Operator) String

func (i Operator) String() string

type ParenExpr

type ParenExpr struct {
	X Expr
	// contains filtered or unexported fields
}

(X)

type Pos added in go1.11

type Pos struct {
	// 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.

func EndPos added in go1.17

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 added in go1.11

func MakePos(base *PosBase, line, col uint) Pos

MakePos returns a new Pos for the given PosBase, line and column.

func StartPos added in go1.17

func StartPos(n Node) Pos

StartPos returns the start position of n.

func (Pos) Base added in go1.11

func (pos Pos) Base() *PosBase

func (Pos) Cmp added in go1.17

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) Col added in go1.11

func (pos Pos) Col() uint

func (Pos) FileBase added in go1.23.0

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) IsKnown added in go1.11

func (pos Pos) IsKnown() bool

func (Pos) Line added in go1.11

func (pos Pos) Line() uint

func (Pos) Pos added in go1.17

func (pos Pos) Pos() Pos

func (Pos) RelCol added in go1.11

func (pos Pos) RelCol() uint

func (Pos) RelFilename added in go1.11

func (pos Pos) RelFilename() string

func (Pos) RelLine added in go1.11

func (pos Pos) RelLine() uint

func (Pos) String added in go1.11

func (pos Pos) String() string

type PosBase added in go1.11

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

A PosBase represents the base for relative position information: At position pos, the relative position is filename:line:col.

func NewFileBase added in go1.11

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 added in go1.11

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 added in go1.18

func NewTrimmedFileBase(filename string, trimmed bool) *PosBase

NewTrimmedFileBase is like NewFileBase, but allows specifying Trimmed.

func (*PosBase) Col added in go1.11

func (base *PosBase) Col() uint

func (*PosBase) Filename added in go1.11

func (base *PosBase) Filename() string

func (*PosBase) IsFileBase added in go1.11

func (base *PosBase) IsFileBase() bool

func (*PosBase) Line added in go1.11

func (base *PosBase) Line() uint

func (*PosBase) Pos added in go1.11

func (base *PosBase) Pos() (_ Pos)

func (*PosBase) Trimmed added in go1.18

func (base *PosBase) Trimmed() bool

type Pragma

type Pragma interface{}

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 PragmaHandler

type PragmaHandler func(pos Pos, blank bool, text string, current Pragma) Pragma

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 RangeClause

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

type ReturnStmt struct {
	Results Expr // nil means no explicit return values
	// contains filtered or unexported fields
}

type SelectStmt

type SelectStmt struct {
	Body   []*CommClause
	Rbrace Pos
	// contains filtered or unexported fields
}

type SelectorExpr

type SelectorExpr struct {
	X   Expr
	Sel *Name
	// contains filtered or unexported fields
}

X.Sel

type SendStmt

type SendStmt struct {
	Chan, Value Expr // Chan <- Value
	// contains filtered or unexported fields
}

type SimpleStmt

type SimpleStmt interface {
	Stmt
	// contains filtered or unexported methods
}

type SliceExpr

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
}

X[Index[0] : Index[1] : Index[2]]

type SliceType

type SliceType struct {
	Elem Expr
	// contains filtered or unexported fields
}

[]Elem

type Stmt

type Stmt interface {
	Node
	// contains filtered or unexported methods
}

type StructType

type StructType struct {
	FieldList []*Field
	TagList   []*BasicLit // i >= len(TagList) || TagList[i] == nil means no tag for field i
	// contains filtered or unexported fields
}

struct { FieldList[0] TagList[0]; FieldList[1] TagList[1]; ... }

type SwitchStmt

type SwitchStmt struct {
	Init   SimpleStmt
	Tag    Expr // incl. *TypeSwitchGuard
	Body   []*CaseClause
	Rbrace Pos
	// contains filtered or unexported fields
}

type Token added in go1.22.0

type Token uint

type Type added in go1.20

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 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 TypeAndValue added in go1.20

type TypeAndValue struct {
	Type  Type
	Value constant.Value
	// contains filtered or unexported fields
}

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.

func (TypeAndValue) Addressable added in go1.20

func (f TypeAndValue) Addressable() bool

func (TypeAndValue) Assignable added in go1.20

func (f TypeAndValue) Assignable() bool

func (TypeAndValue) HasOk added in go1.20

func (f TypeAndValue) HasOk() bool

func (TypeAndValue) IsBuiltin added in go1.20

func (f TypeAndValue) IsBuiltin() bool

func (TypeAndValue) IsNil added in go1.20

func (f TypeAndValue) IsNil() bool

func (TypeAndValue) IsRuntimeHelper added in go1.22.0

func (f TypeAndValue) IsRuntimeHelper() bool

func (TypeAndValue) IsType added in go1.20

func (f TypeAndValue) IsType() bool

func (TypeAndValue) IsValue added in go1.20

func (f TypeAndValue) IsValue() bool

func (TypeAndValue) IsVoid added in go1.20

func (f TypeAndValue) IsVoid() bool

func (*TypeAndValue) SetAddressable added in go1.20

func (f *TypeAndValue) SetAddressable()

func (*TypeAndValue) SetAssignable added in go1.20

func (f *TypeAndValue) SetAssignable()

func (*TypeAndValue) SetHasOk added in go1.20

func (f *TypeAndValue) SetHasOk()

func (*TypeAndValue) SetIsBuiltin added in go1.20

func (f *TypeAndValue) SetIsBuiltin()

func (*TypeAndValue) SetIsNil added in go1.20

func (f *TypeAndValue) SetIsNil()

func (*TypeAndValue) SetIsRuntimeHelper added in go1.22.0

func (f *TypeAndValue) SetIsRuntimeHelper()

func (*TypeAndValue) SetIsType added in go1.20

func (f *TypeAndValue) SetIsType()

func (*TypeAndValue) SetIsValue added in go1.20

func (f *TypeAndValue) SetIsValue()

func (*TypeAndValue) SetIsVoid added in go1.20

func (f *TypeAndValue) SetIsVoid()

type TypeDecl

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
}

Name Type

type TypeSwitchGuard

type TypeSwitchGuard struct {
	Lhs *Name // nil means no Lhs :=
	X   Expr  // X.(type)
	// contains filtered or unexported fields
}

X.(type) Lhs := X.(type)

type VarDecl

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
}

NameList Type NameList Type = Values NameList = Values

type Visitor added in go1.18

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL