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.

      func (*BrokenSymbol) Def

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

      func (*BrokenSymbol) Doc

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

      func (*BrokenSymbol) Name

      func (s *BrokenSymbol) Name() string

      func (*BrokenSymbol) String

      func (s *BrokenSymbol) String() string

      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) Def

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

          func (*Invocation) Doc

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

          func (*Invocation) Func

          func (inv *Invocation) Func() Symbol

            Func is a symbol that represents the function being invoked.

            func (*Invocation) Name

            func (s *Invocation) Name() string

            func (*Invocation) String

            func (s *Invocation) String() string

            type Loader

            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

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

                Load 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

                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

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

                  func (*Struct) Doc

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

                  func (*Struct) Name

                  func (s *Struct) Name() string

                  func (*Struct) String

                  func (s *Struct) String() string

                  func (*Struct) Symbols

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

                    Symbols returns all symbols in the struct.

                    The caller must not modify the returned slice.

                    func (*Struct) Transform

                    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

                      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

                        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

                          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

                            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

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

                              func (*Term) Doc

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

                              func (*Term) Name

                              func (s *Term) Name() string

                              func (*Term) String

                              func (s *Term) String() string