+++ /dev/null
-package analysis
-
-import (
- "flag"
- "fmt"
- "go/ast"
- "go/token"
- "go/types"
- "reflect"
-
- "golang.org/x/tools/internal/analysisinternal"
-)
-
-// An Analyzer describes an analysis function and its options.
-type Analyzer struct {
- // The Name of the analyzer must be a valid Go identifier
- // as it may appear in command-line flags, URLs, and so on.
- Name string
-
- // Doc is the documentation for the analyzer.
- // The part before the first "\n\n" is the title
- // (no capital or period, max ~60 letters).
- Doc string
-
- // Flags defines any flags accepted by the analyzer.
- // The manner in which these flags are exposed to the user
- // depends on the driver which runs the analyzer.
- Flags flag.FlagSet
-
- // Run applies the analyzer to a package.
- // It returns an error if the analyzer failed.
- //
- // On success, the Run function may return a result
- // computed by the Analyzer; its type must match ResultType.
- // The driver makes this result available as an input to
- // another Analyzer that depends directly on this one (see
- // Requires) when it analyzes the same package.
- //
- // To pass analysis results between packages (and thus
- // potentially between address spaces), use Facts, which are
- // serializable.
- Run func(*Pass) (interface{}, error)
-
- // RunDespiteErrors allows the driver to invoke
- // the Run method of this analyzer even on a
- // package that contains parse or type errors.
- RunDespiteErrors bool
-
- // Requires is a set of analyzers that must run successfully
- // before this one on a given package. This analyzer may inspect
- // the outputs produced by each analyzer in Requires.
- // The graph over analyzers implied by Requires edges must be acyclic.
- //
- // Requires establishes a "horizontal" dependency between
- // analysis passes (different analyzers, same package).
- Requires []*Analyzer
-
- // ResultType is the type of the optional result of the Run function.
- ResultType reflect.Type
-
- // FactTypes indicates that this analyzer imports and exports
- // Facts of the specified concrete types.
- // An analyzer that uses facts may assume that its import
- // dependencies have been similarly analyzed before it runs.
- // Facts must be pointers.
- //
- // FactTypes establishes a "vertical" dependency between
- // analysis passes (same analyzer, different packages).
- FactTypes []Fact
-}
-
-func (a *Analyzer) String() string { return a.Name }
-
-func init() {
- // Set the analysisinternal functions to be able to pass type errors
- // to the Pass type without modifying the go/analysis API.
- analysisinternal.SetTypeErrors = func(p interface{}, errors []types.Error) {
- p.(*Pass).typeErrors = errors
- }
- analysisinternal.GetTypeErrors = func(p interface{}) []types.Error {
- return p.(*Pass).typeErrors
- }
-}
-
-// A Pass provides information to the Run function that
-// applies a specific analyzer to a single Go package.
-//
-// It forms the interface between the analysis logic and the driver
-// program, and has both input and an output components.
-//
-// As in a compiler, one pass may depend on the result computed by another.
-//
-// The Run function should not call any of the Pass functions concurrently.
-type Pass struct {
- Analyzer *Analyzer // the identity of the current analyzer
-
- // syntax and type information
- Fset *token.FileSet // file position information
- Files []*ast.File // the abstract syntax tree of each file
- OtherFiles []string // names of non-Go files of this package
- IgnoredFiles []string // names of ignored source files in this package
- Pkg *types.Package // type information about the package
- TypesInfo *types.Info // type information about the syntax trees
- TypesSizes types.Sizes // function for computing sizes of types
-
- // Report reports a Diagnostic, a finding about a specific location
- // in the analyzed source code such as a potential mistake.
- // It may be called by the Run function.
- Report func(Diagnostic)
-
- // ResultOf provides the inputs to this analysis pass, which are
- // the corresponding results of its prerequisite analyzers.
- // The map keys are the elements of Analysis.Required,
- // and the type of each corresponding value is the required
- // analysis's ResultType.
- ResultOf map[*Analyzer]interface{}
-
- // -- facts --
-
- // ImportObjectFact retrieves a fact associated with obj.
- // Given a value ptr of type *T, where *T satisfies Fact,
- // ImportObjectFact copies the value to *ptr.
- //
- // ImportObjectFact panics if called after the pass is complete.
- // ImportObjectFact is not concurrency-safe.
- ImportObjectFact func(obj types.Object, fact Fact) bool
-
- // ImportPackageFact retrieves a fact associated with package pkg,
- // which must be this package or one of its dependencies.
- // See comments for ImportObjectFact.
- ImportPackageFact func(pkg *types.Package, fact Fact) bool
-
- // ExportObjectFact associates a fact of type *T with the obj,
- // replacing any previous fact of that type.
- //
- // ExportObjectFact panics if it is called after the pass is
- // complete, or if obj does not belong to the package being analyzed.
- // ExportObjectFact is not concurrency-safe.
- ExportObjectFact func(obj types.Object, fact Fact)
-
- // ExportPackageFact associates a fact with the current package.
- // See comments for ExportObjectFact.
- ExportPackageFact func(fact Fact)
-
- // AllPackageFacts returns a new slice containing all package facts of the analysis's FactTypes
- // in unspecified order.
- // WARNING: This is an experimental API and may change in the future.
- AllPackageFacts func() []PackageFact
-
- // AllObjectFacts returns a new slice containing all object facts of the analysis's FactTypes
- // in unspecified order.
- // WARNING: This is an experimental API and may change in the future.
- AllObjectFacts func() []ObjectFact
-
- // typeErrors contains types.Errors that are associated with the pkg.
- typeErrors []types.Error
-
- /* Further fields may be added in future. */
- // For example, suggested or applied refactorings.
-}
-
-// PackageFact is a package together with an associated fact.
-// WARNING: This is an experimental API and may change in the future.
-type PackageFact struct {
- Package *types.Package
- Fact Fact
-}
-
-// ObjectFact is an object together with an associated fact.
-// WARNING: This is an experimental API and may change in the future.
-type ObjectFact struct {
- Object types.Object
- Fact Fact
-}
-
-// Reportf is a helper function that reports a Diagnostic using the
-// specified position and formatted error message.
-func (pass *Pass) Reportf(pos token.Pos, format string, args ...interface{}) {
- msg := fmt.Sprintf(format, args...)
- pass.Report(Diagnostic{Pos: pos, Message: msg})
-}
-
-// The Range interface provides a range. It's equivalent to and satisfied by
-// ast.Node.
-type Range interface {
- Pos() token.Pos // position of first character belonging to the node
- End() token.Pos // position of first character immediately after the node
-}
-
-// ReportRangef is a helper function that reports a Diagnostic using the
-// range provided. ast.Node values can be passed in as the range because
-// they satisfy the Range interface.
-func (pass *Pass) ReportRangef(rng Range, format string, args ...interface{}) {
- msg := fmt.Sprintf(format, args...)
- pass.Report(Diagnostic{Pos: rng.Pos(), End: rng.End(), Message: msg})
-}
-
-func (pass *Pass) String() string {
- return fmt.Sprintf("%s@%s", pass.Analyzer.Name, pass.Pkg.Path())
-}
-
-// A Fact is an intermediate fact produced during analysis.
-//
-// Each fact is associated with a named declaration (a types.Object) or
-// with a package as a whole. A single object or package may have
-// multiple associated facts, but only one of any particular fact type.
-//
-// A Fact represents a predicate such as "never returns", but does not
-// represent the subject of the predicate such as "function F" or "package P".
-//
-// Facts may be produced in one analysis pass and consumed by another
-// analysis pass even if these are in different address spaces.
-// If package P imports Q, all facts about Q produced during
-// analysis of that package will be available during later analysis of P.
-// Facts are analogous to type export data in a build system:
-// just as export data enables separate compilation of several passes,
-// facts enable "separate analysis".
-//
-// Each pass (a, p) starts with the set of facts produced by the
-// same analyzer a applied to the packages directly imported by p.
-// The analysis may add facts to the set, and they may be exported in turn.
-// An analysis's Run function may retrieve facts by calling
-// Pass.Import{Object,Package}Fact and update them using
-// Pass.Export{Object,Package}Fact.
-//
-// A fact is logically private to its Analysis. To pass values
-// between different analyzers, use the results mechanism;
-// see Analyzer.Requires, Analyzer.ResultType, and Pass.ResultOf.
-//
-// A Fact type must be a pointer.
-// Facts are encoded and decoded using encoding/gob.
-// A Fact may implement the GobEncoder/GobDecoder interfaces
-// to customize its encoding. Fact encoding should not fail.
-//
-// A Fact should not be modified once exported.
-type Fact interface {
- AFact() // dummy method to avoid type errors
-}
projects / dotfiles / .git / blobdiff