kcd

Documentation

Overview

Package kcd defines an interface and utility functions for the implementation of a Kythe compilation database.

Design documentation: kythe/docs/kythe-compilation-database.txt

Index

• func HexDigest(data []byte) string
• func IsCorpusValid(c string) bool
• func IsRevisionValid(r string) bool
• func IsValidDigest(s string) bool
• type CompiledFilter
• type Deleter
• type FindFilter
  • func (ff *FindFilter) Compile() (*CompiledFilter, error)
  • func (ff *FindFilter) IsEmpty() bool
• type Index
• type ReadWriteDeleter
• type ReadWriter
• type Reader
• type Revision
  • func (r Revision) IsValid() error
  • func (r Revision) String() string
• type RevisionsFilter
  • func (rf *RevisionsFilter) Compile() (func(Revision) bool, error)
• type Unit
• type Writer

Functions

func HexDigest

func HexDigest(data []byte) string

HexDigest computes a hex-encoded SHA256 digest of data.

func IsCorpusValid

func IsCorpusValid(c string) bool

IsCorpusValid reports whether c is a valid corpus marker. A corpus is valid if it is nonempty and does not contain whitespace.

func IsRevisionValid

func IsRevisionValid(r string) bool

IsRevisionValid reports whether r is a valid revision marker. A marker is valid if it is nonempty and does not contain whitespace.

func IsValidDigest

func IsValidDigest(s string) bool

IsValidDigest reports whether s is valid as a digest computed by the HexDigest function. It does not check whether s could have actually been generated by the hash function, only the structure of the value.

Types

type CompiledFilter

type CompiledFilter struct {
	RevisionMatches    func(...string) bool
	BuildCorpusMatches func(...string) bool
	UnitCorpusMatches  func(...string) bool
	LanguageMatches    func(...string) bool
	TargetMatches      func(...string) bool
	OutputMatches      func(...string) bool
	SourcesMatch       func(...string) bool
}

A CompiledFilter is a collection of matchers compiled from a FindFilter.

type Deleter

type Deleter interface {
	// DeleteUnit removes the specified unit from the database.
	DeleteUnit(_ context.Context, unitDigest string) error

	// DeleteFile removes the specified file from the database.
	DeleteFile(_ context.Context, fileDigest string) error

	// DeleteRevision removes the specified revision marker from the database.
	// It is an error if rev == "" or corpus == "".  All timestamps for the
	// matching revision are discarded.
	DeleteRevision(_ context.Context, revision, corpus string) error
}

Deleter expresses the capacity to delete data from a compilation database. Each of the methods of this interface should return an error that satisfies os.IsNotExist if its argument does not match any known entries. Not all writable databases must support this interface.

type FindFilter

type FindFilter struct {
	UnitCorpus  []string // Include only these unit corpus labels (exact match)
	Revisions   []string // Include only these revisions (exact match).
	Languages   []string // Include only these languages (Kythe language names).
	BuildCorpus []string // Include only these build corpus labels (exact match).

	Targets []*regexp.Regexp // Include only compilations for these targets.
	Sources []*regexp.Regexp // Include only compilations for these sources.
	Outputs []*regexp.Regexp // include only compilations for these outputs.
}

FindFilter gives constraints on which compilations are matched by a call to the Find method of compdb.Reader.

func (*FindFilter) Compile

func (ff *FindFilter) Compile() (*CompiledFilter, error)

Compile returns a compiled filter that matches index terms based on ff. Returns nil if ff is an empty filter.

func (*FindFilter) IsEmpty

func (ff *FindFilter) IsEmpty() bool

IsEmpty reports whether f is an empty filter, meaning it specifies no non-empty query terms.

type Index

type Index struct {
	Corpus   string   // The Kythe corpus name, e.g., "kythe"
	Language string   // The Kythe language name, e.g., "c++".
	Output   string   // The output name, e.g., "bazel-out/foo.o".
	Inputs   []string // The digests of all required inputs.
	Sources  []string // The paths of all source files.
	Target   string   // The target name, e.g., "//file/base/go:file".
}

Index represents the indexable terms of a compilation.

type ReadWriteDeleter

type ReadWriteDeleter interface {
	Reader
	Writer
	Deleter
}

ReadWriteDeleter expresses the capacity to read, write, and delete data in a compilation database.

type ReadWriter

type ReadWriter interface {
	Reader
	Writer
}

ReadWriter expresses the capacity to both read and write a compilation database.

type Reader

type Reader interface {
	// Revisions calls f with each known revision matching the given filter.
	// If filter == nil or is empty, all known revisions are reported.
	// If f returns an error, that error is returned from Revisions.
	// Timestamps are returned in UTC.
	Revisions(_ context.Context, filter *RevisionsFilter, f func(Revision) error) error

	// Find calls f with the digest of each known compilation matching filter.
	// If filter == nil or is empty, no compilations are reported.
	// If f returns an error, that error is returned from Find.
	Find(_ context.Context, filter *FindFilter, f func(string) error) error

	// Units calls f with the digest, format key, and content of each specified
	// compilation that exists in the store.
	// If f returns an error, that error is returned from Units.
	Units(_ context.Context, unitDigests []string, f func(digest, key string, data []byte) error) error

	// Files calls f with the digest and content of each specified file that
	// exists in the store.
	// If f returns an error, that error is returned from Files.
	Files(_ context.Context, fileDigests []string, f func(string, []byte) error) error

	// FilesExist calls f with the digest of each specified file that exists in
	// the store.
	// If f returns an error, that error is returned from FilesExist.
	FilesExist(_ context.Context, fileDigests []string, f func(string) error) error
}

Reader represents read-only access to an underlying storage layer used to implement a compilation database.

type Revision

type Revision struct {
	Revision, Corpus string
	Timestamp        time.Time
}

A Revision represents a single revision stored in the database.

func (Revision) IsValid

func (r Revision) IsValid() error

IsValid returns an error if the revision or corpus fields are invalid.

func (Revision) String

func (r Revision) String() string

type RevisionsFilter

type RevisionsFilter struct {
	Revision string    // If set return revision markers matching this RE2.
	Corpus   string    // If set, return only revisions for this corpus.
	Until    time.Time // If nonzero, return only revisions at or before this time.
	Since    time.Time // If nonzero, return only revisions at or after this time.
}

RevisionsFilter gives constraints on which revisions are matched by a call to the Revisions method of compdb.Reader.

func (*RevisionsFilter) Compile

func (rf *RevisionsFilter) Compile() (func(Revision) bool, error)

Compile compiles the filter into a matching function that reports whether its argument matches the original filter.

type Unit

type Unit interface {
	encoding.BinaryMarshaler
	json.Marshaler

	// Index returns a the indexable terms of this unit.
	Index() Index

	// Canonicalize organizes the unit into a canonical form.  The meaning of
	// canonicalization is unit-dependent, and may safely be a no-op.
	Canonicalize()

	// Digest produces a unique string representation of a unit sufficient to
	// serve as a content-addressable digest.
	Digest() string

	// LookupVName looks up and returns the VName for the given file path
	// or nil if it could not be found or the operation is unsupported.
	LookupVName(path string) *spb.VName
}

The Unit interface expresses the capabilities required to represent a compilation unit in a data store.

type Writer

type Writer interface {
	// WriteRevision records the specified revision into the store at the given
	// timestamp.  It is an error if rev.Revision == "" or rev.Corpus == "".
	// If replace is true, any previous version of this marker is discarded
	// before writing.
	WriteRevision(_ context.Context, rev Revision, replace bool) error

	// WriteUnit records unit in the store at the given revision, and returns
	// the digest of the stored unit.  It is an error if rev is invalid per
	// WriteRevision.
	WriteUnit(_ context.Context, rev Revision, formatKey string, unit Unit) (string, error)

	// WriteFile fully reads r and records its content as a file in the store.
	// Returns the digest of the stored file.
	WriteFile(_ context.Context, r io.Reader) (string, error)
}

Writer represents write access to an underlying storage layer used to implement a compilation database.