indexer

Documentation

Overview

Package indexer implements a Kythe indexer for the Go language.

Usage example: Indexing a Kythe CompilationUnit message.

// Obtain a compilation from some source, e.g., an index pack.
var pack *indexpack.Archive = ...
var unit *apb.CompilationUnit = ...

// Parse the sources and resolve types.
pi, err := indexer.Resolve(unit, pack, &indexer.ResolveOptions{
  Info: indexer.AllTypeInfo(),
})
if err != nil {
  log.Fatal("Resolving failed: %v", err)
}
// Type information from http://godoc.org/go/types is now available
// from pi.Info, which is a *types.Info record.

Index

• func AllTypeInfo() *types.Info
• func XRefTypeInfo() *types.Info
• type EmitOptions
• type Fetcher
• type PackageInfo
  • func Resolve(unit *apb.CompilationUnit, f Fetcher, opts *ResolveOptions) (*PackageInfo, error)
  • func (pi *PackageInfo) AnchorVName(file *ast.File, start, end int) *spb.VName
  • func (pi *PackageInfo) Emit(ctx context.Context, sink Sink, opts *EmitOptions) error
  • func (pi *PackageInfo) FileVName(file *ast.File) *spb.VName
  • func (pi *PackageInfo) MarkedSource(obj types.Object) *cpb.MarkedSource
  • func (pi *PackageInfo) ObjectVName(obj types.Object) *spb.VName
  • func (pi *PackageInfo) Signature(obj types.Object) string
  • func (pi *PackageInfo) Span(node ast.Node) (file *ast.File, start, end int)
  • func (pi *PackageInfo) String() string
• type ResolveOptions
• type Ruleset
• type Sink

Functions

func AllTypeInfo

func AllTypeInfo() *types.Info

AllTypeInfo creates a new types.Info value with empty maps for each of the fields that can be filled in by the type-checker.

func XRefTypeInfo

func XRefTypeInfo() *types.Info

XRefTypeInfo creates a new types.Info value with empty maps for each of the fields needed for cross-reference indexing.

Types

type EmitOptions

type EmitOptions struct {
	// If true, emit nodes for standard library packages when they are first
	// encountered. This is helpful if you want to index a package in isolation
	// where data for the standard library are not available.
	EmitStandardLibs bool

	// If true, emit code facts containing MarkedSource messages.
	EmitMarkedSource bool

	// If true, emit linkages specified by metadata rules.
	EmitLinkages bool

	// If set, use this as the base URL for links to godoc.  The import path is
	// appended to the path of this URL to obtain the target URL to link to.
	DocBase *url.URL
}

EmitOptions control the behaviour of the Emit function. A nil options pointer provides default values.

type Fetcher

type Fetcher interface {
	Fetch(path, digest string) ([]byte, error)
}

A Fetcher retrieves the contents of a file given its path and/or hex-encoded SHA256 digest, at least one of which must be set.

type PackageInfo

type PackageInfo struct {
	Name         string                        // The (short) name of the package
	ImportPath   string                        // The nominal import path of the package
	Package      *types.Package                // The package for this compilation
	Dependencies map[string]*types.Package     // Packages imported from dependencies
	VName        *spb.VName                    // The base vname for this package
	PackageVName map[*types.Package]*spb.VName // Resolved package to vname
	FileSet      *token.FileSet                // Location info for the source files
	Files        []*ast.File                   // The parsed ASTs of the source files
	SourceText   map[*ast.File]string          // The text of the source files
	Rules        map[*ast.File]metadata.Rules  // Mapping metadata for each source file
	Vendored     map[string]string             // Mapping from package to its vendor path

	Info   *types.Info // If non-nil, contains type-checker results
	Errors []error     // All errors reported by the type checker
	// contains filtered or unexported fields
}

PackageInfo records information about the Go packages defined by a compilation unit and its dependencies.

func Resolve

func Resolve(unit *apb.CompilationUnit, f Fetcher, opts *ResolveOptions) (*PackageInfo, error)

Resolve resolves the package information for unit and its dependencies. On success the package corresponding to unit is located via ImportPath in the Packages map of the returned value.

func (*PackageInfo) AnchorVName

func (pi *PackageInfo) AnchorVName(file *ast.File, start, end int) *spb.VName

AnchorVName returns a VName for the given file and offsets.

func (*PackageInfo) Emit

func (pi *PackageInfo) Emit(ctx context.Context, sink Sink, opts *EmitOptions) error

Emit generates Kythe facts and edges to represent pi, and writes them to sink. In case of errors, processing continues as far as possible before the first error encountered is reported.

func (*PackageInfo) FileVName

func (pi *PackageInfo) FileVName(file *ast.File) *spb.VName

FileVName returns a VName for path relative to the package base.

func (*PackageInfo) MarkedSource

func (pi *PackageInfo) MarkedSource(obj types.Object) *cpb.MarkedSource

MarkedSource returns a MarkedSource message describing obj. See: http://www.kythe.io/docs/schema/marked-source.html.

func (*PackageInfo) ObjectVName

func (pi *PackageInfo) ObjectVName(obj types.Object) *spb.VName

ObjectVName returns a VName for obj relative to that of its package.

func (*PackageInfo) Signature

func (pi *PackageInfo) Signature(obj types.Object) string

Signature returns a signature for obj, suitable for use in a vname.

func (*PackageInfo) Span

func (pi *PackageInfo) Span(node ast.Node) (file *ast.File, start, end int)

Span returns the containing file and 0-based offset range of the given AST node. The range is half-open, including the start position but excluding the end.

If node == nil or lacks a valid start position, Span returns nil -1, -1. If the end position of node is invalid, start == end.

func (*PackageInfo) String

func (pi *PackageInfo) String() string

String renders a human-readable synopsis of the package information.

type ResolveOptions

type ResolveOptions struct {
	// Passes a value whose non-nil map fields will be filled in by the type
	// checker during resolution. The value will also be copied to the Info
	// field of the PackageInfo returned by Resolve.
	Info *types.Info

	// If set, this function is called for each required input to check whether
	// it contains metadata rules.
	//
	// Valid return are:
	//    rs, nil    -- a valid ruleset
	//    nil, nil   -- no ruleset found
	//    _, err     -- an error attempting to load a ruleset
	//
	CheckRules func(ri *apb.CompilationUnit_FileInput, f Fetcher) (*Ruleset, error)
}

ResolveOptions control the behaviour of the Resolve function. A nil options pointer provides default values.

type Ruleset

type Ruleset struct {
	Path  string         // the file path this rule set applies to
	Rules metadata.Rules // the rules that apply to the path
}

A Ruleset represents a collection of mapping rules applicable to a source file in a compilation to be indexed.

type Sink

type Sink func(context.Context, *spb.Entry) error

A Sink is a callback invoked by the indexer to deliver entries.