interface.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  // This file contains the exported entry points for invoking the parser.
     6  
     7  package parser
     8  
     9  import (
    10  	"bytes"
    11  	"errors"
    12  	"go/ast"
    13  	"go/token"
    14  	"io"
    15  	"io/fs"
    16  	"os"
    17  	"path/filepath"
    18  	"strings"
    19  )
    20  
    21  // If src != nil, readSource converts src to a []byte if possible;
    22  // otherwise it returns an error. If src == nil, readSource returns
    23  // the result of reading the file specified by filename.
    24  func readSource(filename string, src any) ([]byte, error) {
    25  	if src != nil {
    26  		switch s := src.(type) {
    27  		case string:
    28  			return []byte(s), nil
    29  		case []byte:
    30  			return s, nil
    31  		case *bytes.Buffer:
    32  			// is io.Reader, but src is already available in []byte form
    33  			if s != nil {
    34  				return s.Bytes(), nil
    35  			}
    36  		case io.Reader:
    37  			return io.ReadAll(s)
    38  		}
    39  		return nil, errors.New("invalid source")
    40  	}
    41  	return os.ReadFile(filename)
    42  }
    43  
    44  // A Mode value is a set of flags (or 0).
    45  // They control the amount of source code parsed and other optional
    46  // parser functionality.
    47  type Mode uint
    48  
    49  const (
    50  	PackageClauseOnly    Mode             = 1 << iota // stop parsing after package clause
    51  	ImportsOnly                                       // stop parsing after import declarations
    52  	ParseComments                                     // parse comments and add them to AST
    53  	Trace                                             // print a trace of parsed productions
    54  	DeclarationErrors                                 // report declaration errors
    55  	SpuriousErrors                                    // same as AllErrors, for backward-compatibility
    56  	SkipObjectResolution                              // skip deprecated identifier resolution; see ParseFile
    57  	AllErrors            = SpuriousErrors             // report all errors (not just the first 10 on different lines)
    58  )
    59  
    60  // ParseFile parses the source code of a single Go source file and returns
    61  // the corresponding [ast.File] node. The source code may be provided via
    62  // the filename of the source file, or via the src parameter.
    63  //
    64  // If src != nil, ParseFile parses the source from src and the filename is
    65  // only used when recording position information. The type of the argument
    66  // for the src parameter must be string, []byte, or [io.Reader].
    67  // If src == nil, ParseFile parses the file specified by filename.
    68  //
    69  // The mode parameter controls the amount of source text parsed and
    70  // other optional parser functionality. If the [SkipObjectResolution]
    71  // mode bit is set (recommended), the object resolution phase of
    72  // parsing will be skipped, causing File.Scope, File.Unresolved, and
    73  // all Ident.Obj fields to be nil. Those fields are deprecated; see
    74  // [ast.Object] for details.
    75  //
    76  // Position information is recorded in the file set fset, which must not be
    77  // nil.
    78  //
    79  // If the source couldn't be read, the returned AST is nil and the error
    80  // indicates the specific failure. If the source was read but syntax
    81  // errors were found, the result is a partial AST (with [ast.Bad]* nodes
    82  // representing the fragments of erroneous source code). Multiple errors
    83  // are returned via a scanner.ErrorList which is sorted by source position.
    84  func ParseFile(fset *token.FileSet, filename string, src any, mode Mode) (f *ast.File, err error) {
    85  	if fset == nil {
    86  		panic("parser.ParseFile: no token.FileSet provided (fset == nil)")
    87  	}
    88  
    89  	// get source
    90  	text, err := readSource(filename, src)
    91  	if err != nil {
    92  		return nil, err
    93  	}
    94  
    95  	file := fset.AddFile(filename, -1, len(text))
    96  
    97  	var p parser
    98  	defer func() {
    99  		if e := recover(); e != nil {
   100  			// resume same panic if it's not a bailout
   101  			bail, ok := e.(bailout)
   102  			if !ok {
   103  				panic(e)
   104  			} else if bail.msg != "" {
   105  				p.errors.Add(p.file.Position(bail.pos), bail.msg)
   106  			}
   107  		}
   108  
   109  		// set result values
   110  		if f == nil {
   111  			// source is not a valid Go source file - satisfy
   112  			// ParseFile API and return a valid (but) empty
   113  			// *ast.File
   114  			f = &ast.File{
   115  				Name:  new(ast.Ident),
   116  				Scope: ast.NewScope(nil),
   117  			}
   118  		}
   119  
   120  		// Ensure the start/end are consistent,
   121  		// whether parsing succeeded or not.
   122  		f.FileStart = token.Pos(file.Base())
   123  		f.FileEnd = token.Pos(file.Base() + file.Size())
   124  
   125  		p.errors.Sort()
   126  		err = p.errors.Err()
   127  	}()
   128  
   129  	// parse source
   130  	p.init(file, text, mode)
   131  	f = p.parseFile()
   132  
   133  	return
   134  }
   135  
   136  // ParseDir calls [ParseFile] for all files with names ending in ".go" in the
   137  // directory specified by path and returns a map of package name -> package
   138  // AST with all the packages found.
   139  //
   140  // If filter != nil, only the files with [fs.FileInfo] entries passing through
   141  // the filter (and ending in ".go") are considered. The mode bits are passed
   142  // to [ParseFile] unchanged. Position information is recorded in fset, which
   143  // must not be nil.
   144  //
   145  // If the directory couldn't be read, a nil map and the respective error are
   146  // returned. If a parse error occurred, a non-nil but incomplete map and the
   147  // first error encountered are returned.
   148  //
   149  // Deprecated: ParseDir does not consider build tags when associating
   150  // files with packages. For precise information about the relationship
   151  // between packages and files, use golang.org/x/tools/go/packages,
   152  // which can also optionally parse and type-check the files too.
   153  func ParseDir(fset *token.FileSet, path string, filter func(fs.FileInfo) bool, mode Mode) (pkgs map[string]*ast.Package, first error) {
   154  	list, err := os.ReadDir(path)
   155  	if err != nil {
   156  		return nil, err
   157  	}
   158  
   159  	pkgs = make(map[string]*ast.Package)
   160  	for _, d := range list {
   161  		if d.IsDir() || !strings.HasSuffix(d.Name(), ".go") {
   162  			continue
   163  		}
   164  		if filter != nil {
   165  			info, err := d.Info()
   166  			if err != nil {
   167  				return nil, err
   168  			}
   169  			if !filter(info) {
   170  				continue
   171  			}
   172  		}
   173  		filename := filepath.Join(path, d.Name())
   174  		if src, err := ParseFile(fset, filename, nil, mode); err == nil {
   175  			name := src.Name.Name
   176  			pkg, found := pkgs[name]
   177  			if !found {
   178  				pkg = &ast.Package{
   179  					Name:  name,
   180  					Files: make(map[string]*ast.File),
   181  				}
   182  				pkgs[name] = pkg
   183  			}
   184  			pkg.Files[filename] = src
   185  		} else if first == nil {
   186  			first = err
   187  		}
   188  	}
   189  
   190  	return
   191  }
   192  
   193  // ParseExprFrom is a convenience function for parsing an expression.
   194  // The arguments have the same meaning as for [ParseFile], but the source must
   195  // be a valid Go (type or value) expression. Specifically, fset must not
   196  // be nil.
   197  //
   198  // If the source couldn't be read, the returned AST is nil and the error
   199  // indicates the specific failure. If the source was read but syntax
   200  // errors were found, the result is a partial AST (with [ast.Bad]* nodes
   201  // representing the fragments of erroneous source code). Multiple errors
   202  // are returned via a scanner.ErrorList which is sorted by source position.
   203  func ParseExprFrom(fset *token.FileSet, filename string, src any, mode Mode) (expr ast.Expr, err error) {
   204  	if fset == nil {
   205  		panic("parser.ParseExprFrom: no token.FileSet provided (fset == nil)")
   206  	}
   207  
   208  	// get source
   209  	text, err := readSource(filename, src)
   210  	if err != nil {
   211  		return nil, err
   212  	}
   213  
   214  	var p parser
   215  	defer func() {
   216  		if e := recover(); e != nil {
   217  			// resume same panic if it's not a bailout
   218  			bail, ok := e.(bailout)
   219  			if !ok {
   220  				panic(e)
   221  			} else if bail.msg != "" {
   222  				p.errors.Add(p.file.Position(bail.pos), bail.msg)
   223  			}
   224  		}
   225  		p.errors.Sort()
   226  		err = p.errors.Err()
   227  	}()
   228  
   229  	// parse expr
   230  	file := fset.AddFile(filename, -1, len(text))
   231  	p.init(file, text, mode)
   232  	expr = p.parseRhs()
   233  
   234  	// If a semicolon was inserted, consume it;
   235  	// report an error if there's more tokens.
   236  	if p.tok == token.SEMICOLON && p.lit == "\n" {
   237  		p.next()
   238  	}
   239  	p.expect(token.EOF)
   240  
   241  	return
   242  }
   243  
   244  // ParseExpr is a convenience function for obtaining the AST of an expression x.
   245  // The position information recorded in the AST is undefined. The filename used
   246  // in error messages is the empty string.
   247  //
   248  // If syntax errors were found, the result is a partial AST (with [ast.Bad]* nodes
   249  // representing the fragments of erroneous source code). Multiple errors are
   250  // returned via a scanner.ErrorList which is sorted by source position.
   251  func ParseExpr(x string) (ast.Expr, error) {
   252  	return ParseExprFrom(token.NewFileSet(), "", []byte(x), 0)
   253  }
   254
View as plain text