facts

Documentation

Overview

Package facts defines a serializable set of analysis.Fact.

It provides a partial implementation of the Fact-related parts of the analysis.Pass interface for use in analysis drivers such as "go vet" and other build systems.

The serial format is unspecified and may change, so the same version of this package must be used for reading and writing serialized facts.

The handling of facts in the analysis system parallels the handling of type information in the compiler: during compilation of package P, the compiler emits an export data file that describes the type of every object (named thing) defined in package P, plus every object indirectly reachable from one of those objects. Thus the downstream compiler of package Q need only load one export data file per direct import of Q, and it will learn everything about the API of package P and everything it needs to know about the API of P's dependencies.

Similarly, analysis of package P emits a fact set containing facts about all objects exported from P, plus additional facts about only those objects of P's dependencies that are reachable from the API of package P; the downstream analysis of Q need only load one fact set per direct import of Q.

The notion of "exportedness" that matters here is that of the compiler. According to the language spec, a method pkg.T.f is unexported simply because its name starts with lowercase. But the compiler must nonetheless export f so that downstream compilations can accurately ascertain whether pkg.T implements an interface pkg.I defined as interface{f()}. Exported thus means "described in export data".

Index

• type Decoder
  • func NewDecoder(pkg *types.Package) *Decoder
  • func NewDecoderFunc(pkg *types.Package, getPackage GetPackageFunc) *Decoder
  • func (d *Decoder) Decode(skipMethodSorting bool, read func(pkgPath string) ([]byte, error)) (*Set, error)
• type GetPackageFunc
• type Set
  • func (s *Set) AllObjectFacts(filter map[reflect.Type]bool) []analysis.ObjectFact
  • func (s *Set) AllPackageFacts(filter map[reflect.Type]bool) []analysis.PackageFact
  • func (s *Set) Encode(skipMethodSorting bool) []byte
  • func (s *Set) ExportObjectFact(obj types.Object, fact analysis.Fact)
  • func (s *Set) ExportPackageFact(fact analysis.Fact)
  • func (s *Set) ImportObjectFact(obj types.Object, ptr analysis.Fact) bool
  • func (s *Set) ImportPackageFact(pkg *types.Package, ptr analysis.Fact) bool
  • func (s *Set) String() string

Types

type Decoder

type Decoder struct {
	// contains filtered or unexported fields
}

A Decoder decodes the facts from the direct imports of the package provided to NewEncoder. A single decoder may be used to decode multiple fact sets (e.g. each for a different set of fact types) for the same package. Each call to Decode returns an independent fact set.

func NewDecoder

func NewDecoder(pkg *types.Package) *Decoder

NewDecoder returns a fact decoder for the specified package.

It uses a brute-force recursive approach to enumerate all objects defined by dependencies of pkg, so that it can learn the set of package paths that may be mentioned in the fact encoding. This does not scale well; use NewDecoderFunc where possible.

func NewDecoderFunc

func NewDecoderFunc(pkg *types.Package, getPackage GetPackageFunc) *Decoder

NewDecoderFunc returns a fact decoder for the specified package.

It calls the getPackage function for the package path string of each dependency (perhaps indirect) that it encounters in the encoding. If the function returns nil, the fact is discarded.

This function is preferred over NewDecoder when the client is capable of efficient look-up of packages by package path.

func (*Decoder) Decode

func (d *Decoder) Decode(skipMethodSorting bool, read func(pkgPath string) ([]byte, error)) (*Set, error)

Decode decodes all the facts relevant to the analysis of package pkgPath. The read function reads serialized fact data from an external source for one of pkg's direct imports, identified by package path. The empty file is a valid encoding of an empty fact set.

It is the caller's responsibility to call gob.Register on all necessary fact types.

Concurrent calls to Decode are safe, so long as the GetPackageFunc (if any) is also concurrency-safe.

TODO(golang/go#61443): eliminate skipMethodSorting one way or the other.

type GetPackageFunc

type GetPackageFunc = func(pkgPath string) *types.Package

A GetPackageFunc function returns the package denoted by a package path.

type Set

type Set struct {
	// contains filtered or unexported fields
}

A Set is a set of analysis.Facts.

Decode creates a Set of facts by reading from the imports of a given package, and Encode writes out the set. Between these operation, the Import and Export methods will query and update the set.

All of Set's methods except String are safe to call concurrently.

func (*Set) AllObjectFacts

func (s *Set) AllObjectFacts(filter map[reflect.Type]bool) []analysis.ObjectFact

func (*Set) AllPackageFacts

func (s *Set) AllPackageFacts(filter map[reflect.Type]bool) []analysis.PackageFact

func (*Set) Encode

func (s *Set) Encode(skipMethodSorting bool) []byte

Encode encodes a set of facts to a memory buffer.

It may fail if one of the Facts could not be gob-encoded, but this is a sign of a bug in an Analyzer.

func (*Set) ExportObjectFact

func (s *Set) ExportObjectFact(obj types.Object, fact analysis.Fact)

ExportObjectFact implements analysis.Pass.ExportObjectFact.

func (*Set) ExportPackageFact

func (s *Set) ExportPackageFact(fact analysis.Fact)

ExportPackageFact implements analysis.Pass.ExportPackageFact.

func (*Set) ImportObjectFact

func (s *Set) ImportObjectFact(obj types.Object, ptr analysis.Fact) bool

ImportObjectFact implements analysis.Pass.ImportObjectFact.

func (*Set) ImportPackageFact

func (s *Set) ImportPackageFact(pkg *types.Package, ptr analysis.Fact) bool

ImportPackageFact implements analysis.Pass.ImportPackageFact.

func (*Set) String

func (s *Set) String() string

String is provided only for debugging, and must not be called concurrent with any Import/Export method.