Source file src/go/ast/ast.go

     1  // Copyright 2009 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  // Package ast declares the types used to represent syntax trees for Go
     6  // packages.
     7  //
     8  // Syntax trees may be constructed directly, but they are typically
     9  // produced from Go source code by the parser; see the ParseFile
    10  // function in package [go/parser].
    11  package ast
    12  
    13  import (
    14  	"go/token"
    15  	"strings"
    16  )
    17  
    18  // ----------------------------------------------------------------------------
    19  // Interfaces
    20  //
    21  // There are 3 main classes of nodes: Expressions and type nodes,
    22  // statement nodes, and declaration nodes. The node names usually
    23  // match the corresponding Go spec production names to which they
    24  // correspond. The node fields correspond to the individual parts
    25  // of the respective productions.
    26  //
    27  // All nodes contain position information marking the beginning of
    28  // the corresponding source text segment; it is accessible via the
    29  // Pos accessor method. Nodes may contain additional position info
    30  // for language constructs where comments may be found between parts
    31  // of the construct (typically any larger, parenthesized subpart).
    32  // That position information is needed to properly position comments
    33  // when printing the construct.
    34  
    35  // All node types implement the Node interface.
    36  type Node interface {
    37  	Pos() token.Pos // position of first character belonging to the node
    38  	End() token.Pos // position of first character immediately after the node
    39  }
    40  
    41  // All expression nodes implement the Expr interface.
    42  type Expr interface {
    43  	Node
    44  	exprNode()
    45  }
    46  
    47  // All statement nodes implement the Stmt interface.
    48  type Stmt interface {
    49  	Node
    50  	stmtNode()
    51  }
    52  
    53  // All declaration nodes implement the Decl interface.
    54  type Decl interface {
    55  	Node
    56  	declNode()
    57  }
    58  
    59  // ----------------------------------------------------------------------------
    60  // Comments
    61  
    62  // A Comment node represents a single //-style or /*-style comment.
    63  //
    64  // The Text field contains the comment text without carriage returns (\r) that
    65  // may have been present in the source. Because a comment's end position is
    66  // computed using len(Text), the position reported by [Comment.End] does not match the
    67  // true source end position for comments containing carriage returns.
    68  type Comment struct {
    69  	Slash token.Pos // position of "/" starting the comment
    70  	Text  string    // comment text (excluding '\n' for //-style comments)
    71  }
    72  
    73  func (c *Comment) Pos() token.Pos { return c.Slash }
    74  func (c *Comment) End() token.Pos { return token.Pos(int(c.Slash) + len(c.Text)) }
    75  
    76  // A CommentGroup represents a sequence of comments
    77  // with no other tokens and no empty lines between.
    78  type CommentGroup struct {
    79  	List []*Comment // len(List) > 0
    80  }
    81  
    82  func (g *CommentGroup) Pos() token.Pos { return g.List[0].Pos() }
    83  func (g *CommentGroup) End() token.Pos { return g.List[len(g.List)-1].End() }
    84  
    85  func isWhitespace(ch byte) bool { return ch == ' ' || ch == '\t' || ch == '\n' || ch == '\r' }
    86  
    87  func stripTrailingWhitespace(s string) string {
    88  	i := len(s)
    89  	for i > 0 && isWhitespace(s[i-1]) {
    90  		i--
    91  	}
    92  	return s[0:i]
    93  }
    94  
    95  // Text returns the text of the comment.
    96  // Comment markers (//, /*, and */), the first space of a line comment, and
    97  // leading and trailing empty lines are removed.
    98  // Comment directives like "//line" and "//go:noinline" are also removed.
    99  // Multiple empty lines are reduced to one, and trailing space on lines is trimmed.
   100  // Unless the result is empty, it is newline-terminated.
   101  func (g *CommentGroup) Text() string {
   102  	if g == nil {
   103  		return ""
   104  	}
   105  	comments := make([]string, len(g.List))
   106  	for i, c := range g.List {
   107  		comments[i] = c.Text
   108  	}
   109  
   110  	lines := make([]string, 0, 10) // most comments are less than 10 lines
   111  	for _, c := range comments {
   112  		// Remove comment markers.
   113  		// The parser has given us exactly the comment text.
   114  		switch c[1] {
   115  		case '/':
   116  			//-style comment (no newline at the end)
   117  			c = c[2:]
   118  			if len(c) == 0 {
   119  				// empty line
   120  				break
   121  			}
   122  			if c[0] == ' ' {
   123  				// strip first space - required for Example tests
   124  				c = c[1:]
   125  				break
   126  			}
   127  			if isDirective(c) {
   128  				// Ignore //go:noinline, //line, and so on.
   129  				continue
   130  			}
   131  		case '*':
   132  			/*-style comment */
   133  			c = c[2 : len(c)-2]
   134  		}
   135  
   136  		// Split on newlines.
   137  		cl := strings.SplitSeq(c, "\n")
   138  
   139  		// Walk lines, stripping trailing white space and adding to list.
   140  		for l := range cl {
   141  			lines = append(lines, stripTrailingWhitespace(l))
   142  		}
   143  	}
   144  
   145  	// Remove leading blank lines; convert runs of
   146  	// interior blank lines to a single blank line.
   147  	n := 0
   148  	for _, line := range lines {
   149  		if line != "" || n > 0 && lines[n-1] != "" {
   150  			lines[n] = line
   151  			n++
   152  		}
   153  	}
   154  	lines = lines[0:n]
   155  
   156  	// Add final "" entry to get trailing newline from Join.
   157  	if n > 0 && lines[n-1] != "" {
   158  		lines = append(lines, "")
   159  	}
   160  
   161  	return strings.Join(lines, "\n")
   162  }
   163  
   164  // isDirective reports whether c is a comment directive.
   165  // This code is also in go/printer.
   166  func isDirective(c string) bool {
   167  	// "//line " is a line directive.
   168  	// "//extern " is for gccgo.
   169  	// "//export " is for cgo.
   170  	// (The // has been removed.)
   171  	if strings.HasPrefix(c, "line ") || strings.HasPrefix(c, "extern ") || strings.HasPrefix(c, "export ") {
   172  		return true
   173  	}
   174  
   175  	// "//[a-z0-9]+:[a-z0-9]"
   176  	// (The // has been removed.)
   177  	colon := strings.Index(c, ":")
   178  	if colon <= 0 || colon+1 >= len(c) {
   179  		return false
   180  	}
   181  	for i := 0; i <= colon+1; i++ {
   182  		if i == colon {
   183  			continue
   184  		}
   185  		b := c[i]
   186  		if !('a' <= b && b <= 'z' || '0' <= b && b <= '9') {
   187  			return false
   188  		}
   189  	}
   190  	return true
   191  }
   192  
   193  // ----------------------------------------------------------------------------
   194  // Expressions and types
   195  
   196  // A Field represents a Field declaration list in a struct type,
   197  // a method list in an interface type, or a parameter/result declaration
   198  // in a signature.
   199  // [Field.Names] is nil for unnamed parameters (parameter lists which only contain types)
   200  // and embedded struct fields. In the latter case, the field name is the type name.
   201  type Field struct {
   202  	Doc     *CommentGroup // associated documentation; or nil
   203  	Names   []*Ident      // field/method/(type) parameter names; or nil
   204  	Type    Expr          // field/method/parameter type; or nil
   205  	Tag     *BasicLit     // field tag; or nil
   206  	Comment *CommentGroup // line comments; or nil
   207  }
   208  
   209  func (f *Field) Pos() token.Pos {
   210  	if len(f.Names) > 0 {
   211  		return f.Names[0].Pos()
   212  	}
   213  	if f.Type != nil {
   214  		return f.Type.Pos()
   215  	}
   216  	return token.NoPos
   217  }
   218  
   219  func (f *Field) End() token.Pos {
   220  	if f.Tag != nil {
   221  		return f.Tag.End()
   222  	}
   223  	if f.Type != nil {
   224  		return f.Type.End()
   225  	}
   226  	if len(f.Names) > 0 {
   227  		return f.Names[len(f.Names)-1].End()
   228  	}
   229  	return token.NoPos
   230  }
   231  
   232  // A FieldList represents a list of Fields, enclosed by parentheses,
   233  // curly braces, or square brackets.
   234  type FieldList struct {
   235  	Opening token.Pos // position of opening parenthesis/brace/bracket, if any
   236  	List    []*Field  // field list; or nil
   237  	Closing token.Pos // position of closing parenthesis/brace/bracket, if any
   238  }
   239  
   240  func (f *FieldList) Pos() token.Pos {
   241  	if f.Opening.IsValid() {
   242  		return f.Opening
   243  	}
   244  	// the list should not be empty in this case;
   245  	// be conservative and guard against bad ASTs
   246  	if len(f.List) > 0 {
   247  		return f.List[0].Pos()
   248  	}
   249  	return token.NoPos
   250  }
   251  
   252  func (f *FieldList) End() token.Pos {
   253  	if f.Closing.IsValid() {
   254  		return f.Closing + 1
   255  	}
   256  	// the list should not be empty in this case;
   257  	// be conservative and guard against bad ASTs
   258  	if n := len(f.List); n > 0 {
   259  		return f.List[n-1].End()
   260  	}
   261  	return token.NoPos
   262  }
   263  
   264  // NumFields returns the number of parameters or struct fields represented by a [FieldList].
   265  func (f *FieldList) NumFields() int {
   266  	n := 0
   267  	if f != nil {
   268  		for _, g := range f.List {
   269  			m := len(g.Names)
   270  			if m == 0 {
   271  				m = 1
   272  			}
   273  			n += m
   274  		}
   275  	}
   276  	return n
   277  }
   278  
   279  // An expression is represented by a tree consisting of one
   280  // or more of the following concrete expression nodes.
   281  type (
   282  	// A BadExpr node is a placeholder for an expression containing
   283  	// syntax errors for which a correct expression node cannot be
   284  	// created.
   285  	//
   286  	BadExpr struct {
   287  		From, To token.Pos // position range of bad expression
   288  	}
   289  
   290  	// An Ident node represents an identifier.
   291  	Ident struct {
   292  		NamePos token.Pos // identifier position
   293  		Name    string    // identifier name
   294  		Obj     *Object   // denoted object, or nil. Deprecated: see Object.
   295  	}
   296  
   297  	// An Ellipsis node stands for the "..." type in a
   298  	// parameter list or the "..." length in an array type.
   299  	//
   300  	Ellipsis struct {
   301  		Ellipsis token.Pos // position of "..."
   302  		Elt      Expr      // ellipsis element type (parameter lists only); or nil
   303  	}
   304  
   305  	// A BasicLit node represents a literal of basic type.
   306  	//
   307  	// Note that for the CHAR and STRING kinds, the literal is stored
   308  	// with its quotes. For example, for a double-quoted STRING, the
   309  	// first and the last rune in the Value field will be ". The
   310  	// [strconv.Unquote] and [strconv.UnquoteChar] functions can be
   311  	// used to unquote STRING and CHAR values, respectively.
   312  	//
   313  	// For raw string literals (Kind == token.STRING && Value[0] == '`'),
   314  	// the Value field contains the string text without carriage returns (\r) that
   315  	// may have been present in the source.
   316  	BasicLit struct {
   317  		ValuePos token.Pos   // literal position
   318  		ValueEnd token.Pos   // position immediately after the literal
   319  		Kind     token.Token // token.INT, token.FLOAT, token.IMAG, token.CHAR, or token.STRING
   320  		Value    string      // literal string; e.g. 42, 0x7f, 3.14, 1e-9, 2.4i, 'a', '\x7f', "foo" or `\m\n\o`
   321  	}
   322  
   323  	// A FuncLit node represents a function literal.
   324  	FuncLit struct {
   325  		Type *FuncType  // function type
   326  		Body *BlockStmt // function body
   327  	}
   328  
   329  	// A CompositeLit node represents a composite literal.
   330  	CompositeLit struct {
   331  		Type       Expr      // literal type; or nil
   332  		Lbrace     token.Pos // position of "{"
   333  		Elts       []Expr    // list of composite elements; or nil
   334  		Rbrace     token.Pos // position of "}"
   335  		Incomplete bool      // true if (source) expressions are missing in the Elts list
   336  	}
   337  
   338  	// A ParenExpr node represents a parenthesized expression.
   339  	ParenExpr struct {
   340  		Lparen token.Pos // position of "("
   341  		X      Expr      // parenthesized expression
   342  		Rparen token.Pos // position of ")"
   343  	}
   344  
   345  	// A SelectorExpr node represents an expression followed by a selector.
   346  	SelectorExpr struct {
   347  		X   Expr   // expression
   348  		Sel *Ident // field selector
   349  	}
   350  
   351  	// An IndexExpr node represents an expression followed by an index.
   352  	IndexExpr struct {
   353  		X      Expr      // expression
   354  		Lbrack token.Pos // position of "["
   355  		Index  Expr      // index expression
   356  		Rbrack token.Pos // position of "]"
   357  	}
   358  
   359  	// An IndexListExpr node represents an expression followed by multiple
   360  	// indices.
   361  	IndexListExpr struct {
   362  		X       Expr      // expression
   363  		Lbrack  token.Pos // position of "["
   364  		Indices []Expr    // index expressions
   365  		Rbrack  token.Pos // position of "]"
   366  	}
   367  
   368  	// A SliceExpr node represents an expression followed by slice indices.
   369  	SliceExpr struct {
   370  		X      Expr      // expression
   371  		Lbrack token.Pos // position of "["
   372  		Low    Expr      // begin of slice range; or nil
   373  		High   Expr      // end of slice range; or nil
   374  		Max    Expr      // maximum capacity of slice; or nil
   375  		Slice3 bool      // true if 3-index slice (2 colons present)
   376  		Rbrack token.Pos // position of "]"
   377  	}
   378  
   379  	// A TypeAssertExpr node represents an expression followed by a
   380  	// type assertion.
   381  	//
   382  	TypeAssertExpr struct {
   383  		X      Expr      // expression
   384  		Lparen token.Pos // position of "("
   385  		Type   Expr      // asserted type; nil means type switch X.(type)
   386  		Rparen token.Pos // position of ")"
   387  	}
   388  
   389  	// A CallExpr node represents an expression followed by an argument list.
   390  	CallExpr struct {
   391  		Fun      Expr      // function expression
   392  		Lparen   token.Pos // position of "("
   393  		Args     []Expr    // function arguments; or nil
   394  		Ellipsis token.Pos // position of "..." (token.NoPos if there is no "...")
   395  		Rparen   token.Pos // position of ")"
   396  	}
   397  
   398  	// A StarExpr node represents an expression of the form "*" Expression.
   399  	// Semantically it could be a unary "*" expression, or a pointer type.
   400  	//
   401  	StarExpr struct {
   402  		Star token.Pos // position of "*"
   403  		X    Expr      // operand
   404  	}
   405  
   406  	// A UnaryExpr node represents a unary expression.
   407  	// Unary "*" expressions are represented via StarExpr nodes.
   408  	//
   409  	UnaryExpr struct {
   410  		OpPos token.Pos   // position of Op
   411  		Op    token.Token // operator
   412  		X     Expr        // operand
   413  	}
   414  
   415  	// A BinaryExpr node represents a binary expression.
   416  	BinaryExpr struct {
   417  		X     Expr        // left operand
   418  		OpPos token.Pos   // position of Op
   419  		Op    token.Token // operator
   420  		Y     Expr        // right operand
   421  	}
   422  
   423  	// A KeyValueExpr node represents (key : value) pairs
   424  	// in composite literals.
   425  	//
   426  	KeyValueExpr struct {
   427  		Key   Expr
   428  		Colon token.Pos // position of ":"
   429  		Value Expr
   430  	}
   431  )
   432  
   433  // The direction of a channel type is indicated by a bit
   434  // mask including one or both of the following constants.
   435  type ChanDir int
   436  
   437  const (
   438  	SEND ChanDir = 1 << iota
   439  	RECV
   440  )
   441  
   442  // A type is represented by a tree consisting of one
   443  // or more of the following type-specific expression
   444  // nodes.
   445  type (
   446  	// An ArrayType node represents an array or slice type.
   447  	ArrayType struct {
   448  		Lbrack token.Pos // position of "["
   449  		Len    Expr      // Ellipsis node for [...]T array types, nil for slice types
   450  		Elt    Expr      // element type
   451  	}
   452  
   453  	// A StructType node represents a struct type.
   454  	StructType struct {
   455  		Struct     token.Pos  // position of "struct" keyword
   456  		Fields     *FieldList // list of field declarations
   457  		Incomplete bool       // true if (source) fields are missing in the Fields list
   458  	}
   459  
   460  	// Pointer types are represented via StarExpr nodes.
   461  
   462  	// A FuncType node represents a function type.
   463  	FuncType struct {
   464  		Func       token.Pos  // position of "func" keyword (token.NoPos if there is no "func")
   465  		TypeParams *FieldList // type parameters; or nil
   466  		Params     *FieldList // (incoming) parameters; non-nil
   467  		Results    *FieldList // (outgoing) results; or nil
   468  	}
   469  
   470  	// An InterfaceType node represents an interface type.
   471  	InterfaceType struct {
   472  		Interface  token.Pos  // position of "interface" keyword
   473  		Methods    *FieldList // list of embedded interfaces, methods, or types
   474  		Incomplete bool       // true if (source) methods or types are missing in the Methods list
   475  	}
   476  
   477  	// A MapType node represents a map type.
   478  	MapType struct {
   479  		Map   token.Pos // position of "map" keyword
   480  		Key   Expr
   481  		Value Expr
   482  	}
   483  
   484  	// A ChanType node represents a channel type.
   485  	ChanType struct {
   486  		Begin token.Pos // position of "chan" keyword or "<-" (whichever comes first)
   487  		Arrow token.Pos // position of "<-" (token.NoPos if there is no "<-")
   488  		Dir   ChanDir   // channel direction
   489  		Value Expr      // value type
   490  	}
   491  )
   492  
   493  // Pos and End implementations for expression/type nodes.
   494  
   495  func (x *BadExpr) Pos() token.Pos  { return x.From }
   496  func (x *Ident) Pos() token.Pos    { return x.NamePos }
   497  func (x *Ellipsis) Pos() token.Pos { return x.Ellipsis }
   498  func (x *BasicLit) Pos() token.Pos { return x.ValuePos }
   499  func (x *FuncLit) Pos() token.Pos  { return x.Type.Pos() }
   500  func (x *CompositeLit) Pos() token.Pos {
   501  	if x.Type != nil {
   502  		return x.Type.Pos()
   503  	}
   504  	return x.Lbrace
   505  }
   506  func (x *ParenExpr) Pos() token.Pos      { return x.Lparen }
   507  func (x *SelectorExpr) Pos() token.Pos   { return x.X.Pos() }
   508  func (x *IndexExpr) Pos() token.Pos      { return x.X.Pos() }
   509  func (x *IndexListExpr) Pos() token.Pos  { return x.X.Pos() }
   510  func (x *SliceExpr) Pos() token.Pos      { return x.X.Pos() }
   511  func (x *TypeAssertExpr) Pos() token.Pos { return x.X.Pos() }
   512  func (x *CallExpr) Pos() token.Pos       { return x.Fun.Pos() }
   513  func (x *StarExpr) Pos() token.Pos       { return x.Star }
   514  func (x *UnaryExpr) Pos() token.Pos      { return x.OpPos }
   515  func (x *BinaryExpr) Pos() token.Pos     { return x.X.Pos() }
   516  func (x *KeyValueExpr) Pos() token.Pos   { return x.Key.Pos() }
   517  func (x *ArrayType) Pos() token.Pos      { return x.Lbrack }
   518  func (x *StructType) Pos() token.Pos     { return x.Struct }
   519  func (x *FuncType) Pos() token.Pos {
   520  	if x.Func.IsValid() || x.Params == nil { // see issue 3870
   521  		return x.Func
   522  	}
   523  	return x.Params.Pos() // interface method declarations have no "func" keyword
   524  }
   525  func (x *InterfaceType) Pos() token.Pos { return x.Interface }
   526  func (x *MapType) Pos() token.Pos       { return x.Map }
   527  func (x *ChanType) Pos() token.Pos      { return x.Begin }
   528  
   529  func (x *BadExpr) End() token.Pos { return x.To }
   530  func (x *Ident) End() token.Pos   { return token.Pos(int(x.NamePos) + len(x.Name)) }
   531  func (x *Ellipsis) End() token.Pos {
   532  	if x.Elt != nil {
   533  		return x.Elt.End()
   534  	}
   535  	return x.Ellipsis + 3 // len("...")
   536  }
   537  func (x *BasicLit) End() token.Pos {
   538  	if !x.ValueEnd.IsValid() {
   539  		// Not from parser; use a heuristic.
   540  		// (Incorrect for `...` containing \r\n;
   541  		// see https://go.dev/issue/76031.)
   542  		return token.Pos(int(x.ValuePos) + len(x.Value))
   543  	}
   544  	return x.ValueEnd
   545  }
   546  func (x *FuncLit) End() token.Pos        { return x.Body.End() }
   547  func (x *CompositeLit) End() token.Pos   { return x.Rbrace + 1 }
   548  func (x *ParenExpr) End() token.Pos      { return x.Rparen + 1 }
   549  func (x *SelectorExpr) End() token.Pos   { return x.Sel.End() }
   550  func (x *IndexExpr) End() token.Pos      { return x.Rbrack + 1 }
   551  func (x *IndexListExpr) End() token.Pos  { return x.Rbrack + 1 }
   552  func (x *SliceExpr) End() token.Pos      { return x.Rbrack + 1 }
   553  func (x *TypeAssertExpr) End() token.Pos { return x.Rparen + 1 }
   554  func (x *CallExpr) End() token.Pos       { return x.Rparen + 1 }
   555  func (x *StarExpr) End() token.Pos       { return x.X.End() }
   556  func (x *UnaryExpr) End() token.Pos      { return x.X.End() }
   557  func (x *BinaryExpr) End() token.Pos     { return x.Y.End() }
   558  func (x *KeyValueExpr) End() token.Pos   { return x.Value.End() }
   559  func (x *ArrayType) End() token.Pos      { return x.Elt.End() }
   560  func (x *StructType) End() token.Pos     { return x.Fields.End() }
   561  func (x *FuncType) End() token.Pos {
   562  	if x.Results != nil {
   563  		return x.Results.End()
   564  	}
   565  	return x.Params.End()
   566  }
   567  func (x *InterfaceType) End() token.Pos { return x.Methods.End() }
   568  func (x *MapType) End() token.Pos       { return x.Value.End() }
   569  func (x *ChanType) End() token.Pos      { return x.Value.End() }
   570  
   571  // exprNode() ensures that only expression/type nodes can be
   572  // assigned to an Expr.
   573  func (*BadExpr) exprNode()        {}
   574  func (*Ident) exprNode()          {}
   575  func (*Ellipsis) exprNode()       {}
   576  func (*BasicLit) exprNode()       {}
   577  func (*FuncLit) exprNode()        {}
   578  func (*CompositeLit) exprNode()   {}
   579  func (*ParenExpr) exprNode()      {}
   580  func (*SelectorExpr) exprNode()   {}
   581  func (*IndexExpr) exprNode()      {}
   582  func (*IndexListExpr) exprNode()  {}
   583  func (*SliceExpr) exprNode()      {}
   584  func (*TypeAssertExpr) exprNode() {}
   585  func (*CallExpr) exprNode()       {}
   586  func (*StarExpr) exprNode()       {}
   587  func (*UnaryExpr) exprNode()      {}
   588  func (*BinaryExpr) exprNode()     {}
   589  func (*KeyValueExpr) exprNode()   {}
   590  
   591  func (*ArrayType) exprNode()     {}
   592  func (*StructType) exprNode()    {}
   593  func (*FuncType) exprNode()      {}
   594  func (*InterfaceType) exprNode() {}
   595  func (*MapType) exprNode()       {}
   596  func (*ChanType) exprNode()      {}
   597  
   598  // ----------------------------------------------------------------------------
   599  // Convenience functions for Idents
   600  
   601  // NewIdent creates a new [Ident] without position.
   602  // Useful for ASTs generated by code other than the Go parser.
   603  func NewIdent(name string) *Ident { return &Ident{token.NoPos, name, nil} }
   604  
   605  // IsExported reports whether name starts with an upper-case letter.
   606  func IsExported(name string) bool { return token.IsExported(name) }
   607  
   608  // IsExported reports whether id starts with an upper-case letter.
   609  func (id *Ident) IsExported() bool { return token.IsExported(id.Name) }
   610  
   611  func (id *Ident) String() string {
   612  	if id != nil {
   613  		return id.Name
   614  	}
   615  	return "<nil>"
   616  }
   617  
   618  // ----------------------------------------------------------------------------
   619  // Statements
   620  
   621  // A statement is represented by a tree consisting of one
   622  // or more of the following concrete statement nodes.
   623  type (
   624  	// A BadStmt node is a placeholder for statements containing
   625  	// syntax errors for which no correct statement nodes can be
   626  	// created.
   627  	//
   628  	BadStmt struct {
   629  		From, To token.Pos // position range of bad statement
   630  	}
   631  
   632  	// A DeclStmt node represents a declaration in a statement list.
   633  	DeclStmt struct {
   634  		Decl Decl // *GenDecl with CONST, TYPE, or VAR token
   635  	}
   636  
   637  	// An EmptyStmt node represents an empty statement.
   638  	// The "position" of the empty statement is the position
   639  	// of the immediately following (explicit or implicit) semicolon.
   640  	//
   641  	EmptyStmt struct {
   642  		Semicolon token.Pos // position of following ";"
   643  		Implicit  bool      // if set, ";" was omitted in the source
   644  	}
   645  
   646  	// A LabeledStmt node represents a labeled statement.
   647  	LabeledStmt struct {
   648  		Label *Ident
   649  		Colon token.Pos // position of ":"
   650  		Stmt  Stmt
   651  	}
   652  
   653  	// An ExprStmt node represents a (stand-alone) expression
   654  	// in a statement list.
   655  	//
   656  	ExprStmt struct {
   657  		X Expr // expression
   658  	}
   659  
   660  	// A SendStmt node represents a send statement.
   661  	SendStmt struct {
   662  		Chan  Expr
   663  		Arrow token.Pos // position of "<-"
   664  		Value Expr
   665  	}
   666  
   667  	// An IncDecStmt node represents an increment or decrement statement.
   668  	IncDecStmt struct {
   669  		X      Expr
   670  		TokPos token.Pos   // position of Tok
   671  		Tok    token.Token // INC or DEC
   672  	}
   673  
   674  	// An AssignStmt node represents an assignment or
   675  	// a short variable declaration.
   676  	//
   677  	AssignStmt struct {
   678  		Lhs    []Expr
   679  		TokPos token.Pos   // position of Tok
   680  		Tok    token.Token // assignment token, DEFINE
   681  		Rhs    []Expr
   682  	}
   683  
   684  	// A GoStmt node represents a go statement.
   685  	GoStmt struct {
   686  		Go   token.Pos // position of "go" keyword
   687  		Call *CallExpr
   688  	}
   689  
   690  	// A DeferStmt node represents a defer statement.
   691  	DeferStmt struct {
   692  		Defer token.Pos // position of "defer" keyword
   693  		Call  *CallExpr
   694  	}
   695  
   696  	// A ReturnStmt node represents a return statement.
   697  	ReturnStmt struct {
   698  		Return  token.Pos // position of "return" keyword
   699  		Results []Expr    // result expressions; or nil
   700  	}
   701  
   702  	// A BranchStmt node represents a break, continue, goto,
   703  	// or fallthrough statement.
   704  	//
   705  	BranchStmt struct {
   706  		TokPos token.Pos   // position of Tok
   707  		Tok    token.Token // keyword token (BREAK, CONTINUE, GOTO, FALLTHROUGH)
   708  		Label  *Ident      // label name; or nil
   709  	}
   710  
   711  	// A BlockStmt node represents a braced statement list.
   712  	BlockStmt struct {
   713  		Lbrace token.Pos // position of "{"
   714  		List   []Stmt
   715  		Rbrace token.Pos // position of "}", if any (may be absent due to syntax error)
   716  	}
   717  
   718  	// An IfStmt node represents an if statement.
   719  	IfStmt struct {
   720  		If   token.Pos // position of "if" keyword
   721  		Init Stmt      // initialization statement; or nil
   722  		Cond Expr      // condition
   723  		Body *BlockStmt
   724  		Else Stmt // else branch; or nil
   725  	}
   726  
   727  	// A CaseClause represents a case of an expression or type switch statement.
   728  	CaseClause struct {
   729  		Case  token.Pos // position of "case" or "default" keyword
   730  		List  []Expr    // list of expressions or types; nil means default case
   731  		Colon token.Pos // position of ":"
   732  		Body  []Stmt    // statement list; or nil
   733  	}
   734  
   735  	// A SwitchStmt node represents an expression switch statement.
   736  	SwitchStmt struct {
   737  		Switch token.Pos  // position of "switch" keyword
   738  		Init   Stmt       // initialization statement; or nil
   739  		Tag    Expr       // tag expression; or nil
   740  		Body   *BlockStmt // CaseClauses only
   741  	}
   742  
   743  	// A TypeSwitchStmt node represents a type switch statement.
   744  	TypeSwitchStmt struct {
   745  		Switch token.Pos  // position of "switch" keyword
   746  		Init   Stmt       // initialization statement; or nil
   747  		Assign Stmt       // x := y.(type) or y.(type)
   748  		Body   *BlockStmt // CaseClauses only
   749  	}
   750  
   751  	// A CommClause node represents a case of a select statement.
   752  	CommClause struct {
   753  		Case  token.Pos // position of "case" or "default" keyword
   754  		Comm  Stmt      // send or receive statement; nil means default case
   755  		Colon token.Pos // position of ":"
   756  		Body  []Stmt    // statement list; or nil
   757  	}
   758  
   759  	// A SelectStmt node represents a select statement.
   760  	SelectStmt struct {
   761  		Select token.Pos  // position of "select" keyword
   762  		Body   *BlockStmt // CommClauses only
   763  	}
   764  
   765  	// A ForStmt represents a for statement.
   766  	ForStmt struct {
   767  		For  token.Pos // position of "for" keyword
   768  		Init Stmt      // initialization statement; or nil
   769  		Cond Expr      // condition; or nil
   770  		Post Stmt      // post iteration statement; or nil
   771  		Body *BlockStmt
   772  	}
   773  
   774  	// A RangeStmt represents a for statement with a range clause.
   775  	RangeStmt struct {
   776  		For        token.Pos   // position of "for" keyword
   777  		Key, Value Expr        // Key, Value may be nil
   778  		TokPos     token.Pos   // position of Tok; invalid if Key == nil
   779  		Tok        token.Token // ILLEGAL if Key == nil, ASSIGN, DEFINE
   780  		Range      token.Pos   // position of "range" keyword
   781  		X          Expr        // value to range over
   782  		Body       *BlockStmt
   783  	}
   784  )
   785  
   786  // Pos and End implementations for statement nodes.
   787  
   788  func (s *BadStmt) Pos() token.Pos        { return s.From }
   789  func (s *DeclStmt) Pos() token.Pos       { return s.Decl.Pos() }
   790  func (s *EmptyStmt) Pos() token.Pos      { return s.Semicolon }
   791  func (s *LabeledStmt) Pos() token.Pos    { return s.Label.Pos() }
   792  func (s *ExprStmt) Pos() token.Pos       { return s.X.Pos() }
   793  func (s *SendStmt) Pos() token.Pos       { return s.Chan.Pos() }
   794  func (s *IncDecStmt) Pos() token.Pos     { return s.X.Pos() }
   795  func (s *AssignStmt) Pos() token.Pos     { return s.Lhs[0].Pos() }
   796  func (s *GoStmt) Pos() token.Pos         { return s.Go }
   797  func (s *DeferStmt) Pos() token.Pos      { return s.Defer }
   798  func (s *ReturnStmt) Pos() token.Pos     { return s.Return }
   799  func (s *BranchStmt) Pos() token.Pos     { return s.TokPos }
   800  func (s *BlockStmt) Pos() token.Pos      { return s.Lbrace }
   801  func (s *IfStmt) Pos() token.Pos         { return s.If }
   802  func (s *CaseClause) Pos() token.Pos     { return s.Case }
   803  func (s *SwitchStmt) Pos() token.Pos     { return s.Switch }
   804  func (s *TypeSwitchStmt) Pos() token.Pos { return s.Switch }
   805  func (s *CommClause) Pos() token.Pos     { return s.Case }
   806  func (s *SelectStmt) Pos() token.Pos     { return s.Select }
   807  func (s *ForStmt) Pos() token.Pos        { return s.For }
   808  func (s *RangeStmt) Pos() token.Pos      { return s.For }
   809  
   810  func (s *BadStmt) End() token.Pos  { return s.To }
   811  func (s *DeclStmt) End() token.Pos { return s.Decl.End() }
   812  func (s *EmptyStmt) End() token.Pos {
   813  	if s.Implicit {
   814  		return s.Semicolon
   815  	}
   816  	return s.Semicolon + 1 /* len(";") */
   817  }
   818  func (s *LabeledStmt) End() token.Pos { return s.Stmt.End() }
   819  func (s *ExprStmt) End() token.Pos    { return s.X.End() }
   820  func (s *SendStmt) End() token.Pos    { return s.Value.End() }
   821  func (s *IncDecStmt) End() token.Pos {
   822  	return s.TokPos + 2 /* len("++") */
   823  }
   824  func (s *AssignStmt) End() token.Pos { return s.Rhs[len(s.Rhs)-1].End() }
   825  func (s *GoStmt) End() token.Pos     { return s.Call.End() }
   826  func (s *DeferStmt) End() token.Pos  { return s.Call.End() }
   827  func (s *ReturnStmt) End() token.Pos {
   828  	if n := len(s.Results); n > 0 {
   829  		return s.Results[n-1].End()
   830  	}
   831  	return s.Return + 6 // len("return")
   832  }
   833  func (s *BranchStmt) End() token.Pos {
   834  	if s.Label != nil {
   835  		return s.Label.End()
   836  	}
   837  	return token.Pos(int(s.TokPos) + len(s.Tok.String()))
   838  }
   839  func (s *BlockStmt) End() token.Pos {
   840  	if s.Rbrace.IsValid() {
   841  		return s.Rbrace + 1
   842  	}
   843  	if n := len(s.List); n > 0 {
   844  		return s.List[n-1].End()
   845  	}
   846  	return s.Lbrace + 1
   847  }
   848  func (s *IfStmt) End() token.Pos {
   849  	if s.Else != nil {
   850  		return s.Else.End()
   851  	}
   852  	return s.Body.End()
   853  }
   854  func (s *CaseClause) End() token.Pos {
   855  	if n := len(s.Body); n > 0 {
   856  		return s.Body[n-1].End()
   857  	}
   858  	return s.Colon + 1
   859  }
   860  func (s *SwitchStmt) End() token.Pos     { return s.Body.End() }
   861  func (s *TypeSwitchStmt) End() token.Pos { return s.Body.End() }
   862  func (s *CommClause) End() token.Pos {
   863  	if n := len(s.Body); n > 0 {
   864  		return s.Body[n-1].End()
   865  	}
   866  	return s.Colon + 1
   867  }
   868  func (s *SelectStmt) End() token.Pos { return s.Body.End() }
   869  func (s *ForStmt) End() token.Pos    { return s.Body.End() }
   870  func (s *RangeStmt) End() token.Pos  { return s.Body.End() }
   871  
   872  // stmtNode() ensures that only statement nodes can be
   873  // assigned to a Stmt.
   874  func (*BadStmt) stmtNode()        {}
   875  func (*DeclStmt) stmtNode()       {}
   876  func (*EmptyStmt) stmtNode()      {}
   877  func (*LabeledStmt) stmtNode()    {}
   878  func (*ExprStmt) stmtNode()       {}
   879  func (*SendStmt) stmtNode()       {}
   880  func (*IncDecStmt) stmtNode()     {}
   881  func (*AssignStmt) stmtNode()     {}
   882  func (*GoStmt) stmtNode()         {}
   883  func (*DeferStmt) stmtNode()      {}
   884  func (*ReturnStmt) stmtNode()     {}
   885  func (*BranchStmt) stmtNode()     {}
   886  func (*BlockStmt) stmtNode()      {}
   887  func (*IfStmt) stmtNode()         {}
   888  func (*CaseClause) stmtNode()     {}
   889  func (*SwitchStmt) stmtNode()     {}
   890  func (*TypeSwitchStmt) stmtNode() {}
   891  func (*CommClause) stmtNode()     {}
   892  func (*SelectStmt) stmtNode()     {}
   893  func (*ForStmt) stmtNode()        {}
   894  func (*RangeStmt) stmtNode()      {}
   895  
   896  // ----------------------------------------------------------------------------
   897  // Declarations
   898  
   899  // A Spec node represents a single (non-parenthesized) import,
   900  // constant, type, or variable declaration.
   901  type (
   902  	// The Spec type stands for any of *ImportSpec, *ValueSpec, and *TypeSpec.
   903  	Spec interface {
   904  		Node
   905  		specNode()
   906  	}
   907  
   908  	// An ImportSpec node represents a single package import.
   909  	ImportSpec struct {
   910  		Doc     *CommentGroup // associated documentation; or nil
   911  		Name    *Ident        // local package name (including "."); or nil
   912  		Path    *BasicLit     // import path
   913  		Comment *CommentGroup // line comments; or nil
   914  		EndPos  token.Pos     // end of spec (overrides Path.Pos if nonzero)
   915  	}
   916  
   917  	// A ValueSpec node represents a constant or variable declaration
   918  	// (ConstSpec or VarSpec production).
   919  	//
   920  	ValueSpec struct {
   921  		Doc     *CommentGroup // associated documentation; or nil
   922  		Names   []*Ident      // value names (len(Names) > 0)
   923  		Type    Expr          // value type; or nil
   924  		Values  []Expr        // initial values; or nil
   925  		Comment *CommentGroup // line comments; or nil
   926  	}
   927  
   928  	// A TypeSpec node represents a type declaration (TypeSpec production).
   929  	TypeSpec struct {
   930  		Doc        *CommentGroup // associated documentation; or nil
   931  		Name       *Ident        // type name
   932  		TypeParams *FieldList    // type parameters; or nil
   933  		Assign     token.Pos     // position of '=', if any
   934  		Type       Expr          // *Ident, *ParenExpr, *SelectorExpr, *StarExpr, or any of the *XxxTypes
   935  		Comment    *CommentGroup // line comments; or nil
   936  	}
   937  )
   938  
   939  // Pos and End implementations for spec nodes.
   940  
   941  func (s *ImportSpec) Pos() token.Pos {
   942  	if s.Name != nil {
   943  		return s.Name.Pos()
   944  	}
   945  	return s.Path.Pos()
   946  }
   947  func (s *ValueSpec) Pos() token.Pos { return s.Names[0].Pos() }
   948  func (s *TypeSpec) Pos() token.Pos  { return s.Name.Pos() }
   949  
   950  func (s *ImportSpec) End() token.Pos {
   951  	if s.EndPos != 0 {
   952  		return s.EndPos
   953  	}
   954  	return s.Path.End()
   955  }
   956  
   957  func (s *ValueSpec) End() token.Pos {
   958  	if n := len(s.Values); n > 0 {
   959  		return s.Values[n-1].End()
   960  	}
   961  	if s.Type != nil {
   962  		return s.Type.End()
   963  	}
   964  	return s.Names[len(s.Names)-1].End()
   965  }
   966  func (s *TypeSpec) End() token.Pos { return s.Type.End() }
   967  
   968  // specNode() ensures that only spec nodes can be
   969  // assigned to a Spec.
   970  func (*ImportSpec) specNode() {}
   971  func (*ValueSpec) specNode()  {}
   972  func (*TypeSpec) specNode()   {}
   973  
   974  // A declaration is represented by one of the following declaration nodes.
   975  type (
   976  	// A BadDecl node is a placeholder for a declaration containing
   977  	// syntax errors for which a correct declaration node cannot be
   978  	// created.
   979  	//
   980  	BadDecl struct {
   981  		From, To token.Pos // position range of bad declaration
   982  	}
   983  
   984  	// A GenDecl node (generic declaration node) represents an import,
   985  	// constant, type or variable declaration. A valid Lparen position
   986  	// (Lparen.IsValid()) indicates a parenthesized declaration.
   987  	//
   988  	// Relationship between Tok value and Specs element type:
   989  	//
   990  	//	token.IMPORT  *ImportSpec
   991  	//	token.CONST   *ValueSpec
   992  	//	token.TYPE    *TypeSpec
   993  	//	token.VAR     *ValueSpec
   994  	//
   995  	GenDecl struct {
   996  		Doc    *CommentGroup // associated documentation; or nil
   997  		TokPos token.Pos     // position of Tok
   998  		Tok    token.Token   // IMPORT, CONST, TYPE, or VAR
   999  		Lparen token.Pos     // position of '(', if any
  1000  		Specs  []Spec
  1001  		Rparen token.Pos // position of ')', if any
  1002  	}
  1003  
  1004  	// A FuncDecl node represents a function declaration.
  1005  	FuncDecl struct {
  1006  		Doc  *CommentGroup // associated documentation; or nil
  1007  		Recv *FieldList    // receiver (methods); or nil (functions)
  1008  		Name *Ident        // function/method name
  1009  		Type *FuncType     // function signature: type and value parameters, results, and position of "func" keyword
  1010  		Body *BlockStmt    // function body; or nil for external (non-Go) function
  1011  	}
  1012  )
  1013  
  1014  // Pos and End implementations for declaration nodes.
  1015  
  1016  func (d *BadDecl) Pos() token.Pos  { return d.From }
  1017  func (d *GenDecl) Pos() token.Pos  { return d.TokPos }
  1018  func (d *FuncDecl) Pos() token.Pos { return d.Type.Pos() }
  1019  
  1020  func (d *BadDecl) End() token.Pos { return d.To }
  1021  func (d *GenDecl) End() token.Pos {
  1022  	if d.Rparen.IsValid() {
  1023  		return d.Rparen + 1
  1024  	}
  1025  	return d.Specs[0].End()
  1026  }
  1027  func (d *FuncDecl) End() token.Pos {
  1028  	if d.Body != nil {
  1029  		return d.Body.End()
  1030  	}
  1031  	return d.Type.End()
  1032  }
  1033  
  1034  // declNode() ensures that only declaration nodes can be
  1035  // assigned to a Decl.
  1036  func (*BadDecl) declNode()  {}
  1037  func (*GenDecl) declNode()  {}
  1038  func (*FuncDecl) declNode() {}
  1039  
  1040  // ----------------------------------------------------------------------------
  1041  // Files and packages
  1042  
  1043  // A File node represents a Go source file.
  1044  //
  1045  // The Comments list contains all comments in the source file in order of
  1046  // appearance, including the comments that are pointed to from other nodes
  1047  // via Doc and Comment fields.
  1048  //
  1049  // For correct printing of source code containing comments (using packages
  1050  // go/format and go/printer), special care must be taken to update comments
  1051  // when a File's syntax tree is modified: For printing, comments are interspersed
  1052  // between tokens based on their position. If syntax tree nodes are
  1053  // removed or moved, relevant comments in their vicinity must also be removed
  1054  // (from the [File.Comments] list) or moved accordingly (by updating their
  1055  // positions). A [CommentMap] may be used to facilitate some of these operations.
  1056  //
  1057  // Whether and how a comment is associated with a node depends on the
  1058  // interpretation of the syntax tree by the manipulating program: except for Doc
  1059  // and [Comment] comments directly associated with nodes, the remaining comments
  1060  // are "free-floating" (see also issues [#18593], [#20744]).
  1061  //
  1062  // [#18593]: https://go.dev/issue/18593
  1063  // [#20744]: https://go.dev/issue/20744
  1064  type File struct {
  1065  	Doc     *CommentGroup // associated documentation; or nil
  1066  	Package token.Pos     // position of "package" keyword
  1067  	Name    *Ident        // package name
  1068  	Decls   []Decl        // top-level declarations; or nil
  1069  
  1070  	FileStart, FileEnd token.Pos       // start and end of entire file
  1071  	Scope              *Scope          // package scope (this file only). Deprecated: see Object
  1072  	Imports            []*ImportSpec   // imports in this file
  1073  	Unresolved         []*Ident        // unresolved identifiers in this file. Deprecated: see Object
  1074  	Comments           []*CommentGroup // comments in the file, in lexical order
  1075  	GoVersion          string          // minimum Go version required by //go:build or // +build directives
  1076  }
  1077  
  1078  // Pos returns the position of the package declaration.
  1079  // It may be invalid, for example in an empty file.
  1080  //
  1081  // (Use FileStart for the start of the entire file. It is always valid.)
  1082  func (f *File) Pos() token.Pos { return f.Package }
  1083  
  1084  // End returns the end of the last declaration in the file.
  1085  // It may be invalid, for example in an empty file.
  1086  //
  1087  // (Use FileEnd for the end of the entire file. It is always valid.)
  1088  func (f *File) End() token.Pos {
  1089  	if n := len(f.Decls); n > 0 {
  1090  		return f.Decls[n-1].End()
  1091  	}
  1092  	return f.Name.End()
  1093  }
  1094  
  1095  // A Package node represents a set of source files
  1096  // collectively building a Go package.
  1097  //
  1098  // Deprecated: use the type checker [go/types] instead; see [Object].
  1099  type Package struct {
  1100  	Name    string             // package name
  1101  	Scope   *Scope             // package scope across all files
  1102  	Imports map[string]*Object // map of package id -> package object
  1103  	Files   map[string]*File   // Go source files by filename
  1104  }
  1105  
  1106  func (p *Package) Pos() token.Pos { return token.NoPos }
  1107  func (p *Package) End() token.Pos { return token.NoPos }
  1108  
  1109  // IsGenerated reports whether the file was generated by a program,
  1110  // not handwritten, by detecting the special comment described
  1111  // at https://go.dev/s/generatedcode.
  1112  //
  1113  // The syntax tree must have been parsed with the [parser.ParseComments] flag.
  1114  // Example:
  1115  //
  1116  //	f, err := parser.ParseFile(fset, filename, src, parser.ParseComments|parser.PackageClauseOnly)
  1117  //	if err != nil { ... }
  1118  //	gen := ast.IsGenerated(f)
  1119  func IsGenerated(file *File) bool {
  1120  	_, ok := generator(file)
  1121  	return ok
  1122  }
  1123  
  1124  func generator(file *File) (string, bool) {
  1125  	for _, group := range file.Comments {
  1126  		for _, comment := range group.List {
  1127  			if comment.Pos() > file.Package {
  1128  				break // after package declaration
  1129  			}
  1130  			// opt: check Contains first to avoid unnecessary array allocation in Split.
  1131  			const prefix = "// Code generated "
  1132  			if strings.Contains(comment.Text, prefix) {
  1133  				for line := range strings.SplitSeq(comment.Text, "\n") {
  1134  					if rest, ok := strings.CutPrefix(line, prefix); ok {
  1135  						if gen, ok := strings.CutSuffix(rest, " DO NOT EDIT."); ok {
  1136  							return gen, true
  1137  						}
  1138  					}
  1139  				}
  1140  			}
  1141  		}
  1142  	}
  1143  	return "", false
  1144  }
  1145  
  1146  // Unparen returns the expression with any enclosing parentheses removed.
  1147  func Unparen(e Expr) Expr {
  1148  	for {
  1149  		paren, ok := e.(*ParenExpr)
  1150  		if !ok {
  1151  			return e
  1152  		}
  1153  		e = paren.X
  1154  	}
  1155  }
  1156  

View as plain text