golang

Documentation

Overview

Package golang produces Kythe compilation units for each Go import path specified. Compilations are extracted incrementally, so that partial results are available to the caller.

Usage:

var c golang.Extractor
if _, err := c.Locate("fmt"); err != nil {
  log.Fatalf(`Unable to locate package "fmt": %v`, err)
}
c.Extract()
for _, pkg := range c.Packages {
  if pkg.Err != nil {
    log.Printf("Error extracting %q: %v", pkg.Path, pkg.Err)
  } else {
    writeOutput(pkg)
  }
}

Index

• type Extractor
  • func (e *Extractor) Extract() error
  • func (e *Extractor) ImportDir(dir string) (*Package, error)
  • func (e *Extractor) Locate(importPath string) ([]*Package, error)
• type MissingError
  • func (m *MissingError) Error() string
• type Package
  • func (p *Package) EachUnit(ctx context.Context, ...) error
  • func (p *Package) Extract() error
• type PackageVNameOptions

Types

type Extractor

type Extractor struct {
	// The build configuration to use for extraction.
	BuildContext build.Context

	// The packages that have been extracted so far (initially empty).
	Packages []*Package

	// The configuration for constructing VNames for packages.
	PackageVNameOptions

	// An alternative installation path for compiled packages.  If this is set,
	// and a compiled package cannot be found in the normal location, the
	// extractor will try in this location.
	AltInstallPath string

	// Extra file paths to include in each compilation record.
	ExtraFiles []string

	// A function to convert a directory path to an import path.  If nil, the
	// path is made relative to the first matching element of the build
	// context's GOROOT or GOPATH or the current working directory.
	DirToImport func(path string) (string, error)
	// contains filtered or unexported fields
}

An Extractor contains the state needed to extract Go compilations from build information. The zero value is ready for use with default settings.

func (*Extractor) Extract

func (e *Extractor) Extract() error

Extract invokes the Extract method of each package in the Packages list, and updates its Err field with the result. If there were errors in extraction, one of them is returned.

func (*Extractor) ImportDir

func (e *Extractor) ImportDir(dir string) (*Package, error)

ImportDir attempts to import the Go package located in the given directory. An import path is inferred from the directory path.

func (*Extractor) Locate

func (e *Extractor) Locate(importPath string) ([]*Package, error)

Locate attempts to resolve and locate the specified import path in the build context. If a package has already been located, its existing *Package is returned. Otherwise, a new *Package value is returned and appended to the Packages field.

Note: multiple packages may be resolved for "/..." import paths

type MissingError

type MissingError struct {
	Path    string   // The import path of the incomplete package
	Missing []string // The import paths of the missing dependencies
}

MissingError is the concrete type of errors about missing dependencies.

func (*MissingError) Error

func (m *MissingError) Error() string

type Package

type Package struct {
	CorpusRoot   string                 // Corpus package root path
	Path         string                 // Import or directory path
	DepOnly      bool                   // Whether the package is only seen as a dependency
	Err          error                  // Error discovered during processing
	BuildPackage *build.Package         // Package info from the go/build library
	VName        *spb.VName             // The package's Kythe vname
	Units        []*apb.CompilationUnit // Compilations generated from Package
	// contains filtered or unexported fields
}

Package represents a single Go package extracted from local files.

func (*Package) EachUnit

func (p *Package) EachUnit(ctx context.Context, f func(cu *apb.CompilationUnit, fetcher analysis.Fetcher) error) error

EachUnit calls f with a compilation record for each unit in p. If f reports an error, that error is returned by EachUnit.

func (*Package) Extract

func (p *Package) Extract() error

Extract populates the Units field of p, and reports an error if any occurred.

After this method returns successfully, the require inputs for each of the Units are partially resolved, meaning we know their filesystem paths but not their contents. The filesystem paths are resolved to contents and digests by the Store method.

type PackageVNameOptions

type PackageVNameOptions = govname.PackageVNameOptions

PackageVNameOptions re-exports govname.PackageVNameOptions.