luci: Index | Files

package symbols

import ""

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.


Package Files

loader.go symbols.go

type BrokenSymbol Uses

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.

func (*BrokenSymbol) Def Uses

func (s *BrokenSymbol) Def() ast.Node

func (*BrokenSymbol) Doc Uses

func (s *BrokenSymbol) Doc() *docstring.Parsed

func (*BrokenSymbol) Name Uses

func (s *BrokenSymbol) Name() string

type Loader Uses

type Loader struct {
    // 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 Starlark code, for example:

def _func():
  """Doc string."""
exported = struct(func = _func, const = 123)

It will produce the following symbol tree:

Struct('', *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.

func (*Loader) Load Uses

func (l *Loader) Load(module string) (syms *Struct, err error)

Loads loads the module and all modules it references, populating the loader's state with information about exported symbols.

Returns a struct with a list of symbols defined in the module.

Can be called multiple times with different modules.

type Struct Uses

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.

func (*Struct) Def Uses

func (s *Struct) Def() ast.Node

func (*Struct) Doc Uses

func (s *Struct) Doc() *docstring.Parsed

func (*Struct) Name Uses

func (s *Struct) Name() string

func (*Struct) Symbols Uses

func (s *Struct) Symbols() []Symbol

Symbols returns all symbols in the struct.

The caller must not modify the returned slice.

type Symbol Uses

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.

func Lookup Uses

func Lookup(ns Symbol, path ...string) Symbol

Lookup essentially does "ns.p0.p1.p2" operation.

Returns a broken symbol if this lookup is not possible, e.g. some field path element is not a struct or doesn't exist at all.

type Term Uses

type Term struct {
    // contains filtered or unexported fields

Term is a symbol that represents some single terminal definition, not a struct.

func (*Term) Def Uses

func (s *Term) Def() ast.Node

func (*Term) Doc Uses

func (s *Term) Doc() *docstring.Parsed

func (*Term) Name Uses

func (s *Term) Name() string

Package symbols imports 5 packages (graph) and is imported by 2 packages. Updated 2019-02-24. Refresh now. Tools for package owners.