Documentation
¶
Overview ¶
Package symbols defines a data model representing Starlark symbols.
A symbol is a like a variable: it has a name and points to some object somewhere. This package allows to load symbols defined in a starlark module, following references. For example, if "a = b", then symbol 'a' points to the same object as symbol 'b'.
The loader understands how to follow references across module boundaries and struct()s.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BrokenSymbol ¶
type BrokenSymbol struct {
// contains filtered or unexported fields
}
BrokenSymbol is a symbol that refers to something we can't resolve.
For example, if "b" is undefined in "a = b", then "a" becomes BrokenSymbol.
type Invocation ¶
type Invocation struct {
// contains filtered or unexported fields
}
Invocation is a symbol assigned a return value of some function call.
The name of the function, as well as value of all keyword arguments, are represented by symbols too.
func (*Invocation) Args ¶
func (inv *Invocation) Args() []Symbol
Args is keyword arguments passed to the function.
func (*Invocation) Func ¶
func (inv *Invocation) Func() Symbol
Func is a symbol that represents the function being invoked.
type Loader ¶
type Loader struct {
// Normalize normalizes a load() statement relative to the parent.
Normalize func(parent, module string) (string, error)
// Source loads module's source code.
Source func(module string) (src string, err error)
// contains filtered or unexported fields
}
Loader knows how to load symbols from a starlark file, following references to other file it may load (recursively).
As a result it builds a symbol tree. Intermediate nodes in this tree are struct-like definitions (which define namespaces), and leafs hold pointers to ast.Nodes with concrete definitions of these symbols (after following all possible aliases).
Consider this module.star Starlark code, for example:
def _func(): """Doc string.""" exported = struct(func = _func, const = 123)
It will produce the following symbol tree:
Struct('module.star', *ast.Module, [
Term('_func', *ast.Function _func),
Struct('exported', *ast.Namespace exported, [
Term('func', *ast.Function _func),
Term('const', *ast.Var const),
]),
])
Notice that both '_func' and 'exported.func' point to exact same AST node where the function was actually defined.
This allows to collect the documentation for all exported symbols even if they are gathered from many internal modules via load(...) statements, assignments and structs.
type Struct ¶
type Struct struct {
// contains filtered or unexported fields
}
Struct is a symbol that represents a struct (or equivalent) that has more symbols inside it.
Basically, a struct symbol is something that supports "." operation to "look" inside it.
type Symbol ¶
type Symbol interface {
// Name is a name of this symbol within its parent namespace.
//
// E.g. this is just "a", not "parent.a".
Name() string
// Def is an AST node where the object this symbol points to was defined.
//
// Nil for broken symbols.
Def() ast.Node
// Doc is a parsed docstring for this symbol.
Doc() *docstring.Parsed
}
Symbol is something defined in a Starlark module.
It has a name and it points to some declaration.
Source Files