Source file src/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/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 var p parser 96 defer func() { 97 if e := recover(); e != nil { 98 // resume same panic if it's not a bailout 99 bail, ok := e.(bailout) 100 if !ok { 101 panic(e) 102 } else if bail.msg != "" { 103 p.errors.Add(p.file.Position(bail.pos), bail.msg) 104 } 105 } 106 107 // set result values 108 if f == nil { 109 // source is not a valid Go source file - satisfy 110 // ParseFile API and return a valid (but) empty 111 // *ast.File 112 f = &ast.File{ 113 Name: new(ast.Ident), 114 Scope: ast.NewScope(nil), 115 } 116 } 117 118 p.errors.Sort() 119 err = p.errors.Err() 120 }() 121 122 // parse source 123 p.init(fset, filename, text, mode) 124 f = p.parseFile() 125 126 return 127 } 128 129 // ParseDir calls [ParseFile] for all files with names ending in ".go" in the 130 // directory specified by path and returns a map of package name -> package 131 // AST with all the packages found. 132 // 133 // If filter != nil, only the files with [fs.FileInfo] entries passing through 134 // the filter (and ending in ".go") are considered. The mode bits are passed 135 // to [ParseFile] unchanged. Position information is recorded in fset, which 136 // must not be nil. 137 // 138 // If the directory couldn't be read, a nil map and the respective error are 139 // returned. If a parse error occurred, a non-nil but incomplete map and the 140 // first error encountered are returned. 141 func ParseDir(fset *token.FileSet, path string, filter func(fs.FileInfo) bool, mode Mode) (pkgs map[string]*ast.Package, first error) { 142 list, err := os.ReadDir(path) 143 if err != nil { 144 return nil, err 145 } 146 147 pkgs = make(map[string]*ast.Package) 148 for _, d := range list { 149 if d.IsDir() || !strings.HasSuffix(d.Name(), ".go") { 150 continue 151 } 152 if filter != nil { 153 info, err := d.Info() 154 if err != nil { 155 return nil, err 156 } 157 if !filter(info) { 158 continue 159 } 160 } 161 filename := filepath.Join(path, d.Name()) 162 if src, err := ParseFile(fset, filename, nil, mode); err == nil { 163 name := src.Name.Name 164 pkg, found := pkgs[name] 165 if !found { 166 pkg = &ast.Package{ 167 Name: name, 168 Files: make(map[string]*ast.File), 169 } 170 pkgs[name] = pkg 171 } 172 pkg.Files[filename] = src 173 } else if first == nil { 174 first = err 175 } 176 } 177 178 return 179 } 180 181 // ParseExprFrom is a convenience function for parsing an expression. 182 // The arguments have the same meaning as for [ParseFile], but the source must 183 // be a valid Go (type or value) expression. Specifically, fset must not 184 // be nil. 185 // 186 // If the source couldn't be read, the returned AST is nil and the error 187 // indicates the specific failure. If the source was read but syntax 188 // errors were found, the result is a partial AST (with [ast.Bad]* nodes 189 // representing the fragments of erroneous source code). Multiple errors 190 // are returned via a scanner.ErrorList which is sorted by source position. 191 func ParseExprFrom(fset *token.FileSet, filename string, src any, mode Mode) (expr ast.Expr, err error) { 192 if fset == nil { 193 panic("parser.ParseExprFrom: no token.FileSet provided (fset == nil)") 194 } 195 196 // get source 197 text, err := readSource(filename, src) 198 if err != nil { 199 return nil, err 200 } 201 202 var p parser 203 defer func() { 204 if e := recover(); e != nil { 205 // resume same panic if it's not a bailout 206 bail, ok := e.(bailout) 207 if !ok { 208 panic(e) 209 } else if bail.msg != "" { 210 p.errors.Add(p.file.Position(bail.pos), bail.msg) 211 } 212 } 213 p.errors.Sort() 214 err = p.errors.Err() 215 }() 216 217 // parse expr 218 p.init(fset, filename, text, mode) 219 expr = p.parseRhs() 220 221 // If a semicolon was inserted, consume it; 222 // report an error if there's more tokens. 223 if p.tok == token.SEMICOLON && p.lit == "\n" { 224 p.next() 225 } 226 p.expect(token.EOF) 227 228 return 229 } 230 231 // ParseExpr is a convenience function for obtaining the AST of an expression x. 232 // The position information recorded in the AST is undefined. The filename used 233 // in error messages is the empty string. 234 // 235 // If syntax errors were found, the result is a partial AST (with [ast.Bad]* nodes 236 // representing the fragments of erroneous source code). Multiple errors are 237 // returned via a scanner.ErrorList which is sorted by source position. 238 func ParseExpr(x string) (ast.Expr, error) { 239 return ParseExprFrom(token.NewFileSet(), "", []byte(x), 0) 240 } 241