luci: go.chromium.org/luci/lucicfg/docgen/symbols Index | Files

package symbols

import "go.chromium.org/luci/lucicfg/docgen/symbols"

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

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

func (*BrokenSymbol) String Uses

func (s *BrokenSymbol) String() string

type Invocation Uses

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 Uses

func (inv *Invocation) Args() []Symbol

Args is keyword arguments passed to the function.

func (*Invocation) Def Uses

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

func (*Invocation) Doc Uses

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

func (*Invocation) Func Uses

func (inv *Invocation) Func() Symbol

Func is a symbol that represents the function being invoked.

func (*Invocation) Name Uses

func (s *Invocation) Name() string

func (*Invocation) String Uses

func (s *Invocation) String() 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 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.

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) String Uses

func (s *Struct) String() 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.

func (*Struct) Transform Uses

func (s *Struct) Transform(tr func(Symbol) (Symbol, error)) (*Struct, error)

Transform returns a new struct made by applying a transformation to the receiver struct, recursively.

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.

func NewAlias Uses

func NewAlias(name string, symbol Symbol) Symbol

NewAlias handles definitions like "a = <symbol>".

It returns a new symbol of the same type as the RHS and new name ('a'). It points to the same definition the symbol on the RHS points to.

type Term Uses

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

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

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

func (*Term) String Uses

func (s *Term) String() string

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