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 7package parser 8 9import ( 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// 25func 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 io.ReadAll(s) 39 } 40 return nil, errors.New("invalid source") 41 } 42 return os.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// 49type Mode uint 50 51const ( 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// 80func 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 fs.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// 135func ParseDir(fset *token.FileSet, path string, filter func(fs.FileInfo) bool, mode Mode) (pkgs map[string]*ast.Package, first error) { 136 list, err := os.ReadDir(path) 137 if err != nil { 138 return nil, err 139 } 140 141 pkgs = make(map[string]*ast.Package) 142 for _, d := range list { 143 if d.IsDir() || !strings.HasSuffix(d.Name(), ".go") { 144 continue 145 } 146 if filter != nil { 147 info, err := d.Info() 148 if err != nil { 149 return nil, err 150 } 151 if !filter(info) { 152 continue 153 } 154 } 155 filename := filepath.Join(path, d.Name()) 156 if src, err := ParseFile(fset, filename, nil, mode); err == nil { 157 name := src.Name.Name 158 pkg, found := pkgs[name] 159 if !found { 160 pkg = &ast.Package{ 161 Name: name, 162 Files: make(map[string]*ast.File), 163 } 164 pkgs[name] = pkg 165 } 166 pkg.Files[filename] = src 167 } else if first == nil { 168 first = err 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// If the source couldn't be read, the returned AST is nil and the error 181// indicates the specific failure. If the source was read but syntax 182// errors were found, the result is a partial AST (with ast.Bad* nodes 183// representing the fragments of erroneous source code). Multiple errors 184// are returned via a scanner.ErrorList which is sorted by source position. 185// 186func ParseExprFrom(fset *token.FileSet, filename string, src interface{}, mode Mode) (expr ast.Expr, err error) { 187 if fset == nil { 188 panic("parser.ParseExprFrom: no token.FileSet provided (fset == nil)") 189 } 190 191 // get source 192 text, err := readSource(filename, src) 193 if err != nil { 194 return nil, err 195 } 196 197 var p parser 198 defer func() { 199 if e := recover(); e != nil { 200 // resume same panic if it's not a bailout 201 if _, ok := e.(bailout); !ok { 202 panic(e) 203 } 204 } 205 p.errors.Sort() 206 err = p.errors.Err() 207 }() 208 209 // parse expr 210 p.init(fset, filename, text, mode) 211 // Set up pkg-level scopes to avoid nil-pointer errors. 212 // This is not needed for a correct expression x as the 213 // parser will be ok with a nil topScope, but be cautious 214 // in case of an erroneous x. 215 p.openScope() 216 p.pkgScope = p.topScope 217 expr = p.parseRhsOrType() 218 p.closeScope() 219 assert(p.topScope == nil, "unbalanced scopes") 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// 239func ParseExpr(x string) (ast.Expr, error) { 240 return ParseExprFrom(token.NewFileSet(), "", []byte(x), 0) 241} 242