importer

Documentation

Overview

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

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 src/pkg/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. Ad-hoc packages and external test packages are non-importable. The importer and its clients must be careful not to assume that the import path of a package may be used for a name-based lookup. For example, a pointer analysis scope may consist of 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.) An external test package may depend upon members of the augmented package that are not in the unaugmented package, such as functions that expose internals. (See bufio/export_test.go for an example.) So, the importer must ensure that for each external test package it loads, it also augments the corresponding non-test package.

The import graph over n unaugmented packages must be acyclic; the import graph over n-1 unaugmented packages plus one augmented package must also be acyclic. ('go test' relies on this.) But the import graph over n augmented packages may contain cycles, and currently, go/types is incapable of handling such inputs, so the Importer will only augment (and create an external test package for) the first import path specified on the command-line.

Index

• Constants
• func ParseFiles(fset *token.FileSet, dir string, files ...string) ([]*ast.File, error)
• type Config
• type Importer
  • func New(config *Config) *Importer
  • func (imp *Importer) AllPackages() []*PackageInfo
  • func (imp *Importer) CreatePackage(path string, files ...*ast.File) *PackageInfo
  • func (imp *Importer) LoadInitialPackages(args []string) ([]*PackageInfo, []string, error)
  • func (imp *Importer) LoadPackage(path string) (*PackageInfo, error)
  • func (imp *Importer) PathEnclosingInterval(start, end token.Pos) (pkg *PackageInfo, path []ast.Node, exact bool)
• type PackageInfo
  • func (info *PackageInfo) ImportSpecPkg(spec *ast.ImportSpec) *types.PkgName
  • func (info *PackageInfo) IsType(e ast.Expr) bool
  • func (info *PackageInfo) ObjectOf(id *ast.Ident) types.Object
  • func (info *PackageInfo) String() string
  • func (info *PackageInfo) TypeCaseVar(cc *ast.CaseClause) *types.Var
  • func (info *PackageInfo) TypeOf(e ast.Expr) types.Type
  • func (info *PackageInfo) ValueOf(e ast.Expr) exact.Value

Constants

const InitialPackagesUsage = `` /* 1301-byte string literal not displayed */

InitialPackagesUsage is a partial usage message that client applications may wish to include in their -help output.

Functions

func ParseFiles

func ParseFiles(fset *token.FileSet, dir string, files ...string) ([]*ast.File, error)

ParseFiles parses the Go source files files within directory dir and returns their ASTs, or the first parse error if any.

Types

type Config

type Config struct {
	// TypeChecker contains options relating to the type checker.
	//
	// The supplied IgnoreFuncBodies is not used; the effective
	// value comes from the TypeCheckFuncBodies func below.
	//
	// All callbacks must be thread-safe.
	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.
	//
	// Must be thread-safe.
	//
	TypeCheckFuncBodies func(string) bool

	// If Build is non-nil, it is used to satisfy imports.
	//
	// If it is nil, binary object files produced by the gc
	// compiler will be loaded instead of source code for all
	// imported packages.  Such files supply only the types of
	// package-level declarations and values of constants, but no
	// code, so this mode will not yield a whole program.  It is
	// intended for analyses that perform intraprocedural analysis
	// of a single package.
	Build *build.Context
}

Config specifies the configuration for the importer.

type Importer

type Importer struct {
	Fset *token.FileSet // position info for all files seen
	// contains filtered or unexported fields
}

An Importer's exported methods are not thread-safe.

func New

func New(config *Config) *Importer

New returns a new, empty Importer using configuration options specified by config.

func (*Importer) AllPackages

func (imp *Importer) AllPackages() []*PackageInfo

AllPackages returns a new slice containing all packages loaded by importer imp.

func (*Importer) CreatePackage

func (imp *Importer) CreatePackage(path string, files ...*ast.File) *PackageInfo

CreatePackage creates and type-checks a package from the specified list of parsed files, importing their dependencies. It returns a PackageInfo containing the resulting types.Package, the ASTs, and other type information.

The order of files determines the package initialization order.

path is the full name under which this package is known, such as appears in an import declaration. e.g. "sync/atomic". It need not be unique; for example, it is possible to construct two distinct packages both named "main".

The resulting package is accessible via AllPackages() but is not importable, i.e. no 'import' spec can resolve to it.

CreatePackage never fails, but the resulting package may contain type errors; the first of these is recorded in PackageInfo.Err.

func (*Importer) LoadInitialPackages

func (imp *Importer) LoadInitialPackages(args []string) ([]*PackageInfo, []string, error)

LoadInitialPackages interprets args as a set of packages, loads those packages and their dependencies, and returns them.

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

The second result parameter returns the list of unconsumed arguments.

It is an error to specify no packages.

Precondition: LoadInitialPackages cannot be called after any previous calls to Load* on the same importer.

func (*Importer) LoadPackage

func (imp *Importer) LoadPackage(path string) (*PackageInfo, error)

LoadPackage loads and type-checks the package whose import path is path, plus its necessary dependencies.

func (*Importer) PathEnclosingInterval

func (imp *Importer) 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 the Importer imp. exact is defined as for astutil.PathEnclosingInterval.

The result is (nil, nil, false) if not found.

type PackageInfo

type PackageInfo struct {
	Pkg        *types.Package
	Importable bool        // true if 'import "Pkg.Path()"' would resolve to this
	Err        error       // non-nil if the package had static errors
	Files      []*ast.File // abstract syntax for the package's files
	types.Info             // type-checker deductions.
}

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

Not mutated once constructed.

func (*PackageInfo) ImportSpecPkg

func (info *PackageInfo) ImportSpecPkg(spec *ast.ImportSpec) *types.PkgName

ImportSpecPkg returns the PkgName for a given ImportSpec, possibly an implicit one for a dot-import or an import-without-rename. It returns nil if not found.

func (*PackageInfo) IsType

func (info *PackageInfo) IsType(e ast.Expr) bool

IsType returns true iff expression e denotes a type. Precondition: e belongs to the package's ASTs.

TODO(gri): move this into go/types.

func (*PackageInfo) ObjectOf

func (info *PackageInfo) ObjectOf(id *ast.Ident) types.Object

ObjectOf returns the typechecker object denoted by the specified id. Precondition: id belongs to the package's ASTs.

func (*PackageInfo) String

func (info *PackageInfo) String() string

func (*PackageInfo) TypeCaseVar

func (info *PackageInfo) TypeCaseVar(cc *ast.CaseClause) *types.Var

TypeCaseVar returns the implicit variable created by a single-type case clause in a type switch, or nil if not found.

func (*PackageInfo) TypeOf

func (info *PackageInfo) TypeOf(e ast.Expr) types.Type

TypeOf returns the type of expression e. Precondition: e belongs to the package's ASTs.

func (*PackageInfo) ValueOf

func (info *PackageInfo) ValueOf(e ast.Expr) exact.Value

ValueOf returns the value of expression e if it is a constant, nil otherwise. Precondition: e belongs to the package's ASTs.