unit

Documentation

Overview

Package unit provides a source unit abstraction over distribution packages in various languages.

Index

• func ExpandPaths(base string, paths []string) ([]string, error)
• func ParseID(unitID string) (name, typ string, err error)
• type ID
  • func (x *ID) Scan(v interface{}) error
  • func (x ID) Value() (driver.Value, error)
• type Info
  • func GetInfo(u SourceUnit) Info
• type RepoSourceUnit
  • func (u *RepoSourceUnit) SourceUnit() (SourceUnit, error)
• type SourceUnit
  • func (u SourceUnit) ID() ID
  • func (u *SourceUnit) OpsSorted() []string

Functions

func ExpandPaths

func ExpandPaths(base string, paths []string) ([]string, error)

ExpandPaths interprets paths, which contains paths (optionally with filepath.Glob-compatible globs) that are relative to base. A list of actual files that are referenced is returned.

func ParseID

func ParseID(unitID string) (name, typ string, err error)

ParseID parses the name and type from a source unit ID (from (*SourceUnit).ID()).

Types

type ID

type ID string

ID is a source unit ID.

func (*ID) Scan

func (x *ID) Scan(v interface{}) error

Scan implements sql.Scanner.

func (ID) Value

func (x ID) Value() (driver.Value, error)

Value implements driver.Valuer.

type Info

type Info struct {
	// NameInRepository is the name to use when displaying the source unit in
	// the context of the repository in which it is defined. This name
	// typically needs less qualification than GlobalName.
	//
	// For example, a Go package's GlobalName is its repository URI basename
	// plus its directory path within the repository (e.g.,
	// "github.com/user/repo/x/y"'s NameInRepository is "repo/x/y"). Because npm
	// and pip packages are named globally, their name is probably appropriate
	// to use as both the unit's NameInRepository and GlobalName.
	NameInRepository string

	// GlobalName is the name to use when displaying the source unit *OUTSIDE OF*
	// the context of the repository in which it is defined.
	//
	// For example, a Go package's GlobalName is its full import path. Because
	// npm and pip packages are named globally, their name is probably
	// appropriate to use as both the unit's NameInRepository and GlobalName.
	GlobalName string

	// Description is a short (~1-sentence) description of the source unit.
	Description string

	// TypeName is the human-readable name of the type of source unit; e.g., "Go
	// package".
	TypeName string
}

func GetInfo

func GetInfo(u SourceUnit) Info

GetInfo returns a source unit's Info field if non-nil, or otherwise an Info struct filled with values derived from the source unit's name and type.

type RepoSourceUnit

type RepoSourceUnit struct {
	Repo     string
	CommitID string `db:"commit_id"`
	UnitType string `db:"unit_type"`
	Unit     string

	// Data is the JSON of the underlying SourceUnit.
	Data types.JsonText
}

A RepoSourceUnit is the "concrete" form of SourceUnit that includes information about which repository (and commit) the source unit exists in. In general, type SourceUnit is used during analysis of a single source unit and type RepoSourceUnit is used afterwards (either in cross-source-unit analysis, such as cross-reference resolution, or in after-the-fact DB/API queries).

func (*RepoSourceUnit) SourceUnit

func (u *RepoSourceUnit) SourceUnit() (SourceUnit, error)

SourceUnit decodes u's Data JSON field to the SourceUnit it represents.

type SourceUnit

type SourceUnit struct {
	// Name is an opaque identifier for this source unit that MUST be unique
	// among all other source units of the same type in the same repository.
	//
	// Two source units of different types in a repository may have the same name.
	// To obtain an identifier for a source unit that is guaranteed to be unique
	// repository-wide, use the ID method.
	Name string

	// Type is the type of source unit this represents, such as "GoPackage".
	Type string

	// Repo is the URI of the repository containing this source unit, if any.
	// The scanner tool does not need to set this field - it can be left blank,
	// to be filled in by the `src` tool
	Repo string

	// Globs is a list of patterns that match files that make up this source
	// unit. It is used to detect when the source unit definition is out of date
	// (e.g., when a file matches the glob but is not in the Files list).
	//
	// TODO(sqs): implement this in the Makefiles
	Globs []string

	// Files is all of the files that make up this source unit. Filepaths should
	// be relative to the repository root.
	Files []string

	// Dir is the root directory of this source unit. It is optional and maybe
	// empty.
	Dir string

	// Dependencies is a list of dependencies that this source unit has. The
	// schema for these dependencies is internal to the scanner that produced
	// this source unit. The dependency resolver is expected to know how to
	// interpret this schema.
	//
	// The dependency information stored in this field should be able to be very
	// quickly determined by the scanner. The scanner should not perform any
	// dependency resolution on these entries. This is because the scanner is
	// run frequently and should execute very quickly, and dependency resolution
	// is often slow (requiring network access, etc.).
	Dependencies []interface{} `json:",omitempty"`

	// Info is an optional field that contains additional information used to
	// display the source unit
	Info *Info `json:",omitempty"`

	// Data is additional data dumped by the scanner about this source unit. It
	// typically holds information that the scanner wants to make available to
	// other components in the toolchain (grapher, dep resolver, etc.).
	Data interface{} `json:",omitempty"`

	// Config is an arbitrary key-value property map. The Config map from the
	// tree config is copied verbatim to each source unit. It can be used to
	// pass options from the Srcfile to tools.
	Config map[string]interface{} `json:",omitempty"`

	// Ops enumerates the operations that should be performed on this source
	// unit. Each key is the name of an operation, and the value is the tool to
	// use to perform that operation. If the value is nil, the tool is chosen
	// automatically according to the user's configuration.
	Ops map[string]*toolchain.ToolRef
}

START SourceUnit OMIT

func (SourceUnit) ID

func (u SourceUnit) ID() ID

ID returns an opaque identifier for this source unit that is guaranteed to be unique among all other source units in the same repository.

func (*SourceUnit) OpsSorted

func (u *SourceUnit) OpsSorted() []string

OpsSorted returns the keys of the Ops map in sorted order.