diff options
Diffstat (limited to 'devdocs/go/go%2Fparser%2Findex.html')
| -rw-r--r-- | devdocs/go/go%2Fparser%2Findex.html | 68 |
1 files changed, 68 insertions, 0 deletions
diff --git a/devdocs/go/go%2Fparser%2Findex.html b/devdocs/go/go%2Fparser%2Findex.html new file mode 100644 index 00000000..8a527fed --- /dev/null +++ b/devdocs/go/go%2Fparser%2Findex.html @@ -0,0 +1,68 @@ +<h1> Package parser </h1> <ul id="short-nav"> +<li><code>import "go/parser"</code></li> +<li><a href="#pkg-overview" class="overviewLink">Overview</a></li> +<li><a href="#pkg-index" class="indexLink">Index</a></li> +<li><a href="#pkg-examples" class="examplesLink">Examples</a></li> +</ul> <h2 id="pkg-overview">Overview </h2> <p>Package parser implements a parser for Go source files. Input may be provided in a variety of forms (see the various Parse* functions); the output is an abstract syntax tree (AST) representing the Go source. The parser is invoked through one of the Parse* functions. </p> +<p>The parser accepts a larger language than is syntactically permitted by the Go spec, for simplicity, and for improved robustness in the presence of syntax errors. For instance, in method declarations, the receiver is treated like an ordinary parameter list and thus may contain multiple entries where the spec permits exactly one. Consequently, the corresponding field in the AST (ast.FuncDecl.Recv) field is not restricted to one entry. </p> <h2 id="pkg-index">Index </h2> <ul id="manual-nav"> +<li><a href="#ParseDir">func ParseDir(fset *token.FileSet, path string, filter func(fs.FileInfo) bool, mode Mode) (pkgs map[string]*ast.Package, first error)</a></li> +<li><a href="#ParseExpr">func ParseExpr(x string) (ast.Expr, error)</a></li> +<li><a href="#ParseExprFrom">func ParseExprFrom(fset *token.FileSet, filename string, src any, mode Mode) (expr ast.Expr, err error)</a></li> +<li><a href="#ParseFile">func ParseFile(fset *token.FileSet, filename string, src any, mode Mode) (f *ast.File, err error)</a></li> +<li><a href="#Mode">type Mode</a></li> +</ul> <div id="pkg-examples"> <h3>Examples</h3> <dl> <dd><a class="exampleLink" href="#example_ParseFile">ParseFile</a></dd> </dl> </div> <h3>Package files</h3> <p> <span>interface.go</span> <span>parser.go</span> <span>resolver.go</span> </p> <h2 id="ParseDir">func <span>ParseDir</span> </h2> <pre data-language="go">func ParseDir(fset *token.FileSet, path string, filter func(fs.FileInfo) bool, mode Mode) (pkgs map[string]*ast.Package, first error)</pre> <p>ParseDir calls <a href="#ParseFile">ParseFile</a> for all files with names ending in ".go" in the directory specified by path and returns a map of package name -> package AST with all the packages found. </p> +<p>If filter != nil, only the files with <span>fs.FileInfo</span> entries passing through the filter (and ending in ".go") are considered. The mode bits are passed to <a href="#ParseFile">ParseFile</a> unchanged. Position information is recorded in fset, which must not be nil. </p> +<p>If the directory couldn't be read, a nil map and the respective error are returned. If a parse error occurred, a non-nil but incomplete map and the first error encountered are returned. </p> +<h2 id="ParseExpr">func <span>ParseExpr</span> </h2> <pre data-language="go">func ParseExpr(x string) (ast.Expr, error)</pre> <p>ParseExpr is a convenience function for obtaining the AST of an expression x. The position information recorded in the AST is undefined. The filename used in error messages is the empty string. </p> +<p>If syntax errors were found, the result is a partial AST (with <span>ast.Bad</span>* nodes representing the fragments of erroneous source code). Multiple errors are returned via a scanner.ErrorList which is sorted by source position. </p> +<h2 id="ParseExprFrom">func <span>ParseExprFrom</span> <span title="Added in Go 1.5">1.5</span> </h2> <pre data-language="go">func ParseExprFrom(fset *token.FileSet, filename string, src any, mode Mode) (expr ast.Expr, err error)</pre> <p>ParseExprFrom is a convenience function for parsing an expression. The arguments have the same meaning as for <a href="#ParseFile">ParseFile</a>, but the source must be a valid Go (type or value) expression. Specifically, fset must not be nil. </p> +<p>If the source couldn't be read, the returned AST is nil and the error indicates the specific failure. If the source was read but syntax errors were found, the result is a partial AST (with <span>ast.Bad</span>* nodes representing the fragments of erroneous source code). Multiple errors are returned via a scanner.ErrorList which is sorted by source position. </p> +<h2 id="ParseFile">func <span>ParseFile</span> </h2> <pre data-language="go">func ParseFile(fset *token.FileSet, filename string, src any, mode Mode) (f *ast.File, err error)</pre> <p>ParseFile parses the source code of a single Go source file and returns the corresponding <span>ast.File</span> node. The source code may be provided via the filename of the source file, or via the src parameter. </p> +<p>If src != nil, ParseFile parses the source from src and the filename is only used when recording position information. The type of the argument for the src parameter must be string, []byte, or <span>io.Reader</span>. If src == nil, ParseFile parses the file specified by filename. </p> +<p>The mode parameter controls the amount of source text parsed and other optional parser functionality. If the <a href="#SkipObjectResolution">SkipObjectResolution</a> mode bit is set (recommended), the object resolution phase of parsing will be skipped, causing File.Scope, File.Unresolved, and all Ident.Obj fields to be nil. Those fields are deprecated; see <span>ast.Object</span> for details. </p> +<p>Position information is recorded in the file set fset, which must not be nil. </p> +<p>If the source couldn't be read, the returned AST is nil and the error indicates the specific failure. If the source was read but syntax errors were found, the result is a partial AST (with <span>ast.Bad</span>* nodes representing the fragments of erroneous source code). Multiple errors are returned via a scanner.ErrorList which is sorted by source position. </p> <h4 id="example_ParseFile"> <span class="text">Example</span> +</h4> <p>Code:</p> <pre class="code" data-language="go">fset := token.NewFileSet() // positions are relative to fset + +src := `package foo + +import ( + "fmt" + "time" +) + +func bar() { + fmt.Println(time.Now()) +}` + +// Parse src but stop after processing the imports. +f, err := parser.ParseFile(fset, "", src, parser.ImportsOnly) +if err != nil { + fmt.Println(err) + return +} + +// Print the imports from the file's AST. +for _, s := range f.Imports { + fmt.Println(s.Path.Value) +} + +</pre> <p>Output:</p> <pre class="output" data-language="go"> +"fmt" +"time" +</pre> <h2 id="Mode">type <span>Mode</span> </h2> <p>A Mode value is a set of flags (or 0). They control the amount of source code parsed and other optional parser functionality. </p> +<pre data-language="go">type Mode uint</pre> <pre data-language="go">const ( + PackageClauseOnly Mode = 1 << iota // stop parsing after package clause + ImportsOnly // stop parsing after import declarations + ParseComments // parse comments and add them to AST + Trace // print a trace of parsed productions + DeclarationErrors // report declaration errors + SpuriousErrors // same as AllErrors, for backward-compatibility + SkipObjectResolution // skip deprecated identifier resolution; see ParseFile + AllErrors = SpuriousErrors // report all errors (not just the first 10 on different lines) +)</pre><div class="_attribution"> + <p class="_attribution-p"> + © Google, Inc.<br>Licensed under the Creative Commons Attribution License 3.0.<br> + <a href="http://golang.org/pkg/go/parser/" class="_attribution-link">http://golang.org/pkg/go/parser/</a> + </p> +</div> |