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

View as plain text