1 // Copyright 2016 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 package syntax 6 7 import ( 8 "fmt" 9 "io" 10 "os" 11 ) 12 13 // Mode describes the parser mode. 14 type Mode uint 15 16 // Modes supported by the parser. 17 const ( 18 CheckBranches Mode = 1 << iota // check correct use of labels, break, continue, and goto statements 19 ) 20 21 // Error describes a syntax error. Error implements the error interface. 22 type Error struct { 23 Pos Pos 24 Msg string 25 } 26 27 func (err Error) Error() string { 28 return fmt.Sprintf("%s: %s", err.Pos, err.Msg) 29 } 30 31 var _ error = Error{} // verify that Error implements error 32 33 // An ErrorHandler is called for each error encountered reading a .go file. 34 type ErrorHandler func(err error) 35 36 // A Pragma value augments a package, import, const, func, type, or var declaration. 37 // Its meaning is entirely up to the PragmaHandler, 38 // except that nil is used to mean “no pragma seen.” 39 type Pragma interface{} 40 41 // A PragmaHandler is used to process //go: directives while scanning. 42 // It is passed the current pragma value, which starts out being nil, 43 // and it returns an updated pragma value. 44 // The text is the directive, with the "//" prefix stripped. 45 // The current pragma is saved at each package, import, const, func, type, or var 46 // declaration, into the File, ImportDecl, ConstDecl, FuncDecl, TypeDecl, or VarDecl node. 47 // 48 // If text is the empty string, the pragma is being returned 49 // to the handler unused, meaning it appeared before a non-declaration. 50 // The handler may wish to report an error. In this case, pos is the 51 // current parser position, not the position of the pragma itself. 52 // Blank specifies whether the line is blank before the pragma. 53 type PragmaHandler func(pos Pos, blank bool, text string, current Pragma) Pragma 54 55 // Parse parses a single Go source file from src and returns the corresponding 56 // syntax tree. If there are errors, Parse will return the first error found, 57 // and a possibly partially constructed syntax tree, or nil. 58 // 59 // If errh != nil, it is called with each error encountered, and Parse will 60 // process as much source as possible. In this case, the returned syntax tree 61 // is only nil if no correct package clause was found. 62 // If errh is nil, Parse will terminate immediately upon encountering the first 63 // error, and the returned syntax tree is nil. 64 // 65 // If pragh != nil, it is called with each pragma encountered. 66 func Parse(base *PosBase, src io.Reader, errh ErrorHandler, pragh PragmaHandler, mode Mode) (_ *File, first error) { 67 defer func() { 68 if p := recover(); p != nil { 69 if err, ok := p.(Error); ok { 70 first = err 71 return 72 } 73 panic(p) 74 } 75 }() 76 77 var p parser 78 p.init(base, src, errh, pragh, mode) 79 p.next() 80 return p.fileOrNil(), p.first 81 } 82 83 // ParseFile behaves like Parse but it reads the source from the named file. 84 func ParseFile(filename string, errh ErrorHandler, pragh PragmaHandler, mode Mode) (*File, error) { 85 f, err := os.Open(filename) 86 if err != nil { 87 if errh != nil { 88 errh(err) 89 } 90 return nil, err 91 } 92 defer f.Close() 93 return Parse(NewFileBase(filename), f, errh, pragh, mode) 94 } 95