graph

package
v0.2.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 22, 2016 License: BSD-3-Clause, MIT Imports: 13 Imported by: 56

Documentation

Overview

Package graph is a generated protocol buffer package.

It is generated from these files: 

def.proto
doc.proto
output.proto
ref.proto

It has these top-level messages: 

DefKey
Def
DefDoc
DefFormatStrings
QualFormatStrings
Doc
Output
Ref
RefDefKey

Index

Constants

View Source 
const (
	// An Unqualified name is just the def's name.
	//
	// Examples:
	//
	//   Go method         `MyMethod`
	//   Python method     `my_method`
	//   JavaScript method `myMethod`
	Unqualified Qualification = ""

	// A ScopeQualified name is the language-specific description of the
	// def's defining scope plus the def's unqualified name. It should
	// uniquely describe the def among all other defs defined in the same
	// logical package (but this is not strictly defined or enforced).
	//
	// Examples:
	//
	//   Go method         `(*MyType).MyMethod`
	//   Python method     `MyClass.my_method`
	//   JavaScript method `MyConstructor.prototype.myMethod`
	ScopeQualified = "scope"

	// A DepQualified name is the package/module name (as seen by an external
	// library that imports/depends on the def's package/module) plus the
	// def's scope-qualified name. If there are nested packages, it should
	// describe enough of the package hierarchy to distinguish it from other
	// similarly named defs (but this is not strictly defined or enforced).
	//
	// Examples:
	//
	//   Go method       `(*mypkg.MyType).MyMethod`
	//   Python method   `mypkg.MyClass.my_method`
	//   CommonJS method `mymodule.MyConstructor.prototype.myMethod`
	DepQualified = "dep"

	// A RepositoryWideQualified name is the full package/module name(s) plus
	// the def's scope-qualified name. It should describe enough of the
	// package hierarchy so that it is unique in its repository.
	// RepositoryWideQualified differs from DepQualified in that the former
	// includes the full nested package/module path from the repository root
	// (e.g., 'a/b.C' for a Go func C in the repository 'github.com/user/a'
	// subdirectory 'b'), while DepQualified would only be the last directory
	// component (e.g., 'b.C' in that example).
	//
	// Examples:
	//
	//   Go method       `(*mypkg/subpkg.MyType).MyMethod`
	//   Python method   `mypkg.subpkg.MyClass.my_method` (unless mypkg =~ subpkg)
	//   CommonJS method `mypkg.mymodule.MyConstructor.prototype.myMethod` (unless mypkg =~ mymodule)
	RepositoryWideQualified = "repo-wide"

	// A LanguageWideQualified name is the library/repository name plus the
	// package-qualified def name. It should describe the def so that it
	// is logically unique among all defs that could reasonably exist for the
	// language that the def is written in (but this is not strictly defined
	// or enforced).
	//
	// Examples:
	//
	//   Go method       `(*github.com/user/repo/mypkg.MyType).MyMethod`
	//   Python method   `mylib.MyClass.my_method` (if mylib =~ mypkg, as for Django, etc.)
	//   CommonJS method `mylib.MyConstructor.prototype.myMethod` (if mylib =~ mymod, as for caolan/async, etc.)
	LanguageWideQualified = "lang-wide"
)
View Source 
const (
	// StatXRefs is the number of external references to a def (i.e.,
	// references from other repositories). It is only computed for abstract
	// defs (see the docs for DefKey) because it is not easy to determine
	// which specific commit a ref references (for external refs).
	StatXRefs = "xrefs"

	// StatRRefs is the number of references to a def from the same
	// repository in which the def is defined. It is inclusive of the
	// StatURefs count. It is only computed for concrete defs (see the docs
	// for DefKey) because otherwise it would count 1 rref for each unique
	// revision of the repository that we have processed. (It is easy to
	// determine which specific commit an internal ref references; we just
	// assume it references a def in the same commit.)
	StatRRefs = "rrefs"

	// StatURefs is the number of references to a def from the same source
	// unit in which the def is defined. It is included in the StatRRefs
	// count. It is only computed for concrete defs (see the docs for
	// DefKey) because otherwise it would count 1 uref for each revision of
	// the repository that we have processed.
	StatURefs = "urefs"

	// StatAuthors is the number of distinct resolved people who contributed
	// code to a def's definition (according to a VCS "blame" of the
	// version). It is only computed for concrete defs (see the docs for
	// DefKey).
	StatAuthors = "authors"

	// StatClients is the number of distinct resolved people who have committed
	// refs that reference a def. It is only computed for abstract defs
	// (see the docs for DefKey) because it is not easy to determine which
	// specific commit a ref references.
	StatClients = "clients"

	// StatDependents is the number of distinct repositories that contain refs
	// that reference a def. It is only computed for abstract defs (see
	// the docs for DefKey) because it is not easy to determine which
	// specific commit a ref references.
	StatDependents = "dependents"

	// StatExportedElements is the number of exported defs whose path is a
	// descendant of this def's path (and that is in the same repository and
	// source unit). It is only computed for concrete defs (see the docs for
	// DefKey) because otherwise it would count 1 exported element for each
	// revision of the repository that we have processed.
	StatExportedElements = "exported_elements"
)

Variables

View Source 
var (
	ErrInvalidLengthDef = fmt.Errorf("proto: negative length found during unmarshaling")
	ErrIntOverflowDef   = fmt.Errorf("proto: integer overflow")
)
View Source 
var (
	ErrInvalidLengthDoc = fmt.Errorf("proto: negative length found during unmarshaling")
	ErrIntOverflowDoc   = fmt.Errorf("proto: integer overflow")
)
View Source 
var (
	ErrInvalidLengthOutput = fmt.Errorf("proto: negative length found during unmarshaling")
	ErrIntOverflowOutput   = fmt.Errorf("proto: integer overflow")
)
View Source 
var (
	ErrInvalidLengthRef = fmt.Errorf("proto: negative length found during unmarshaling")
	ErrIntOverflowRef   = fmt.Errorf("proto: integer overflow")
)
View Source 
var AllStatTypes = []StatType{StatXRefs, StatRRefs, StatURefs, StatAuthors, StatClients, StatDependents, StatExportedElements}
View Source 
var ErrDefNotExist = errors.New("def does not exist")
View Source 
var MakeDefFormatters = make(map[string]MakeDefFormatter)

MakeDefFormatter holds MakeDefFormatters that toolchains have registered with RegisterMakeDefFormatter.

View Source 
var QualLevels = []Qualification{
	Unqualified, ScopeQualified, DepQualified, RepositoryWideQualified, LanguageWideQualified,
}

QualLevels associates a number (the slice index) with each Qualification, for use in format strings (so that, e.g., "%.0n" means Unqualified name and "%.2n" means DepQualified name).

Functions

func IsNotExist 

func IsNotExist(err error) bool

func IsValidTreePath added in v0.0.33 

func IsValidTreePath(treePath string) bool

func MakeURI added in v0.0.27 

func MakeURI(cloneURL string) string

MakeURI converts a repository clone URL, such as "git://github.com/user/repo.git", to a normalized URI string, such as "github.com/user/repo" lexically. MakeURI panics if there is an error, and should only be used if cloneURL is a correctly-formed URL. It is a wrapper around TryMakeURI.

func RegisterMakeDefFormatter added in v0.0.9 

func RegisterMakeDefFormatter(unitType string, f MakeDefFormatter)

RegisterMakeDefFormatter makes a DefFormatter constructor function (MakeDefFormatter) available for defs with the specified unitType. If Register is called twice with the same unitType or if sf is nil, it panics

func TryMakeURI added in v0.0.27 

func TryMakeURI(cloneURL string) (string, error)

TryMakeURI converts a repository clone URL, such as "git://github.com/user/repo.git", to a normalized URI string, such as "github.com/user/repo" lexically. TryMakeURI returns an error if cloneURL is empty or malformed.

The following forms are supported: - transport://... (http://foo.bar) - vcs:transport://... (hg:http://foo.bar) - 'scm':vcs:transport://... (scm:git:git://foo.bar) - user@host:path (assumed SSH) - host:path (assumed SSH)

func URIEqual added in v0.0.27 

func URIEqual(a, b string) bool

URIEqual returns true if a and b are equal, based on a case insensitive comparison (strings.EqualFold).

func UniqueRefDefs added in v0.0.9 

func UniqueRefDefs(refs []*Ref, m map[RefDefKey]int) map[RefDefKey]int

UniqueRefDefs groups refs by the RefDefKey field and returns a map of how often each RefDefKey appears. If m is non-nil, counts are incremented and a new map is not created.

Types

type Def added in v0.0.9 

type Def struct {
	// DefKey is the natural unique key for a def. It is stable
	// (subsequent runs of a grapher will emit the same defs with the same
	// DefKeys).
	DefKey `protobuf:"bytes,1,opt,name=Key,embedded=Key" json:""`
	// Name of the definition. This need not be unique.
	Name string `protobuf:"bytes,2,opt,name=Name,proto3" json:"Name"`
	// Kind is the kind of thing this definition is. This is
	// language-specific. Possible values include "type", "func",
	// "var", etc.
	Kind     string `protobuf:"bytes,3,opt,name=Kind,proto3" json:"Kind,omitempty"`
	File     string `protobuf:"bytes,4,opt,name=File,proto3" json:"File"`
	DefStart uint32 `protobuf:"varint,5,opt,name=DefStart,proto3" json:"DefStart"`
	DefEnd   uint32 `protobuf:"varint,6,opt,name=DefEnd,proto3" json:"DefEnd"`
	// Exported is whether this def is part of a source unit's
	// public API. For example, in Java a "public" field is
	// Exported.
	Exported bool `protobuf:"varint,7,opt,name=Exported,proto3" json:"Exported,omitempty"`
	// Local is whether this def is local to a function or some
	// other inner scope. Local defs do *not* have module,
	// package, or file scope. For example, in Java a function's
	// args are Local, but fields with "private" scope are not
	// Local.
	Local bool `protobuf:"varint,8,opt,name=Local,proto3" json:"Local,omitempty"`
	// Test is whether this def is defined in test code (as opposed to main
	// code). For example, definitions in Go *_test.go files have Test = true.
	Test bool `protobuf:"varint,9,opt,name=Test,proto3" json:"Test,omitempty"`
	// Data contains additional language- and toolchain-specific information
	// about the def. Data is used to construct function signatures,
	// import/require statements, language-specific type descriptions, etc.
	Data sourcegraph_com_sqs_pbtypes.RawMessage `protobuf:"bytes,10,opt,name=Data,proto3,casttype=sourcegraph.com/sqs/pbtypes.RawMessage" json:"Data,omitempty"`
	// Docs are docstrings for this Def. This field is not set in the
	// Defs produced by graphers; they should emit docs in the
	// separate Docs field on the graph.Output struct.
	Docs []*DefDoc `protobuf:"bytes,11,rep,name=Docs" json:"Docs,omitempty"`
	// TreePath is a structurally significant path descriptor for a def. For
	// many languages, it may be identical or similar to DefKey.Path.
	// However, it has the following constraints, which allow it to define a
	// def tree.
	//
	// A tree-path is a chain of '/'-delimited components. A component is either a
	// def name or a ghost component.
	// - A def name satifies the regex [^/-][^/]*
	// - A ghost component satisfies the regex -[^/]*
	// Any prefix of a tree-path that terminates in a def name must be a valid
	// tree-path for some def.
	// The following regex captures the children of a tree-path X: X(/-[^/]*)*(/[^/-][^/]*)
	TreePath string `protobuf:"bytes,17,opt,name=TreePath,proto3" json:"TreePath,omitempty"`
}

Def is a definition in code.

func (*Def) Fmt added in v0.0.9 

func (s *Def) Fmt() DefPrintFormatter

func (*Def) Marshal added in v0.0.33 

func (m *Def) Marshal() (data []byte, err error)

func (*Def) MarshalTo added in v0.0.33 

func (m *Def) MarshalTo(data []byte) (int, error)

func (*Def) ProtoMessage added in v0.0.33 

func (*Def) ProtoMessage()

func (*Def) Reset added in v0.0.33 

func (m *Def) Reset()

func (*Def) Size added in v0.0.33 

func (m *Def) Size() (n int)

func (*Def) String added in v0.0.9 

func (m *Def) String() string

func (*Def) Unmarshal added in v0.0.33 

func (m *Def) Unmarshal(data []byte) error

type DefDoc added in v0.0.33 

type DefDoc struct {
	// Format is the the MIME-type that the documentation is stored
	// in. Valid formats include 'text/html', 'text/plain',
	// 'text/x-markdown', text/x-rst'.
	Format string `protobuf:"bytes,1,opt,name=Format,proto3" json:"Format"`
	// Data is the actual documentation text.
	Data string `protobuf:"bytes,2,opt,name=Data,proto3" json:"Data"`
}

DefDoc is documentation on a Def.

func (*DefDoc) Marshal added in v0.0.33 

func (m *DefDoc) Marshal() (data []byte, err error)

func (*DefDoc) MarshalTo added in v0.0.33 

func (m *DefDoc) MarshalTo(data []byte) (int, error)

func (*DefDoc) ProtoMessage added in v0.0.33 

func (*DefDoc) ProtoMessage()

func (*DefDoc) Reset added in v0.0.33 

func (m *DefDoc) Reset()

func (*DefDoc) Size added in v0.0.33 

func (m *DefDoc) Size() (n int)

func (*DefDoc) String added in v0.0.33 

func (m *DefDoc) String() string

func (*DefDoc) Unmarshal added in v0.0.33 

func (m *DefDoc) Unmarshal(data []byte) error

type DefFormatStrings added in v0.1.0 

type DefFormatStrings struct {
	Name                 QualFormatStrings `protobuf:"bytes,1,opt,name=Name" json:"Name"`
	Type                 QualFormatStrings `protobuf:"bytes,2,opt,name=Type" json:"Type"`
	NameAndTypeSeparator string            `protobuf:"bytes,3,opt,name=NameAndTypeSeparator,proto3" json:"NameAndTypeSeparator,omitempty"`
	Language             string            `protobuf:"bytes,4,opt,name=Language,proto3" json:"Language,omitempty"`
	DefKeyword           string            `protobuf:"bytes,5,opt,name=DefKeyword,proto3" json:"DefKeyword,omitempty"`
	Kind                 string            `protobuf:"bytes,6,opt,name=Kind,proto3" json:"Kind,omitempty"`
}

DefFormatStrings contains the various def format strings.

func (*DefFormatStrings) Marshal added in v0.2.0 

func (m *DefFormatStrings) Marshal() (data []byte, err error)

func (*DefFormatStrings) MarshalTo added in v0.2.0 

func (m *DefFormatStrings) MarshalTo(data []byte) (int, error)

func (*DefFormatStrings) ProtoMessage added in v0.1.0 

func (*DefFormatStrings) ProtoMessage()

func (*DefFormatStrings) Reset added in v0.1.0 

func (m *DefFormatStrings) Reset()

func (*DefFormatStrings) Size added in v0.2.0 

func (m *DefFormatStrings) Size() (n int)

func (*DefFormatStrings) String added in v0.1.0 

func (m *DefFormatStrings) String() string

func (*DefFormatStrings) Unmarshal added in v0.2.0 

func (m *DefFormatStrings) Unmarshal(data []byte) error

type DefFormatter added in v0.0.9 

type DefFormatter interface {
	// Name formats the def's name with the specified level of qualification.
	Name(qual Qualification) string

	// Type is the type of the def s, if s is not itself a type. If s is
	// itself a type, then Type returns its underlying type.
	//
	// Outputs:
	//
	//   TYPE OF s          RESULT
	//   ------------   -----------------------------------------------------------------
	//   named type     the named type's name
	//   primitive      the primitive's name
	//   function       `(arg1, arg2, ..., argN)` with language-specific type annotations
	//   package        empty
	//   anon. type     the leading keyword (or similar) of the anonymous type definition
	//
	// These rules are not strictly defined or enforced. Language toolchains
	// should freely bend the rules (after noting important exceptions here) to
	// produce sensible output.
	Type(qual Qualification) string

	// NameAndTypeSeparator is the string that should be inserted between the
	// def's name and type. This is typically empty for functions (so that
	// they are formatted with the left paren immediately following the name,
	// like `F(a)`) and a single space for other defs (e.g., `MyVar string`).
	NameAndTypeSeparator() string

	// Language is the name of the programming language that s is in; e.g.,
	// "Python" or "Go".
	Language() string

	// DefKeyword is the language keyword used to define the def (e.g.,
	// 'class', 'type', 'func').
	DefKeyword() string

	// Kind is the language-specific kind of this def (e.g., 'package', 'field', 'CommonJS module').
	Kind() string
}

DefFormatter formats a def.

type DefKey added in v0.0.9 

type DefKey struct {
	// Repo is the VCS repository that defines this definition.
	Repo string `protobuf:"bytes,1,opt,name=Repo,proto3" json:"Repo,omitempty"`
	// CommitID is the ID of the VCS commit that this definition was defined in. The
	// CommitID is always a full commit ID (40 hexadecimal characters for git
	// and hg), never a branch or tag name.
	CommitID string `protobuf:"bytes,2,opt,name=CommitID,proto3" json:"CommitID,omitempty"`
	// UnitType is the type name of the source unit (obtained from unit.Type(u))
	// that this definition was defined in.
	UnitType string `protobuf:"bytes,3,opt,name=UnitType,proto3" json:"UnitType,omitempty"`
	// Unit is the name of the source unit (obtained from u.Name()) that this
	// definition was defined in.
	Unit string `protobuf:"bytes,4,opt,name=Unit,proto3" json:"Unit,omitempty"`
	// Path is a unique identifier for the def, relative to the source unit.
	// It should remain stable across commits as long as the def is the
	// "same" def. Its Elasticsearch mapping is defined separately (because
	// it is a multi_field, which the struct tag can't currently represent).
	//
	// Path encodes no structural semantics. Its only meaning is to be a stable
	// unique identifier within a given source unit. In many languages, it is
	// convenient to use the namespace hierarchy (with some modifications) as
	// the Path, but this may not always be the case. I.e., don't rely on Path
	// to find parents or children or any other structural propreties of the
	// def hierarchy). See Def.TreePath instead.
	Path string `protobuf:"bytes,5,opt,name=Path,proto3" json:"Path"`
}

DefKey specifies a definition, either concretely or abstractly. A concrete definition key has a non-empty CommitID and refers to a definition defined in a specific commit. An abstract definition key has an empty CommitID and is considered to refer to definitions from any number of commits (so long as the Repo, UnitType, Unit, and Path match).

You can think of CommitID as the time dimension. With an empty CommitID, you are referring to a definition that may or may not exist at various times. With a non-empty CommitID, you are referring to a specific definition of a definition at the time specified by the CommitID.

func (*DefKey) Marshal added in v0.0.33 

func (m *DefKey) Marshal() (data []byte, err error)

func (*DefKey) MarshalTo added in v0.0.33 

func (m *DefKey) MarshalTo(data []byte) (int, error)

func (*DefKey) ProtoMessage added in v0.0.33 

func (*DefKey) ProtoMessage()

func (*DefKey) Reset added in v0.0.33 

func (m *DefKey) Reset()

func (*DefKey) Size added in v0.0.33 

func (m *DefKey) Size() (n int)

func (*DefKey) String added in v0.0.9 

func (m *DefKey) String() string

func (*DefKey) Unmarshal added in v0.0.33 

func (m *DefKey) Unmarshal(data []byte) error

type DefPrintFormatter added in v0.0.9 

type DefPrintFormatter interface {
	DefFormatter
	fmt.Formatter
}

func PrintFormatter 

func PrintFormatter(s *Def) DefPrintFormatter

Formatter creates a string formatter for a def.

The verbs: 

%n     qualified name
%w     language keyword used to define the def (e.g., 'class', 'type', 'func')
%k     language-specific kind of this def (e.g., 'package', 'field', 'CommonJS module')
%t     type

The flags: 

' '    (in `% t`) prepend the language-specific delimiter between a def's name and type

See DefFormatter for more information.

type Defs added in v0.0.9 

type Defs []*Def

func (Defs) KeySet added in v0.0.12 

func (defs Defs) KeySet() (keys map[DefKey]struct{}, err error)

func (Defs) Keys added in v0.0.9 

func (defs Defs) Keys() (keys []DefKey)

func (Defs) Len added in v0.0.9 

func (vs Defs) Len() int

func (Defs) Less added in v0.0.9 

func (vs Defs) Less(i, j int) bool

func (Defs) Swap added in v0.0.9 

func (vs Defs) Swap(i, j int)

type Doc 

type Doc struct {
	// DefKey points to the Def that this documentation pertains to.
	DefKey `protobuf:"bytes,1,opt,name=Key,embedded=Key" json:""`
	// Format is the the MIME-type that the documentation is stored
	// in. Valid formats include 'text/html', 'text/plain',
	// 'text/x-markdown', text/x-rst'.
	Format string `protobuf:"bytes,2,opt,name=Format,proto3" json:"Format"`
	// Data is the actual documentation text.
	Data string `protobuf:"bytes,3,opt,name=Data,proto3" json:"Data"`
	// File is the filename where this Doc exists.
	File string `protobuf:"bytes,4,opt,name=File,proto3" json:"File,omitempty"`
	// Start is the byte offset of this Doc's first byte in File.
	Start uint32 `protobuf:"varint,5,opt,name=Start,proto3" json:"Start,omitempty"`
	// End is the byte offset of this Doc's last byte in File.
	End uint32 `protobuf:"varint,6,opt,name=End,proto3" json:"End,omitempty"`
}

Doc is documentation on a Def.

func (*Doc) Key added in v0.0.32 

func (d *Doc) Key() DocKey

Key returns the unique key for the doc.

func (*Doc) Marshal added in v0.0.33 

func (m *Doc) Marshal() (data []byte, err error)

func (*Doc) MarshalTo added in v0.0.33 

func (m *Doc) MarshalTo(data []byte) (int, error)

func (*Doc) ProtoMessage added in v0.0.33 

func (*Doc) ProtoMessage()

func (*Doc) Reset added in v0.0.33 

func (m *Doc) Reset()

func (*Doc) Size added in v0.0.33 

func (m *Doc) Size() (n int)

func (*Doc) String added in v0.0.33 

func (m *Doc) String() string

func (*Doc) Unmarshal added in v0.0.33 

func (m *Doc) Unmarshal(data []byte) error

type DocKey added in v0.0.32 

type DocKey struct {
	DefKey
	Format string
	File   string
	Start  uint32
}

DocKey is the unique key for a doc. Each doc within a source unit must have a unique DocKey.

Freestanding comments will not have an associated DefKey, but they *must* provide 'Start' and 'File'.

func (DocKey) String added in v0.0.32 

func (d DocKey) String() string

type Docs 

type Docs []*Doc

func (Docs) Len 

func (vs Docs) Len() int

func (Docs) Less 

func (vs Docs) Less(i, j int) bool

func (Docs) Swap 

func (vs Docs) Swap(i, j int)

type MakeDefFormatter added in v0.0.9 

type MakeDefFormatter func(*Def) DefFormatter

A MakeDefFormatter is a function, typically implemented by toolchains, that creates a DefFormatter for a def.

type Output added in v0.0.33 

type Output struct {
	Defs []*Def     `protobuf:"bytes,1,rep,name=Defs" json:"Defs,omitempty"`
	Refs []*Ref     `protobuf:"bytes,2,rep,name=Refs" json:"Refs,omitempty"`
	Docs []*Doc     `protobuf:"bytes,3,rep,name=Docs" json:"Docs,omitempty"`
	Anns []*ann.Ann `protobuf:"bytes,4,rep,name=Anns" json:"Anns,omitempty"`
}

func (*Output) Marshal added in v0.0.33 

func (m *Output) Marshal() (data []byte, err error)

func (*Output) MarshalTo added in v0.0.33 

func (m *Output) MarshalTo(data []byte) (int, error)

func (*Output) ProtoMessage added in v0.0.33 

func (*Output) ProtoMessage()

func (*Output) Reset added in v0.0.33 

func (m *Output) Reset()

func (*Output) Size added in v0.0.33 

func (m *Output) Size() (n int)

func (*Output) String added in v0.0.33 

func (m *Output) String() string

func (*Output) Unmarshal added in v0.0.33 

func (m *Output) Unmarshal(data []byte) error

type Propagate 

type Propagate struct {
	// Src is the def whose type/value is being propagated to the dst def.
	SrcRepo     string
	SrcPath     string
	SrcUnit     string
	SrcUnitType string

	// Dst is the def that is receiving a propagated type/value from the src def.
	DstRepo     string
	DstPath     string
	DstUnit     string
	DstUnitType string
}

Propagate describes type/value propagation in code. A Propagate entry from A (src) to B (dst) indicates that the type/value of A propagates to B. In Tern, this is indicated by A having a "fwd" property whose value is an array that includes B.

## Motivation & example

For example, consider the following JavaScript code: 

var a = Foo;
var b = a;

Foo, a, and b are each their own def. We could resolve all of them to the def of their original type (perhaps Foo), but there are occasions when you do want to see only the definition of a or b and examples thereof. Therefore, we need to represent them as distinct defs.

Even though Foo, a, and b are distinct defs, there are propagation relationships between them that are important to represent. The type of Foo propagates to both a and b, and the type of a propagates to b. In this case, we would have 3 Propagates: Propagate{Src: "Foo", Dst: "a"}, Propagate{Src: "Foo", Dst: "b"}, and Propagate{Src: "a", Dst: "b"}. (The propagation relationships could be described by just the first and last Propagates, but we explicitly include all paths as a denormalization optimization to avoid requiring an unbounded number of DB queries to determine which defs a type propagates to or from.)

## Directionality

Propagation is unidirectional, in the general case. In the example above, if Foo referred to a JavaScript object and if the code were evaluated, any *runtime* type changes (e.g., setting a property) on Foo, a, and b would be reflected on all of the others. But this doesn't hold for static analysis; it's not always true that if a property "a.x" or "b.x" exists, then "Foo.x" exists. The simplest example is when Foo is an external definition. Perhaps this example file (which uses Foo as a library) modifies Foo to add a new property, but other libraries that use Foo would never see that property because they wouldn't be executed in the same context as this example file. So, in general, we cannot say that Foo receives all types applied to defs that Foo propagates to.

## Hypothetical Python example

Consider the following 2 Python files: 

"""file1.py"""
class Foo(object): end

"""file2.py"""
from .file1 import Foo
Foo2 = Foo

In this example, there would be one Propagate: Propagate{Src: "file1/Foo", Dst: "file2/Foo2}.

type QualFormatStrings added in v0.1.0 

type QualFormatStrings struct {
	Unqualified             string `protobuf:"bytes,1,opt,name=Unqualified,proto3" json:"Unqualified,omitempty"`
	ScopeQualified          string `protobuf:"bytes,2,opt,name=ScopeQualified,proto3" json:"ScopeQualified,omitempty"`
	DepQualified            string `protobuf:"bytes,3,opt,name=DepQualified,proto3" json:"DepQualified,omitempty"`
	RepositoryWideQualified string `protobuf:"bytes,4,opt,name=RepositoryWideQualified,proto3" json:"RepositoryWideQualified,omitempty"`
	LanguageWideQualified   string `protobuf:"bytes,5,opt,name=LanguageWideQualified,proto3" json:"LanguageWideQualified,omitempty"`
}

QualFormatStrings holds the formatted string for each Qualification for a def (for either Name or Type).

func (*QualFormatStrings) Marshal added in v0.2.0 

func (m *QualFormatStrings) Marshal() (data []byte, err error)

func (*QualFormatStrings) MarshalTo added in v0.2.0 

func (m *QualFormatStrings) MarshalTo(data []byte) (int, error)

func (*QualFormatStrings) ProtoMessage added in v0.1.0 

func (*QualFormatStrings) ProtoMessage()

func (*QualFormatStrings) Reset added in v0.1.0 

func (m *QualFormatStrings) Reset()

func (*QualFormatStrings) Size added in v0.2.0 

func (m *QualFormatStrings) Size() (n int)

func (*QualFormatStrings) String added in v0.1.0 

func (m *QualFormatStrings) String() string

func (*QualFormatStrings) Unmarshal added in v0.2.0 

func (m *QualFormatStrings) Unmarshal(data []byte) error

type Qualification 

type Qualification string

A Qualification specifies how much to qualify names when formatting defs and their type information.

type Ref 

type Ref struct {
	// DefRepo is the repository URI of the Def that this Ref refers
	// to.
	DefRepo string `protobuf:"bytes,1,opt,name=DefRepo,proto3" json:"DefRepo,omitempty"`
	// DefUnitType is the source unit type of the Def that this Ref refers to.
	DefUnitType string `protobuf:"bytes,3,opt,name=DefUnitType,proto3" json:"DefUnitType,omitempty"`
	// DefUnit is the name of the source unit that this ref exists in.
	DefUnit string `protobuf:"bytes,4,opt,name=DefUnit,proto3" json:"DefUnit,omitempty"`
	// Path is the path of the Def that this ref refers to.
	DefPath string `protobuf:"bytes,5,opt,name=DefPath,proto3" json:"DefPath"`
	// Repo is the VCS repository in which this ref exists.
	Repo string `protobuf:"bytes,6,opt,name=Repo,proto3" json:"Repo,omitempty"`
	// CommitID is the ID of the VCS commit that this ref exists
	// in. The CommitID is always a full commit ID (40 hexadecimal
	// characters for git and hg), never a branch or tag name.
	CommitID string `protobuf:"bytes,7,opt,name=CommitID,proto3" json:"CommitID,omitempty"`
	// UnitType is the type name of the source unit that this ref
	// exists in.
	UnitType string `protobuf:"bytes,8,opt,name=UnitType,proto3" json:"UnitType,omitempty"`
	// Unit is the name of the source unit that this ref exists in.
	Unit string `protobuf:"bytes,9,opt,name=Unit,proto3" json:"Unit,omitempty"`
	// Def is true if this Ref spans the name of the Def it points to.
	Def bool `protobuf:"varint,17,opt,name=Def,proto3" json:"Def,omitempty"`
	// File is the filename in which this Ref exists.
	File string `protobuf:"bytes,10,opt,name=File,proto3" json:"File,omitempty"`
	// Start is the byte offset of this ref's first byte in File.
	Start uint32 `protobuf:"varint,11,opt,name=Start,proto3" json:"Start"`
	// End is the byte offset of this ref's last byte in File.
	End uint32 `protobuf:"varint,12,opt,name=End,proto3" json:"End"`
}

Ref represents a reference from source code to a Def.

func (*Ref) DefKey added in v0.0.9 

func (r *Ref) DefKey() DefKey

func (*Ref) Marshal added in v0.0.33 

func (m *Ref) Marshal() (data []byte, err error)

func (*Ref) MarshalTo added in v0.0.33 

func (m *Ref) MarshalTo(data []byte) (int, error)

func (*Ref) ProtoMessage added in v0.0.33 

func (*Ref) ProtoMessage()

func (*Ref) RefDefKey added in v0.0.9 

func (r *Ref) RefDefKey() RefDefKey

func (*Ref) RefKey 

func (r *Ref) RefKey() RefKey

func (*Ref) Reset added in v0.0.33 

func (m *Ref) Reset()

func (*Ref) SetFromDefKey added in v0.0.9 

func (r *Ref) SetFromDefKey(k DefKey)

func (*Ref) Size added in v0.0.33 

func (m *Ref) Size() (n int)

func (*Ref) String added in v0.0.33 

func (m *Ref) String() string

func (*Ref) Unmarshal added in v0.0.33 

func (m *Ref) Unmarshal(data []byte) error

type RefDefKey added in v0.0.9 

type RefDefKey struct {
	DefRepo     string `protobuf:"bytes,1,opt,name=DefRepo,proto3" json:"DefRepo,omitempty"`
	DefUnitType string `protobuf:"bytes,3,opt,name=DefUnitType,proto3" json:"DefUnitType,omitempty"`
	DefUnit     string `protobuf:"bytes,4,opt,name=DefUnit,proto3" json:"DefUnit,omitempty"`
	DefPath     string `protobuf:"bytes,5,opt,name=DefPath,proto3" json:"DefPath"`
}

func (*RefDefKey) Marshal added in v0.0.33 

func (m *RefDefKey) Marshal() (data []byte, err error)

func (*RefDefKey) MarshalTo added in v0.0.33 

func (m *RefDefKey) MarshalTo(data []byte) (int, error)

func (*RefDefKey) ProtoMessage added in v0.0.33 

func (*RefDefKey) ProtoMessage()

func (*RefDefKey) Reset added in v0.0.33 

func (m *RefDefKey) Reset()

func (*RefDefKey) Size added in v0.0.33 

func (m *RefDefKey) Size() (n int)

func (*RefDefKey) String added in v0.0.33 

func (m *RefDefKey) String() string

func (*RefDefKey) Unmarshal added in v0.0.33 

func (m *RefDefKey) Unmarshal(data []byte) error

type RefKey 

type RefKey struct {
	DefRepo     string `json:",omitempty"`
	DefUnitType string `json:",omitempty"`
	DefUnit     string `json:",omitempty"`
	DefPath     string `json:",omitempty"`
	Def         bool   `json:",omitempty"`
	Repo        string `json:",omitempty"`
	UnitType    string `json:",omitempty"`
	Unit        string `json:",omitempty"`
	File        string `json:",omitempty"`
	CommitID    string `json:",omitempty"`
	Start       uint32 `json:",omitempty"`
	End         uint32 `json:",omitempty"`
}

func (*RefKey) RefDefKey added in v0.0.9 

func (r *RefKey) RefDefKey() RefDefKey

type RefSet 

type RefSet struct {
	// contains filtered or unexported fields
}

RefSet is a set of Refs. It can used to determine whether a grapher emits duplicate refs.

func NewRefSet 

func NewRefSet() *RefSet

func (*RefSet) AddAndCheckUnique 

func (c *RefSet) AddAndCheckUnique(ref Ref) (duplicate bool)

AddAndCheckUnique adds ref to the set of seen refs, and returns whether the ref already existed in the set.

type Refs 

type Refs []*Ref

func (Refs) Len 

func (vs Refs) Len() int

func (Refs) Less 

func (vs Refs) Less(i, j int) bool

func (Refs) Swap 

func (vs Refs) Swap(i, j int)

type RepositoryListingDef added in v0.0.9 

type RepositoryListingDef struct {
	// Name is the full name shown on the page.
	Name string

	// NameLabel is a label displayed next to the Name, such as "(main package)"
	// to denote that a package is a Go main package.
	NameLabel string

	// Language is the source language of the def, with any additional
	// specifiers, such as "JavaScript (node.js)".
	Language string

	// SortKey is the key used to lexicographically sort all of the defs on
	// the page.
	SortKey string
}

RepositoryListingDef holds rendered display text to show on the "package" listing page of a repository.

type StatType 

type StatType string

StatType is the name of a def statistic (see below for a listing).

func (StatType) IsAbstract 

func (x StatType) IsAbstract() bool

type Stats 

type Stats map[StatType]int

Stats holds statistics for a def.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.