close_issue_1
/
tools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

go/packages: fix the documentation 

It got out of sync after the round of API design changes, this brings it
back in line.
Also fix the behavior of passing nil as the config to match the
expected/documented behavior.

Change-Id: I8b51f5bd29ef9338ddb920fb872d857f180f9c84
Reviewed-on: https://go-review.googlesource.com/127255
Reviewed-by: Michael Matloob <matloob@golang.org>
This commit is contained in:
Ian Cottrell 2018-08-01 13:22:45 -04:00
parent 1801cb7c15
commit 681bc0c94c
2 changed files with 38 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

53
go/packages/doc.go
View File

@ -6,14 +6,13 @@
Package packages loads Go packages for inspection and analysis. Package packages loads Go packages for inspection and analysis.
NOTE: THIS PACKAGE IS NOT YET READY FOR WIDESPREAD USE: NOTE: THIS PACKAGE IS NOT YET READY FOR WIDESPREAD USE:
- The interface is still being reivsed and is likely to change. - The interface is still being revised and is likely to change.
- The implementation depends on the Go 1.11 go command. - The implementation depends on the Go 1.11 go command.
- We intend to finalize the API before Go 1.11 is released. - We intend to finalize the API before Go 1.11 is released.
The three loaders Metadata, TypeCheck, and WholeProgram provide differing The Load function takes as input a list of patterns and return a list of Package
amounts of detail about the loaded packages but otherwise behave the same. structs describing individual packages matched by those patterns.
All three take as input a list of patterns and return a list of Package structs The LoadMode controls the amounts of detail about the loaded packages.
describing individual packages matched by those patterns.
The patterns are used as arguments to the underlying build tool, The patterns are used as arguments to the underlying build tool,
such as the go command or Bazel, and are interpreted according to such as the go command or Bazel, and are interpreted according to
@ -22,19 +21,18 @@ that tool's conventions.
The Package struct provides basic information about the package, including The Package struct provides basic information about the package, including
- ID, a unique identifier for the package in the returned set; - ID, a unique identifier for the package in the returned set;
- PkgPath, the import path for the package when used in a build; - GoFiles, the names of the package's Go source files;
- Srcs, the names of the package's Go source files;
- Imports, a map from source import strings to the Packages they name; - Imports, a map from source import strings to the Packages they name;
- Type, the type information for the package's exported symbols; - Types, the type information for the package's exported symbols;
- Files, the parsed syntax trees for the package's source code; and - Syntax, the parsed syntax trees for the package's source code; and
- Info, the result of a complete type-check of the package syntax trees. - TypeInfo, the result of a complete type-check of the package syntax trees.
(See the documentation for type Package for the complete list of fields (See the documentation for type Package for the complete list of fields
and more detailed descriptions.) and more detailed descriptions.)
For example, For example,
Metadata(nil, "bytes", "unicode...") Load(nil, "bytes", "unicode...")
returns four Package structs describing the standard library packages returns four Package structs describing the standard library packages
bytes, unicode, unicode/utf16, and unicode/utf8. Note that one pattern bytes, unicode, unicode/utf16, and unicode/utf8. Note that one pattern
@ -42,23 +40,20 @@ can match multiple packages and that a package might be matched by
multiple patterns: in general it is not possible to determine which multiple patterns: in general it is not possible to determine which
packages correspond to which patterns. packages correspond to which patterns.
Note that the list returned by the loader (Metadata in this case) Note that the list returned by Load (LoadAllSyntax in this case)
only contains the packages matched by the patterns. Their dependencies only contains the packages matched by the patterns. Their dependencies
can be found by walking the import graph using the Imports fields. can be found by walking the import graph using the Imports fields.
As noted earlier, the three loaders provide increasing amounts of detail The Load function can be configured by passing a non-nil Config struct as
about the loaded packages. the first argument. If you pass nil for the Config Load will
run in LoadAllSyntax mode, collecting the maximal amount of information
it can.
See the documentation for type Config for details.
Metadata loads information about package location, source files, and imports. As noted earlier, the Config.Mode controls increasing amounts of detail
about the loaded packages, with each mode returning all the data of the
TypeCheck adds type information for all packages, including dependencies, previous mode with some extra added. See the documentation for type LoadMode
and type-checked syntax trees only for the packages matched by the patterns. for details.
WholeProgram adds type-checked syntax trees for all packages,
including dependencies.
The loaders can be configured by passing a non-nil Options struct as
the first argument. See the documentation for type Options for details.
Most tools should pass their command-line arguments (after any flags) Most tools should pass their command-line arguments (after any flags)
uninterpreted to the loader, so that the loader can interpret them uninterpreted to the loader, so that the loader can interpret them
@ -78,12 +73,12 @@ for each package listed on the command line:
func main() { func main() {
flag.Parse() flag.Parse()
pkgs, err := packages.Metadata(nil, flag.Args()...) pkgs, err := packages.Load(nil, flag.Args()...)
if err != nil { if err != nil {
log.Fatal(err) log.Fatal(err)
} }
for _, pkg := range pkgs { for _, pkg := range pkgs {
fmt.Print(pkg.ID, pkg.Srcs) fmt.Print(pkg.ID, pkg.GoFiles)
} }
} }
*/ */
@ -233,15 +228,11 @@ Questions & Tasks
Load? Load?
- Do we need a GeneratedBy map that maps the name of each generated Go - Do we need a GeneratedBy map that maps the name of each generated Go
source file in Srcs to that of the original file, if known, or "" otherwise? source file in GoFiles to that of the original file, if known, or "" otherwise?
Or are //line directives and "Generated" comments in those files enough? Or are //line directives and "Generated" comments in those files enough?
- Support bazel, blaze, and go1.10 list, not just go1.11 list. - Support bazel, blaze, and go1.10 list, not just go1.11 list.
- Support a "contains" query: a boolean option would cause the the
pattern words to be interpreted as filenames, and the query would
return the package(s) to which the file(s) belong.
- Handle (and test) various partial success cases, e.g. - Handle (and test) various partial success cases, e.g.
a mixture of good packages and: a mixture of good packages and:
invalid patterns invalid patterns

38
go/packages/packages.go
View File

@ -23,6 +23,10 @@ import (
) )
// A LoadMode specifies the amount of detail to return when loading packages. // A LoadMode specifies the amount of detail to return when loading packages.
// The modes are all strictly additive, as you go through the list it increases
// the amount of information available to you, but may also increase the cost
// of collecting the information.
// Load is always allowed to return more information than requested.
type LoadMode int type LoadMode int
const ( const (
@ -184,44 +188,32 @@ type Package struct {
Imports map[string]*Package Imports map[string]*Package
// GoFiles lists the absolute file paths of the package's Go source files. // GoFiles lists the absolute file paths of the package's Go source files.
//
// If a package has typed syntax trees and the DisableCgo option is false,
// the cgo-processed output files are listed instead of the original
// source files that contained import "C" statements.
// In this case, the file paths may not even end in ".go".
// Although the original sources are not listed in Srcs, the corresponding
// syntax tree positions will still refer back to the orignal source code,
// respecting the //line directives in the cgo-processed output.
//
// TODO(rsc): Actually, in TypeCheck mode even the packages without
// syntax trees (pure dependencies) lose their original sources.
// We should fix that.
GoFiles []string GoFiles []string
// OtherFiles lists the absolute file paths of the package's non-Go source files, // OtherFiles lists the absolute file paths of the package's non-Go source files,
// including assembly, C, C++, Fortran, Objective-C, SWIG, and so on. // including assembly, C, C++, Fortran, Objective-C, SWIG, and so on.
OtherFiles []string OtherFiles []string
// Type is the type information for the package. // Types is the type information for the package.
// The TypeCheck and WholeProgram loaders set this field for all packages. // Modes LoadTypes and above set this field for all packages.
Types *types.Package Types *types.Package
// IllTyped indicates whether the package has any type errors. // IllTyped indicates whether the package has any type errors.
// The TypeCheck and WholeProgram loaders set this field for all packages. // Modes LoadTypes and above set this field for all packages.
IllTyped bool IllTyped bool
// Files is the package's syntax trees, for the files listed in Srcs. // Syntax is the package's syntax trees, for the files listed in GoFiles.
// //
// The TypeCheck loader sets Files for packages matching the patterns. // Mode LoadSyntax set this field for packages matching the patterns.
// The WholeProgram loader sets Files for all packages, including dependencies. // Mode LoadSyntaxAll sets this field for all packages, including dependencies.
Syntax []*ast.File Syntax []*ast.File
// Info is the type-checking results for the package's syntax trees. // TypesInfo is the type-checking results for the package's syntax trees.
// It is set only when Files is set. // It is set only when Syntax is set.
TypesInfo *types.Info TypesInfo *types.Info
// Fset is the token.FileSet for the package's syntax trees listed in Files. // Fset is the token.FileSet for the package's syntax trees listed in Syntax.
// It is set only when Files is set. // It is set only when Syntax is set.
// All packages loaded together share a single Fset. // All packages loaded together share a single Fset.
Fset *token.FileSet Fset *token.FileSet
} }
@ -249,6 +241,8 @@ func newLoader(cfg *Config) *loader {
ld := &loader{} ld := &loader{}
if cfg != nil { if cfg != nil {
ld.Config = *cfg ld.Config = *cfg
} else {
ld.Config.Mode = LoadAllSyntax
} }
if ld.Context == nil { if ld.Context == nil {
ld.Context = context.Background() ld.Context = context.Background()