...
Run Format

Source file src/go/parser/interface.go

Documentation: go/parser

     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/ioutil"
    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  //
    25  func readSource(filename string, src interface{}) ([]byte, error) {
    26  	if src != nil {
    27  		switch s := src.(type) {
    28  		case string:
    29  			return []byte(s), nil
    30  		case []byte:
    31  			return s, nil
    32  		case *bytes.Buffer:
    33  			// is io.Reader, but src is already available in []byte form
    34  			if s != nil {
    35  				return s.Bytes(), nil
    36  			}
    37  		case io.Reader:
    38  			return ioutil.ReadAll(s)
    39  		}
    40  		return nil, errors.New("invalid source")
    41  	}
    42  	return ioutil.ReadFile(filename)
    43  }
    44  
    45  // A Mode value is a set of flags (or 0).
    46  // They control the amount of source code parsed and other optional
    47  // parser functionality.
    48  //
    49  type Mode uint
    50  
    51  const (
    52  	PackageClauseOnly Mode             = 1 << iota // stop parsing after package clause
    53  	ImportsOnly                                    // stop parsing after import declarations
    54  	ParseComments                                  // parse comments and add them to AST
    55  	Trace                                          // print a trace of parsed productions
    56  	DeclarationErrors                              // report declaration errors
    57  	SpuriousErrors                                 // same as AllErrors, for backward-compatibility
    58  	AllErrors         = SpuriousErrors             // report all errors (not just the first 10 on different lines)
    59  )
    60  
    61  // ParseFile parses the source code of a single Go source file and returns
    62  // the corresponding ast.File node. The source code may be provided via
    63  // the filename of the source file, or via the src parameter.
    64  //
    65  // If src != nil, ParseFile parses the source from src and the filename is
    66  // only used when recording position information. The type of the argument
    67  // for the src parameter must be string, []byte, or io.Reader.
    68  // If src == nil, ParseFile parses the file specified by filename.
    69  //
    70  // The mode parameter controls the amount of source text parsed and other
    71  // optional parser functionality. Position information is recorded in the
    72  // file set fset, which must not be nil.
    73  //
    74  // If the source couldn't be read, the returned AST is nil and the error
    75  // indicates the specific failure. If the source was read but syntax
    76  // errors were found, the result is a partial AST (with ast.Bad* nodes
    77  // representing the fragments of erroneous source code). Multiple errors
    78  // are returned via a scanner.ErrorList which is sorted by file position.
    79  //
    80  func ParseFile(fset *token.FileSet, filename string, src interface{}, mode Mode) (f *ast.File, err error) {
    81  	if fset == nil {
    82  		panic("parser.ParseFile: no token.FileSet provided (fset == nil)")
    83  	}
    84  
    85  	// get source
    86  	text, err := readSource(filename, src)
    87  	if err != nil {
    88  		return nil, err
    89  	}
    90  
    91  	var p parser
    92  	defer func() {
    93  		if e := recover(); e != nil {
    94  			// resume same panic if it's not a bailout
    95  			if _, ok := e.(bailout); !ok {
    96  				panic(e)
    97  			}
    98  		}
    99  
   100  		// set result values
   101  		if f == nil {
   102  			// source is not a valid Go source file - satisfy
   103  			// ParseFile API and return a valid (but) empty
   104  			// *ast.File
   105  			f = &ast.File{
   106  				Name:  new(ast.Ident),
   107  				Scope: ast.NewScope(nil),
   108  			}
   109  		}
   110  
   111  		p.errors.Sort()
   112  		err = p.errors.Err()
   113  	}()
   114  
   115  	// parse source
   116  	p.init(fset, filename, text, mode)
   117  	f = p.parseFile()
   118  
   119  	return
   120  }
   121  
   122  // ParseDir calls ParseFile for all files with names ending in ".go" in the
   123  // directory specified by path and returns a map of package name -> package
   124  // AST with all the packages found.
   125  //
   126  // If filter != nil, only the files with os.FileInfo entries passing through
   127  // the filter (and ending in ".go") are considered. The mode bits are passed
   128  // to ParseFile unchanged. Position information is recorded in fset, which
   129  // must not be nil.
   130  //
   131  // If the directory couldn't be read, a nil map and the respective error are
   132  // returned. If a parse error occurred, a non-nil but incomplete map and the
   133  // first error encountered are returned.
   134  //
   135  func ParseDir(fset *token.FileSet, path string, filter func(os.FileInfo) bool, mode Mode) (pkgs map[string]*ast.Package, first error) {
   136  	fd, err := os.Open(path)
   137  	if err != nil {
   138  		return nil, err
   139  	}
   140  	defer fd.Close()
   141  
   142  	list, err := fd.Readdir(-1)
   143  	if err != nil {
   144  		return nil, err
   145  	}
   146  
   147  	pkgs = make(map[string]*ast.Package)
   148  	for _, d := range list {
   149  		if strings.HasSuffix(d.Name(), ".go") && (filter == nil || filter(d)) {
   150  			filename := filepath.Join(path, d.Name())
   151  			if src, err := ParseFile(fset, filename, nil, mode); err == nil {
   152  				name := src.Name.Name
   153  				pkg, found := pkgs[name]
   154  				if !found {
   155  					pkg = &ast.Package{
   156  						Name:  name,
   157  						Files: make(map[string]*ast.File),
   158  					}
   159  					pkgs[name] = pkg
   160  				}
   161  				pkg.Files[filename] = src
   162  			} else if first == nil {
   163  				first = err
   164  			}
   165  		}
   166  	}
   167  
   168  	return
   169  }
   170  
   171  // ParseExprFrom is a convenience function for parsing an expression.
   172  // The arguments have the same meaning as for ParseFile, but the source must
   173  // be a valid Go (type or value) expression. Specifically, fset must not
   174  // be nil.
   175  //
   176  func ParseExprFrom(fset *token.FileSet, filename string, src interface{}, mode Mode) (ast.Expr, error) {
   177  	if fset == nil {
   178  		panic("parser.ParseExprFrom: no token.FileSet provided (fset == nil)")
   179  	}
   180  
   181  	// get source
   182  	text, err := readSource(filename, src)
   183  	if err != nil {
   184  		return nil, err
   185  	}
   186  
   187  	var p parser
   188  	defer func() {
   189  		if e := recover(); e != nil {
   190  			// resume same panic if it's not a bailout
   191  			if _, ok := e.(bailout); !ok {
   192  				panic(e)
   193  			}
   194  		}
   195  		p.errors.Sort()
   196  		err = p.errors.Err()
   197  	}()
   198  
   199  	// parse expr
   200  	p.init(fset, filename, text, mode)
   201  	// Set up pkg-level scopes to avoid nil-pointer errors.
   202  	// This is not needed for a correct expression x as the
   203  	// parser will be ok with a nil topScope, but be cautious
   204  	// in case of an erroneous x.
   205  	p.openScope()
   206  	p.pkgScope = p.topScope
   207  	e := p.parseRhsOrType()
   208  	p.closeScope()
   209  	assert(p.topScope == nil, "unbalanced scopes")
   210  
   211  	// If a semicolon was inserted, consume it;
   212  	// report an error if there's more tokens.
   213  	if p.tok == token.SEMICOLON && p.lit == "\n" {
   214  		p.next()
   215  	}
   216  	p.expect(token.EOF)
   217  
   218  	if p.errors.Len() > 0 {
   219  		p.errors.Sort()
   220  		return nil, p.errors.Err()
   221  	}
   222  
   223  	return e, nil
   224  }
   225  
   226  // ParseExpr is a convenience function for obtaining the AST of an expression x.
   227  // The position information recorded in the AST is undefined. The filename used
   228  // in error messages is the empty string.
   229  //
   230  func ParseExpr(x string) (ast.Expr, error) {
   231  	return ParseExprFrom(token.NewFileSet(), "", []byte(x), 0)
   232  }
   233  

View as plain text