libgo/go/go/parser/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/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 source 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 // If the source couldn't be read, the returned AST is nil and the error
 177 // indicates the specific failure. If the source was read but syntax
 178 // errors were found, the result is a partial AST (with ast.Bad* nodes
 179 // representing the fragments of erroneous source code). Multiple errors
 180 // are returned via a scanner.ErrorList which is sorted by source position.
 181 //
 182 func ParseExprFrom(fset *token.FileSet, filename string, src interface{}, mode Mode) (expr ast.Expr, err error) {
 183         if fset == nil {
 184                 panic("parser.ParseExprFrom: no token.FileSet provided (fset == nil)")
 185         }
 186
 187         // get source
 188         text, err := readSource(filename, src)
 189         if err != nil {
 190                 return nil, err
 191         }
 192
 193         var p parser
 194         defer func() {
 195                 if e := recover(); e != nil {
 196                         // resume same panic if it's not a bailout
 197                         if _, ok := e.(bailout); !ok {
 198                                 panic(e)
 199                         }
 200                 }
 201                 p.errors.Sort()
 202                 err = p.errors.Err()
 203         }()
 204
 205         // parse expr
 206         p.init(fset, filename, text, mode)
 207         // Set up pkg-level scopes to avoid nil-pointer errors.
 208         // This is not needed for a correct expression x as the
 209         // parser will be ok with a nil topScope, but be cautious
 210         // in case of an erroneous x.
 211         p.openScope()
 212         p.pkgScope = p.topScope
 213         expr = p.parseRhsOrType()
 214         p.closeScope()
 215         assert(p.topScope == nil, "unbalanced scopes")
 216
 217         // If a semicolon was inserted, consume it;
 218         // report an error if there's more tokens.
 219         if p.tok == token.SEMICOLON && p.lit == "\n" {
 220                 p.next()
 221         }
 222         p.expect(token.EOF)
 223
 224         return
 225 }
 226
 227 // ParseExpr is a convenience function for obtaining the AST of an expression x.
 228 // The position information recorded in the AST is undefined. The filename used
 229 // in error messages is the empty string.
 230 //
 231 // If syntax errors were found, the result is a partial AST (with ast.Bad* nodes
 232 // representing the fragments of erroneous source code). Multiple errors are
 233 // returned via a scanner.ErrorList which is sorted by source position.
 234 //
 235 func ParseExpr(x string) (ast.Expr, error) {
 236         return ParseExprFrom(token.NewFileSet(), "", []byte(x), 0)
 237 }