loader

Documentation

Overview

Package loader loads, parses and type-checks packages of Go code plus their transitive closure, and retains both the ASTs and the derived facts.

THIS INTERFACE IS EXPERIMENTAL AND IS LIKELY TO CHANGE.

The package defines two primary types: Config, which specifies a set of initial packages to load and various other options; and Program, which is the result of successfully loading the packages specified by a configuration.

The configuration can be set directly, but *Config provides various convenience methods to simplify the common cases, each of which can be called any number of times. Finally, these are followed by a call to Load() to actually load and type-check the program.

var conf loader.Config

// Use the command-line arguments to specify
// a set of initial packages to load from source.
// See FromArgsUsage for help.
rest, err := conf.FromArgs(os.Args[1:], wantTests)

// Parse the specified files and create an ad-hoc package with path "foo".
// All files must have the same 'package' declaration.
conf.CreateFromFilenames("foo", "foo.go", "bar.go")

// Create an ad-hoc package with path "foo" from
// the specified already-parsed files.
// All ASTs must have the same 'package' declaration.
conf.CreateFromFiles("foo", parsedFiles)

// Add "runtime" to the set of packages to be loaded.
conf.Import("runtime")

// Adds "fmt" and "fmt_test" to the set of packages
// to be loaded.  "fmt" will include *_test.go files.
conf.ImportWithTests("fmt")

// Finally, load all the packages specified by the configuration.
prog, err := conf.Load()

CONCEPTS AND TERMINOLOGY

An AD-HOC package is one specified as a set of source files on the command line. In the simplest case, it may consist of a single file such as $GOROOT/src/net/http/triv.go.

EXTERNAL TEST packages are those comprised of a set of *_test.go files all with the same 'package foo_test' declaration, all in the same directory. (go/build.Package calls these files XTestFiles.)

An IMPORTABLE package is one that can be referred to by some import spec. The Path() of each importable package is unique within a Program.

Ad-hoc packages and external test packages are NON-IMPORTABLE. The Path() of an ad-hoc package is inferred from the package declarations of its files and is therefore not a unique package key. For example, Config.CreatePkgs may specify two initial ad-hoc packages both called "main".

An AUGMENTED package is an importable package P plus all the *_test.go files with same 'package foo' declaration as P. (go/build.Package calls these files TestFiles.)

The INITIAL packages are those specified in the configuration. A DEPENDENCY is a package loaded to satisfy an import in an initial package or another dependency.

Index

• Constants
• type Config
  • func (conf *Config) CreateFromFilenames(path string, filenames ...string)
  • func (conf *Config) CreateFromFiles(path string, files ...*ast.File)
  • func (conf *Config) FromArgs(args []string, xtest bool) ([]string, error)
  • func (conf *Config) Import(path string)
  • func (conf *Config) ImportWithTests(path string)
  • func (conf *Config) Load() (*Program, error)
  • func (conf *Config) ParseFile(filename string, src interface{}) (*ast.File, error)
• type PackageInfo
  • func (info *PackageInfo) String() string
• type PkgSpec
• type Program
  • func (prog *Program) InitialPackages() []*PackageInfo
  • func (prog *Program) PathEnclosingInterval(start, end token.Pos) (pkg *PackageInfo, path []ast.Node, exact bool)

Constants

const FromArgsUsage = `` /* 1067-byte string literal not displayed */

FromArgsUsage is a partial usage message that applications calling FromArgs may wish to include in their -help output.

Types

type Config

type Config struct {
	// Fset is the file set for the parser to use when loading the
	// program.  If nil, it may be lazily initialized by any
	// method of Config.
	Fset *token.FileSet

	// ParserMode specifies the mode to be used by the parser when
	// loading source packages.
	ParserMode parser.Mode

	// TypeChecker contains options relating to the type checker.
	//
	// The supplied IgnoreFuncBodies is not used; the effective
	// value comes from the TypeCheckFuncBodies func below.
	//
	// TypeChecker.Packages is lazily initialized during Load.
	TypeChecker types.Config

	// TypeCheckFuncBodies is a predicate over package import
	// paths.  A package for which the predicate is false will
	// have its package-level declarations type checked, but not
	// its function bodies; this can be used to quickly load
	// dependencies from source.  If nil, all func bodies are type
	// checked.
	TypeCheckFuncBodies func(string) bool

	// ImportFromBinary determines whether to satisfy dependencies by
	// loading gc export data instead of Go source code.
	//
	// If false, the entire program---the initial packages and their
	// transitive closure of dependencies---will be loaded from
	// source, parsed, and type-checked.  This is required for
	// whole-program analyses such as pointer analysis.
	//
	// If true, the go/gcimporter mechanism is used instead to read
	// the binary export-data files written by the gc toolchain.
	// They supply only the types of package-level declarations and
	// values of constants, but no code, this option will not yield
	// a whole program.  It is intended for analyses that perform
	// modular analysis of a single package, e.g. traditional
	// compilation.
	//
	// No check is made that the export data files are up-to-date.
	//
	// The initial packages (CreatePkgs and ImportPkgs) are always
	// loaded from Go source, regardless of this flag's setting.
	//
	// NB: there is a bug when loading multiple initial packages with
	// this flag enabled: https://github.com/golang/go/issues/9955.
	ImportFromBinary bool

	// If Build is non-nil, it is used to locate source packages.
	// Otherwise &build.Default is used.
	//
	// By default, cgo is invoked to preprocess Go files that
	// import the fake package "C".  This behaviour can be
	// disabled by setting CGO_ENABLED=0 in the environment prior
	// to startup, or by setting Build.CgoEnabled=false.
	Build *build.Context

	// If DisplayPath is non-nil, it is used to transform each
	// file name obtained from Build.Import().  This can be used
	// to prevent a virtualized build.Config's file names from
	// leaking into the user interface.
	DisplayPath func(path string) string

	// If AllowErrors is true, Load will return a Program even
	// if some of the its packages contained I/O, parser or type
	// errors; such errors are accessible via PackageInfo.Errors.  If
	// false, Load will fail if any package had an error.
	AllowErrors bool

	// CreatePkgs specifies a list of non-importable initial
	// packages to create.  The resulting packages will appear in
	// the corresponding elements of the Program.Created slice.
	CreatePkgs []PkgSpec

	// ImportPkgs specifies a set of initial packages to load from
	// source.  The map keys are package import paths, used to
	// locate the package relative to $GOROOT.
	//
	// The map value indicates whether to load tests.  If true, Load
	// will add and type-check two lists of files to the package:
	// non-test files followed by in-package *_test.go files.  In
	// addition, it will append the external test package (if any)
	// to Program.Created.
	ImportPkgs map[string]bool

	// FindPackage is called during Load to create the build.Package
	// for a given import path.  If nil, a default implementation
	// based on ctxt.Import is used.  A client may use this hook to
	// adapt to a proprietary build system that does not follow the
	// "go build" layout conventions, for example.
	//
	// It must be safe to call concurrently from multiple goroutines.
	FindPackage func(ctxt *build.Context, importPath string) (*build.Package, error)

	// PackageCreated is a hook called when a types.Package
	// is created but before it has been populated.
	//
	// The package's import Path() and Scope() are defined,
	// but not its Name() since no package declaration has
	// been seen yet.
	//
	// Clients may use this to insert synthetic items into
	// the package scope, for example.
	//
	// It must be safe to call concurrently from multiple goroutines.
	PackageCreated func(*types.Package)
}

Config specifies the configuration for a program to load. The zero value for Config is a ready-to-use default configuration.

func (*Config) CreateFromFilenames

func (conf *Config) CreateFromFilenames(path string, filenames ...string)

CreateFromFilenames is a convenience function that adds a conf.CreatePkgs entry to create a package of the specified *.go files.

func (*Config) CreateFromFiles

func (conf *Config) CreateFromFiles(path string, files ...*ast.File)

CreateFromFiles is a convenience function that adds a conf.CreatePkgs entry to create package of the specified path and parsed files.

func (*Config) FromArgs

func (conf *Config) FromArgs(args []string, xtest bool) ([]string, error)

FromArgs interprets args as a set of initial packages to load from source and updates the configuration. It returns the list of unconsumed arguments.

It is intended for use in command-line interfaces that require a set of initial packages to be specified; see FromArgsUsage message for details.

Only superficial errors are reported at this stage; errors dependent on I/O are detected during Load.

func (*Config) Import

func (conf *Config) Import(path string)

Import is a convenience function that adds path to ImportPkgs, the set of initial packages that will be imported from source.

func (*Config) ImportWithTests

func (conf *Config) ImportWithTests(path string)

ImportWithTests is a convenience function that adds path to ImportPkgs, the set of initial source packages located relative to $GOPATH. The package will be augmented by any *_test.go files in its directory that contain a "package x" (not "package x_test") declaration.

In addition, if any *_test.go files contain a "package x_test" declaration, an additional package comprising just those files will be added to CreatePkgs.

func (*Config) Load

func (conf *Config) Load() (*Program, error)

Load creates the initial packages specified by conf.{Create,Import}Pkgs, loading their dependencies packages as needed.

On success, Load returns a Program containing a PackageInfo for each package. On failure, it returns an error.

If AllowErrors is true, Load will return a Program even if some packages contained I/O, parser or type errors, or if dependencies were missing. (Such errors are accessible via PackageInfo.Errors. If false, Load will fail if any package had an error.

It is an error if no packages were loaded.

func (*Config) ParseFile

func (conf *Config) ParseFile(filename string, src interface{}) (*ast.File, error)

ParseFile is a convenience function (intended for testing) that invokes the parser using the Config's FileSet, which is initialized if nil.

src specifies the parser input as a string, []byte, or io.Reader, and filename is its apparent name. If src is nil, the contents of filename are read from the file system.

type PackageInfo

type PackageInfo struct {
	Pkg                   *types.Package
	Importable            bool        // true if 'import "Pkg.Path()"' would resolve to this
	TransitivelyErrorFree bool        // true if Pkg and all its dependencies are free of errors
	Files                 []*ast.File // syntax trees for the package's files
	Errors                []error     // non-nil if the package had errors
	types.Info                        // type-checker deductions.
	// contains filtered or unexported fields
}

PackageInfo holds the ASTs and facts derived by the type-checker for a single package.

Not mutated once exposed via the API.

func (*PackageInfo) String

func (info *PackageInfo) String() string

type PkgSpec

type PkgSpec struct {
	Path      string      // import path ("" => use package declaration)
	Files     []*ast.File // ASTs of already-parsed files
	Filenames []string    // names of files to be parsed
}

A PkgSpec specifies a non-importable package to be created by Load. Files are processed first, but typically only one of Files and Filenames is provided. The path needn't be globally unique.

type Program

type Program struct {
	Fset *token.FileSet // the file set for this program

	// Created[i] contains the initial package whose ASTs or
	// filenames were supplied by Config.CreatePkgs[i], followed by
	// the external test package, if any, of each package in
	// Config.ImportPkgs ordered by ImportPath.
	Created []*PackageInfo

	// Imported contains the initially imported packages,
	// as specified by Config.ImportPkgs.
	Imported map[string]*PackageInfo

	// ImportMap is the canonical mapping of import paths to
	// packages used by the type-checker (Config.TypeChecker.Packages).
	// It contains all Imported initial packages, but not Created
	// ones, and all imported dependencies.
	ImportMap map[string]*types.Package

	// AllPackages contains the PackageInfo of every package
	// encountered by Load: all initial packages and all
	// dependencies, including incomplete ones.
	AllPackages map[*types.Package]*PackageInfo
}

A Program is a Go program loaded from source or binary as specified by a Config.

func (*Program) InitialPackages

func (prog *Program) InitialPackages() []*PackageInfo

InitialPackages returns a new slice containing the set of initial packages (Created + Imported) in unspecified order.

func (*Program) PathEnclosingInterval

func (prog *Program) PathEnclosingInterval(start, end token.Pos) (pkg *PackageInfo, path []ast.Node, exact bool)

PathEnclosingInterval returns the PackageInfo and ast.Node that contain source interval [start, end), and all the node's ancestors up to the AST root. It searches all ast.Files of all packages in prog. exact is defined as for astutil.PathEnclosingInterval.

The zero value is returned if not found.