symbols

package
v0.0.0-...-d3da680 Latest Latest
Warning

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

Go to latest
Published: Dec 4, 2024 License: Apache-2.0 Imports: 5 Imported by: 0

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 {
	// 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.

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.

The module string must be normalized.

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL