package analysisinternal

import "golang.org/x/tools/internal/analysisinternal"

Package analysisinternal provides gopls' internal analyses with a number of helper functions that operate on typed syntax trees.

Index ¶

• func AddImport(info *types.Info, file *ast.File, preferredName, pkgpath, member string, pos token.Pos) (name, prefix string, newImport []analysis.TextEdit)
• func CheckReadable(pass *analysis.Pass, filename string) error
• func ExtractDoc(content, name string) (string, error)
• func Format(fset *token.FileSet, e ast.Expr) string
• func Imports(pkg *types.Package, path string) bool
• func IsFunctionNamed(obj types.Object, pkgPath string, names ...string) bool
• func IsMethodNamed(obj types.Object, pkgPath string, typeName string, names ...string) bool
• func IsPointerToNamed(t types.Type, pkgPath string, names ...string) bool
• func IsTypeNamed(t types.Type, pkgPath string, names ...string) bool
• func MatchingIdents(typs []types.Type, node ast.Node, pos token.Pos, info *types.Info, pkg *types.Package) map[types.Type][]string
• func MustExtractDoc(content, name string) string
• func TypeErrorEndPos(fset *token.FileSet, src []byte, start token.Pos) token.Pos
• func ValidateFixes(fset *token.FileSet, a *analysis.Analyzer, fixes []analysis.SuggestedFix) error
• func WalkASTWithParent(n ast.Node, f func(n ast.Node, parent ast.Node) bool)
• type ReadFileFunc
• func CheckedReadFile(pass *analysis.Pass, readFile ReadFileFunc) ReadFileFunc

Functions ¶

func AddImport ¶

func AddImport(info *types.Info, file *ast.File, preferredName, pkgpath, member string, pos token.Pos) (name, prefix string, newImport []analysis.TextEdit)

AddImport checks whether this file already imports pkgpath and that import is in scope at pos. If so, it returns the name under which it was imported and a zero edit. Otherwise, it adds a new import of pkgpath, using a name derived from the preferred name, and returns the chosen name, a prefix to be concatenated with member to form a qualified name, and the edit for the new import.

In the special case that pkgpath is dot-imported then member, the identifer for which the import is being added, is consulted. If member is not shadowed at pos, AddImport returns (".", "", nil). (AddImport accepts the caller's implicit claim that the imported package declares member.)

It does not mutate its arguments.

func CheckReadable ¶

func CheckReadable(pass *analysis.Pass, filename string) error

CheckReadable enforces the access policy defined by the ReadFile field of analysis.Pass.

func ExtractDoc ¶

func ExtractDoc(content, name string) (string, error)

ExtractDoc extracts a section of a package doc comment from the provided contents of an analyzer package's doc.go file.

A section is a portion of the comment between one heading and the next, using this form:

# Analyzer NAME

NAME: SUMMARY

Full description...

where NAME matches the name argument, and SUMMARY is a brief verb-phrase that describes the analyzer. The following lines, up until the next heading or the end of the comment, contain the full description. ExtractDoc returns the portion following the colon, which is the form expected by Analyzer.Doc.

Example:

# Analyzer printf

printf: checks consistency of calls to printf

The printf analyzer checks consistency of calls to printf.
Here is the complete description...

This notation allows a single doc comment to provide documentation for multiple analyzers, each in its own section. The HTML anchors generated for each heading are predictable.

It returns an error if the content was not a valid Go source file containing a package doc comment with a heading of the required form.

This machinery enables the package documentation (typically accessible via the web at https://pkg.go.dev/) and the command documentation (typically printed to a terminal) to be derived from the same source and formatted appropriately.

func Format ¶

func Format(fset *token.FileSet, e ast.Expr) string

Format returns a string representation of the expression e.

func Imports ¶

func Imports(pkg *types.Package, path string) bool

Imports returns true if path is imported by pkg.

func IsFunctionNamed ¶

func IsFunctionNamed(obj types.Object, pkgPath string, names ...string) bool

IsFunctionNamed reports whether obj is a package-level function defined in the given package and has one of the given names. It returns false if obj is nil.

This function avoids allocating the concatenation of "pkg.Name", which is important for the performance of syntax matching.

func IsMethodNamed ¶

func IsMethodNamed(obj types.Object, pkgPath string, typeName string, names ...string) bool

IsMethodNamed reports whether obj is a method defined on a package-level type with the given package and type name, and has one of the given names. It returns false if obj is nil.

This function avoids allocating the concatenation of "pkg.TypeName.Name", which is important for the performance of syntax matching.

func IsPointerToNamed ¶

func IsPointerToNamed(t types.Type, pkgPath string, names ...string) bool

IsPointerToNamed reports whether t is (or is an alias for) a pointer to a package-level defined type with the given package path and one of the given names. It returns false if t is not a pointer type.

func IsTypeNamed ¶

func IsTypeNamed(t types.Type, pkgPath string, names ...string) bool

IsTypeNamed reports whether t is (or is an alias for) a package-level defined type with the given package path and one of the given names. It returns false if t is nil.

This function avoids allocating the concatenation of "pkg.Name", which is important for the performance of syntax matching.

func MatchingIdents ¶

func MatchingIdents(typs []types.Type, node ast.Node, pos token.Pos, info *types.Info, pkg *types.Package) map[types.Type][]string

MatchingIdents finds the names of all identifiers in 'node' that match any of the given types. 'pos' represents the position at which the identifiers may be inserted. 'pos' must be within the scope of each of identifier we select. Otherwise, we will insert a variable at 'pos' that is unrecognized.

func MustExtractDoc ¶

func MustExtractDoc(content, name string) string

MustExtractDoc is like ExtractDoc but it panics on error.

To use, define a doc.go file such as:

// Package halting defines an analyzer of program termination.
//
// # Analyzer halting
//
// halting: reports whether execution will halt.
//
// The halting analyzer reports a diagnostic for functions
// that run forever. To suppress the diagnostics, try inserting
// a 'break' statement into each loop.
package halting

import _ "embed"

//go:embed doc.go
var doc string

And declare your analyzer as:

var Analyzer = &analysis.Analyzer{
	Name:             "halting",
	Doc:              analysisutil.MustExtractDoc(doc, "halting"),
	...
}

func TypeErrorEndPos ¶

func TypeErrorEndPos(fset *token.FileSet, src []byte, start token.Pos) token.Pos

func ValidateFixes ¶

func ValidateFixes(fset *token.FileSet, a *analysis.Analyzer, fixes []analysis.SuggestedFix) error

ValidateFixes validates the set of fixes for a single diagnostic. Any error indicates a bug in the originating analyzer.

It updates fixes so that fixes[*].End.IsValid().

It may be used as part of an analysis driver implementation.

func WalkASTWithParent ¶

func WalkASTWithParent(n ast.Node, f func(n ast.Node, parent ast.Node) bool)

WalkASTWithParent walks the AST rooted at n. The semantics are similar to ast.Inspect except it does not call f(nil).

Types ¶

type ReadFileFunc ¶

type ReadFileFunc = func(filename string) ([]byte, error)

A ReadFileFunc is a function that returns the contents of a file, such as os.ReadFile.

func CheckedReadFile ¶

func CheckedReadFile(pass *analysis.Pass, readFile ReadFileFunc) ReadFileFunc

CheckedReadFile returns a wrapper around a Pass.ReadFile function that performs the appropriate checks.

Source Files ¶

analysis.go extractdoc.go