go.starlark.net: go.starlark.net/starlark Index | Examples | Files

package starlark

import "go.starlark.net/starlark"

Package starlark provides a Starlark interpreter.

Starlark values are represented by the Value interface. The following built-in Value types are known to the evaluator:

NoneType        -- NoneType
Bool            -- bool
Int             -- int
Float           -- float
String          -- string
*List           -- list
Tuple           -- tuple
*Dict           -- dict
*Set            -- set
*Function       -- function (implemented in Starlark)
*Builtin        -- builtin_function_or_method (function or method implemented in Go)

Client applications may define new data types that satisfy at least the Value interface. Such types may provide additional operations by implementing any of these optional interfaces:

Callable        -- value is callable like a function
Comparable      -- value defines its own comparison operations
Iterable        -- value is iterable using 'for' loops
Sequence        -- value is iterable sequence of known length
Indexable       -- value is sequence with efficient random access
Mapping         -- value maps from keys to values, like a dictionary
HasBinary       -- value defines binary operations such as * and +
HasAttrs        -- value has readable fields or methods x.f
HasSetField     -- value has settable fields x.f
HasSetIndex     -- value supports element update using x[i]=y
HasSetKey       -- value supports map update using x[k]=v
HasUnary        -- value defines unary operations such as + and -

Client applications may also define domain-specific functions in Go and make them available to Starlark programs. Use NewBuiltin to construct a built-in value that wraps a Go function. The implementation of the Go function may use UnpackArgs to make sense of the positional and keyword arguments provided by the caller.

Starlark's None value is not equal to Go's nil, but nil may be assigned to a Starlark Value. Be careful to avoid allowing Go nil values to leak into Starlark data structures.

The Compare operation requires two arguments of the same type, but this constraint cannot be expressed in Go's type system. (This is the classic "binary method problem".) So, each Value type's CompareSameType method is a partial function that compares a value only against others of the same type. Use the package's standalone Compare (or Equal) function to compare an arbitrary pair of values.

To parse and evaluate a Starlark source file, use ExecFile. The Eval function evaluates a single expression. All evaluator functions require a Thread parameter which defines the "thread-local storage" of a Starlark thread and may be used to plumb application state through Sklyark code and into callbacks. When evaluation fails it returns an EvalError from which the application may obtain a backtrace of active Starlark calls.

Index

Examples

Package Files

debug.go eval.go hashtable.go int.go interp.go library.go profile.go value.go

Constants

const CompilerVersion = compile.Version

CompilerVersion is the version number of the protocol for compiled files. Applications must not run programs compiled by one version with an interpreter at another version, and should thus incorporate the compiler version into the cache key when reusing compiled code.

const None = NoneType(0)

func AsFloat Uses

func AsFloat(x Value) (f float64, ok bool)

AsFloat returns the float64 value closest to x. The f result is undefined if x is not a float or int.

func AsInt32 Uses

func AsInt32(x Value) (int, error)

AsInt32 returns the value of x if is representable as an int32.

func AsString Uses

func AsString(x Value) (string, bool)

func Compare Uses

func Compare(op syntax.Token, x, y Value) (bool, error)

Compare compares two Starlark values. The comparison operation must be one of EQL, NEQ, LT, LE, GT, or GE. Compare returns an error if an ordered comparison was requested for a type that does not support it.

Recursive comparisons by implementations of Value.CompareSameType should use CompareDepth to prevent infinite recursion.

func CompareDepth Uses

func CompareDepth(op syntax.Token, x, y Value, depth int) (bool, error)

CompareDepth compares two Starlark values. The comparison operation must be one of EQL, NEQ, LT, LE, GT, or GE. CompareDepth returns an error if an ordered comparison was requested for a pair of values that do not support it.

The depth parameter limits the maximum depth of recursion in cyclic data structures.

func Equal Uses

func Equal(x, y Value) (bool, error)

Equal reports whether two Starlark values are equal.

func EqualDepth Uses

func EqualDepth(x, y Value, depth int) (bool, error)

EqualDepth reports whether two Starlark values are equal.

Recursive comparisons by implementations of Value.CompareSameType should use EqualDepth to prevent infinite recursion.

func Len Uses

func Len(x Value) int

Len returns the length of a string or sequence value, and -1 for all others.

Warning: Len(x) >= 0 does not imply Iterate(x) != nil. A string has a known length but is not directly iterable.

func StartProfile Uses

func StartProfile(w io.Writer) error

StartProfile enables time profiling of all Starlark threads, and writes a profile in pprof format to w. It must be followed by a call to StopProfiler to stop the profiler and finalize the profile.

StartProfile returns an error if profiling was already enabled.

StartProfile must not be called concurrently with Starlark execution.

func StopProfile Uses

func StopProfile() error

StopProfiler stops the profiler started by a prior call to StartProfile and finalizes the profile. It returns an error if the profile could not be completed.

StopProfiler must not be called concurrently with Starlark execution.

func UnpackArgs Uses

func UnpackArgs(fnname string, args Tuple, kwargs []Tuple, pairs ...interface{}) error

UnpackArgs unpacks the positional and keyword arguments into the supplied parameter variables. pairs is an alternating list of names and pointers to variables.

If the variable is a bool, int, string, *List, *Dict, Callable, Iterable, or user-defined implementation of Value, UnpackArgs performs the appropriate type check. An int uses the AsInt32 check. If the parameter name ends with "?", it and all following parameters are optional.

If the variable implements Value, UnpackArgs may call its Type() method while constructing the error message.

Beware: an optional *List, *Dict, Callable, Iterable, or Value variable that is not assigned is not a valid Starlark Value, so the caller must explicitly handle such cases by interpreting nil as None or some computed default.

func UnpackPositionalArgs Uses

func UnpackPositionalArgs(fnname string, args Tuple, kwargs []Tuple, min int, vars ...interface{}) error

UnpackPositionalArgs unpacks the positional arguments into corresponding variables. Each element of vars is a pointer; see UnpackArgs for allowed types and conversions.

UnpackPositionalArgs reports an error if the number of arguments is less than min or greater than len(vars), if kwargs is nonempty, or if any conversion fails.

type Bool Uses

type Bool bool

Bool is the type of a Starlark bool.

const (
    False Bool = false
    True  Bool = true
)

func (Bool) CompareSameType Uses

func (x Bool) CompareSameType(op syntax.Token, y_ Value, depth int) (bool, error)

func (Bool) Freeze Uses

func (b Bool) Freeze()

func (Bool) Hash Uses

func (b Bool) Hash() (uint32, error)

func (Bool) String Uses

func (b Bool) String() string

func (Bool) Truth Uses

func (b Bool) Truth() Bool

func (Bool) Type Uses

func (b Bool) Type() string

type Builtin Uses

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

A Builtin is a function implemented in Go.

func NewBuiltin Uses

func NewBuiltin(name string, fn func(thread *Thread, fn *Builtin, args Tuple, kwargs []Tuple) (Value, error)) *Builtin

NewBuiltin returns a new 'builtin_function_or_method' value with the specified name and implementation. It compares unequal with all other values.

func (*Builtin) BindReceiver Uses

func (b *Builtin) BindReceiver(recv Value) *Builtin

BindReceiver returns a new Builtin value representing a method closure, that is, a built-in function bound to a receiver value.

In the example below, the value of f is the string.index built-in method bound to the receiver value "abc":

f = "abc".index; f("a"); f("b")

In the common case, the receiver is bound only during the call, but this still results in the creation of a temporary method closure:

"abc".index("a")

func (*Builtin) CallInternal Uses

func (b *Builtin) CallInternal(thread *Thread, args Tuple, kwargs []Tuple) (Value, error)

func (*Builtin) Freeze Uses

func (b *Builtin) Freeze()

func (*Builtin) Hash Uses

func (b *Builtin) Hash() (uint32, error)

func (*Builtin) Name Uses

func (b *Builtin) Name() string

func (*Builtin) Receiver Uses

func (b *Builtin) Receiver() Value

func (*Builtin) String Uses

func (b *Builtin) String() string

func (*Builtin) Truth Uses

func (b *Builtin) Truth() Bool

func (*Builtin) Type Uses

func (b *Builtin) Type() string

type CallFrame Uses

type CallFrame struct {
    Name string
    Pos  syntax.Position
}

A CallFrame represents the function name and current position of execution of an enclosing call frame.

type CallStack Uses

type CallStack []CallFrame

A CallStack is a stack of call frames, outermost first.

func (CallStack) At Uses

func (stack CallStack) At(i int) CallFrame

At returns a copy of the frame at depth i. At(0) returns the topmost frame.

func (*CallStack) Pop Uses

func (stack *CallStack) Pop() CallFrame

Pop removes and returns the topmost frame.

func (CallStack) String Uses

func (stack CallStack) String() string

String returns a user-friendly description of the stack.

type Callable Uses

type Callable interface {
    Value
    Name() string
    CallInternal(thread *Thread, args Tuple, kwargs []Tuple) (Value, error)
}

A Callable value f may be the operand of a function call, f(x).

Clients should use the Call function, never the CallInternal method.

type Comparable Uses

type Comparable interface {
    Value
    // CompareSameType compares one value to another of the same Type().
    // The comparison operation must be one of EQL, NEQ, LT, LE, GT, or GE.
    // CompareSameType returns an error if an ordered comparison was
    // requested for a type that does not support it.
    //
    // Implementations that recursively compare subcomponents of
    // the value should use the CompareDepth function, not Compare, to
    // avoid infinite recursion on cyclic structures.
    //
    // The depth parameter is used to bound comparisons of cyclic
    // data structures.  Implementations should decrement depth
    // before calling CompareDepth and should return an error if depth
    // < 1.
    //
    // Client code should not call this method.  Instead, use the
    // standalone Compare or Equals functions, which are defined for
    // all pairs of operands.
    CompareSameType(op syntax.Token, y Value, depth int) (bool, error)
}

A Comparable is a value that defines its own equivalence relation and perhaps ordered comparisons.

type DebugFrame Uses

type DebugFrame interface {
    Callable() Callable        // returns the frame's function
    Local(i int) Value         // returns the value of the (Starlark) frame's ith local variable
    Position() syntax.Position // returns the current position of execution in this frame
}

DebugFrame is the debugger API for a frame of the interpreter's call stack.

Most applications have no need for this API; use CallFrame instead.

Clients must not retain a DebugFrame nor call any of its methods once the current built-in call has returned or execution has resumed after a breakpoint as this may have unpredictable effects, including but not limited to retention of object that would otherwise be garbage.

type Dict Uses

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

A *Dict represents a Starlark dictionary. The zero value of Dict is a valid empty dictionary. If you know the exact final number of entries, it is more efficient to call NewDict.

func NewDict Uses

func NewDict(size int) *Dict

NewDict returns a set with initial space for at least size insertions before rehashing.

func (*Dict) Attr Uses

func (d *Dict) Attr(name string) (Value, error)

func (*Dict) AttrNames Uses

func (d *Dict) AttrNames() []string

func (*Dict) Clear Uses

func (d *Dict) Clear() error

func (*Dict) CompareSameType Uses

func (x *Dict) CompareSameType(op syntax.Token, y_ Value, depth int) (bool, error)

func (*Dict) Delete Uses

func (d *Dict) Delete(k Value) (v Value, found bool, err error)

func (*Dict) Freeze Uses

func (d *Dict) Freeze()

func (*Dict) Get Uses

func (d *Dict) Get(k Value) (v Value, found bool, err error)

func (*Dict) Hash Uses

func (d *Dict) Hash() (uint32, error)

func (*Dict) Items Uses

func (d *Dict) Items() []Tuple

func (*Dict) Iterate Uses

func (d *Dict) Iterate() Iterator

func (*Dict) Keys Uses

func (d *Dict) Keys() []Value

func (*Dict) Len Uses

func (d *Dict) Len() int

func (*Dict) SetKey Uses

func (d *Dict) SetKey(k, v Value) error

func (*Dict) String Uses

func (d *Dict) String() string

func (*Dict) Truth Uses

func (d *Dict) Truth() Bool

func (*Dict) Type Uses

func (d *Dict) Type() string

type EvalError Uses

type EvalError struct {
    Msg       string
    CallStack CallStack
}

An EvalError is a Starlark evaluation error and a copy of the thread's stack at the moment of the error.

func (*EvalError) Backtrace Uses

func (e *EvalError) Backtrace() string

Backtrace returns a user-friendly error message describing the stack of calls that led to this error.

func (*EvalError) Error Uses

func (e *EvalError) Error() string

type Float Uses

type Float float64

Float is the type of a Starlark float.

func (Float) CompareSameType Uses

func (x Float) CompareSameType(op syntax.Token, y_ Value, depth int) (bool, error)

func (Float) Freeze Uses

func (f Float) Freeze()

func (Float) Hash Uses

func (f Float) Hash() (uint32, error)

func (Float) Mod Uses

func (x Float) Mod(y Float) Float

func (Float) String Uses

func (f Float) String() string

func (Float) Truth Uses

func (f Float) Truth() Bool

func (Float) Type Uses

func (f Float) Type() string

func (Float) Unary Uses

func (f Float) Unary(op syntax.Token) (Value, error)

Unary implements the operations +float and -float.

type Function Uses

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

A Function is a function defined by a Starlark def statement or lambda expression. The initialization behavior of a Starlark module is also represented by a Function.

func ExprFunc Uses

func ExprFunc(filename string, src interface{}, env StringDict) (*Function, error)

ExprFunc returns a no-argument function that evaluates the expression whose source is src.

func (*Function) CallInternal Uses

func (fn *Function) CallInternal(thread *Thread, args Tuple, kwargs []Tuple) (Value, error)

func (*Function) Doc Uses

func (fn *Function) Doc() string

func (*Function) Freeze Uses

func (fn *Function) Freeze()

func (*Function) Globals Uses

func (fn *Function) Globals() StringDict

Globals returns a new, unfrozen StringDict containing all global variables so far defined in the function's module.

func (*Function) HasKwargs Uses

func (fn *Function) HasKwargs() bool

func (*Function) HasVarargs Uses

func (fn *Function) HasVarargs() bool

func (*Function) Hash Uses

func (fn *Function) Hash() (uint32, error)

func (*Function) Name Uses

func (fn *Function) Name() string

func (*Function) NumKwonlyParams Uses

func (fn *Function) NumKwonlyParams() int

func (*Function) NumParams Uses

func (fn *Function) NumParams() int

func (*Function) Param Uses

func (fn *Function) Param(i int) (string, syntax.Position)

Param returns the name and position of the ith parameter, where 0 <= i < NumParams(). The *args and **kwargs parameters are at the end even if there were optional parameters after *args.

func (*Function) Position Uses

func (fn *Function) Position() syntax.Position

func (*Function) String Uses

func (fn *Function) String() string

func (*Function) Truth Uses

func (fn *Function) Truth() Bool

func (*Function) Type Uses

func (fn *Function) Type() string

type HasAttrs Uses

type HasAttrs interface {
    Value
    Attr(name string) (Value, error) // returns (nil, nil) if attribute not present
    AttrNames() []string             // callers must not modify the result.
}

A HasAttrs value has fields or methods that may be read by a dot expression (y = x.f). Attribute names may be listed using the built-in 'dir' function.

For implementation convenience, a result of (nil, nil) from Attr is interpreted as a "no such field or method" error. Implementations are free to return a more precise error.

type HasBinary Uses

type HasBinary interface {
    Value
    Binary(op syntax.Token, y Value, side Side) (Value, error)
}

A HasBinary value may be used as either operand of these binary operators:

+   -   *   /   //   %   in   not in   |   &   ^   <<   >>

The Side argument indicates whether the receiver is the left or right operand.

An implementation may decline to handle an operation by returning (nil, nil). For this reason, clients should always call the standalone Binary(op, x, y) function rather than calling the method directly.

type HasSetField Uses

type HasSetField interface {
    HasAttrs
    SetField(name string, val Value) error
}

A HasSetField value has fields that may be written by a dot expression (x.f = y).

An implementation of SetField may return a NoSuchAttrError, in which case the runtime may augment the error message to warn of possible misspelling.

type HasSetIndex Uses

type HasSetIndex interface {
    Indexable
    SetIndex(index int, v Value) error
}

A HasSetIndex is an Indexable value whose elements may be assigned (x[i] = y).

The implementation should not add Len to a negative index as the evaluator does this before the call.

type HasSetKey Uses

type HasSetKey interface {
    Mapping
    SetKey(k, v Value) error
}

A HasSetKey supports map update using x[k]=v syntax, like a dictionary.

type HasUnary Uses

type HasUnary interface {
    Value
    Unary(op syntax.Token) (Value, error)
}

A HasUnary value may be used as the operand of these unary operators:

+   -   ~

An implementation may decline to handle an operation by returning (nil, nil). For this reason, clients should always call the standalone Unary(op, x) function rather than calling the method directly.

type Indexable Uses

type Indexable interface {
    Value
    Index(i int) Value // requires 0 <= i < Len()
    Len() int
}

An Indexable is a sequence of known length that supports efficient random access. It is not necessarily iterable.

type Int Uses

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

Int is the type of a Starlark int.

func MakeBigInt Uses

func MakeBigInt(x *big.Int) Int

MakeBigInt returns a Starlark int for the specified big.Int. The caller must not subsequently modify x.

func MakeInt Uses

func MakeInt(x int) Int

MakeInt returns a Starlark int for the specified signed integer.

func MakeInt64 Uses

func MakeInt64(x int64) Int

MakeInt64 returns a Starlark int for the specified int64.

func MakeUint Uses

func MakeUint(x uint) Int

MakeUint returns a Starlark int for the specified unsigned integer.

func MakeUint64 Uses

func MakeUint64(x uint64) Int

MakeUint64 returns a Starlark int for the specified uint64.

func NumberToInt Uses

func NumberToInt(x Value) (Int, error)

NumberToInt converts a number x to an integer value. An int is returned unchanged, a float is truncated towards zero. NumberToInt reports an error for all other values.

func (Int) Add Uses

func (x Int) Add(y Int) Int

func (Int) And Uses

func (x Int) And(y Int) Int

func (Int) BigInt Uses

func (i Int) BigInt() *big.Int

BigInt returns the value as a big.Int. The returned variable must not be modified by the client.

func (Int) CompareSameType Uses

func (x Int) CompareSameType(op syntax.Token, v Value, depth int) (bool, error)

func (Int) Div Uses

func (x Int) Div(y Int) Int

Precondition: y is nonzero.

func (Int) Float Uses

func (i Int) Float() Float

Float returns the float value nearest i.

func (Int) Format Uses

func (i Int) Format(s fmt.State, ch rune)

func (Int) Freeze Uses

func (i Int) Freeze()

func (Int) Hash Uses

func (i Int) Hash() (uint32, error)

func (Int) Int64 Uses

func (i Int) Int64() (_ int64, ok bool)

Int64 returns the value as an int64. If it is not exactly representable the result is undefined and ok is false.

func (Int) Lsh Uses

func (x Int) Lsh(y uint) Int

func (Int) Mod Uses

func (x Int) Mod(y Int) Int

Precondition: y is nonzero.

func (Int) Mul Uses

func (x Int) Mul(y Int) Int

func (Int) Not Uses

func (x Int) Not() Int

func (Int) Or Uses

func (x Int) Or(y Int) Int

func (Int) Rsh Uses

func (x Int) Rsh(y uint) Int

func (Int) Sign Uses

func (x Int) Sign() int

func (Int) String Uses

func (i Int) String() string

func (Int) Sub Uses

func (x Int) Sub(y Int) Int

func (Int) Truth Uses

func (i Int) Truth() Bool

func (Int) Type Uses

func (i Int) Type() string

func (Int) Uint64 Uses

func (i Int) Uint64() (_ uint64, ok bool)

Uint64 returns the value as a uint64. If it is not exactly representable the result is undefined and ok is false.

func (Int) Unary Uses

func (i Int) Unary(op syntax.Token) (Value, error)

Unary implements the operations +int, -int, and ~int.

func (Int) Xor Uses

func (x Int) Xor(y Int) Int

type Iterable Uses

type Iterable interface {
    Value
    Iterate() Iterator // must be followed by call to Iterator.Done
}

An Iterable abstracts a sequence of values. An iterable value may be iterated over by a 'for' loop or used where any other Starlark iterable is allowed. Unlike a Sequence, the length of an Iterable is not necessarily known in advance of iteration.

type IterableMapping Uses

type IterableMapping interface {
    Mapping
    Iterate() Iterator // see Iterable interface
    Items() []Tuple    // a new slice containing all key/value pairs
}

An IterableMapping is a mapping that supports key enumeration.

type Iterator Uses

type Iterator interface {
    // If the iterator is exhausted, Next returns false.
    // Otherwise it sets *p to the current element of the sequence,
    // advances the iterator, and returns true.
    Next(p *Value) bool
    Done()
}

An Iterator provides a sequence of values to the caller.

The caller must call Done when the iterator is no longer needed. Operations that modify a sequence will fail if it has active iterators.

Example usage:

iter := iterable.Iterator()
defer iter.Done()
var x Value
for iter.Next(&x) {
	...
}

func Iterate Uses

func Iterate(x Value) Iterator

Iterate return a new iterator for the value if iterable, nil otherwise. If the result is non-nil, the caller must call Done when finished with it.

Warning: Iterate(x) != nil does not imply Len(x) >= 0. Some iterables may have unknown length.

type List Uses

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

A *List represents a Starlark list value.

func NewList Uses

func NewList(elems []Value) *List

NewList returns a list containing the specified elements. Callers should not subsequently modify elems.

func (*List) Append Uses

func (l *List) Append(v Value) error

func (*List) Attr Uses

func (l *List) Attr(name string) (Value, error)

func (*List) AttrNames Uses

func (l *List) AttrNames() []string

func (*List) Clear Uses

func (l *List) Clear() error

func (*List) CompareSameType Uses

func (x *List) CompareSameType(op syntax.Token, y_ Value, depth int) (bool, error)

func (*List) Freeze Uses

func (l *List) Freeze()

func (*List) Hash Uses

func (l *List) Hash() (uint32, error)

func (*List) Index Uses

func (l *List) Index(i int) Value

func (*List) Iterate Uses

func (l *List) Iterate() Iterator

func (*List) Len Uses

func (l *List) Len() int

func (*List) SetIndex Uses

func (l *List) SetIndex(i int, v Value) error

func (*List) Slice Uses

func (l *List) Slice(start, end, step int) Value

func (*List) String Uses

func (l *List) String() string

func (*List) Truth Uses

func (l *List) Truth() Bool

func (*List) Type Uses

func (l *List) Type() string

type Mapping Uses

type Mapping interface {
    Value
    // Get returns the value corresponding to the specified key,
    // or !found if the mapping does not contain the key.
    //
    // Get also defines the behavior of "v in mapping".
    // The 'in' operator reports the 'found' component, ignoring errors.
    Get(Value) (v Value, found bool, err error)
}

A Mapping is a mapping from keys to values, such as a dictionary.

If a type satisfies both Mapping and Iterable, the iterator yields the keys of the mapping.

type NoSuchAttrError Uses

type NoSuchAttrError string

A NoSuchAttrError may be returned by an implementation of HasAttrs.Attr or HasSetField.SetField to indicate that no such field exists. In that case the runtime may augment the error message to warn of possible misspelling.

func (NoSuchAttrError) Error Uses

func (e NoSuchAttrError) Error() string

type NoneType Uses

type NoneType byte

NoneType is the type of None. Its only legal value is None. (We represent it as a number, not struct{}, so that None may be constant.)

func (NoneType) CompareSameType Uses

func (NoneType) CompareSameType(op syntax.Token, y Value, depth int) (bool, error)

func (NoneType) Freeze Uses

func (NoneType) Freeze()

func (NoneType) Hash Uses

func (NoneType) Hash() (uint32, error)

func (NoneType) String Uses

func (NoneType) String() string

func (NoneType) Truth Uses

func (NoneType) Truth() Bool

func (NoneType) Type Uses

func (NoneType) Type() string

type Program Uses

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

A Program is a compiled Starlark program.

Programs are immutable, and contain no Values. A Program may be created by parsing a source file (see SourceProgram) or by loading a previously saved compiled program (see CompiledProgram).

func CompiledProgram Uses

func CompiledProgram(in io.Reader) (*Program, error)

CompiledProgram produces a new program from the representation of a compiled program previously saved by Program.Write.

func FileProgram Uses

func FileProgram(f *syntax.File, isPredeclared func(string) bool) (*Program, error)

FileProgram produces a new program by resolving, and compiling the Starlark source file syntax tree. On success, it returns the compiled program.

Resolving a syntax tree mutates it. Do not call FileProgram more than once on the same file.

The isPredeclared predicate reports whether a name is a pre-declared identifier of the current module. Its typical value is predeclared.Has, where predeclared is a StringDict of pre-declared values.

func SourceProgram Uses

func SourceProgram(filename string, src interface{}, isPredeclared func(string) bool) (*syntax.File, *Program, error)

SourceProgram produces a new program by parsing, resolving, and compiling a Starlark source file. On success, it returns the parsed file and the compiled program. The filename and src parameters are as for syntax.Parse.

The isPredeclared predicate reports whether a name is a pre-declared identifier of the current module. Its typical value is predeclared.Has, where predeclared is a StringDict of pre-declared values.

func (*Program) Filename Uses

func (prog *Program) Filename() string

Filename returns the name of the file from which this program was loaded.

func (*Program) Init Uses

func (prog *Program) Init(thread *Thread, predeclared StringDict) (StringDict, error)

Init creates a set of global variables for the program, executes the toplevel code of the specified program, and returns a new, unfrozen dictionary of the globals.

func (*Program) Load Uses

func (prog *Program) Load(i int) (string, syntax.Position)

Load(i) returns the name and position of the i'th module directly loaded by this one, where 0 <= i < NumLoads(). The name is unresolved---exactly as it appears in the source.

func (*Program) NumLoads Uses

func (prog *Program) NumLoads() int

NumLoads returns the number of load statements in the compiled program.

func (*Program) String Uses

func (prog *Program) String() string

func (*Program) Write Uses

func (prog *Program) Write(out io.Writer) error

WriteTo writes the compiled module to the specified output stream.

type Sequence Uses

type Sequence interface {
    Iterable
    Len() int
}

A Sequence is a sequence of values of known length.

type Set Uses

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

A Set represents a Starlark set value. The zero value of Set is a valid empty set. If you know the exact final number of elements, it is more efficient to call NewSet.

func NewSet Uses

func NewSet(size int) *Set

NewSet returns a dictionary with initial space for at least size insertions before rehashing.

func (*Set) Attr Uses

func (s *Set) Attr(name string) (Value, error)

func (*Set) AttrNames Uses

func (s *Set) AttrNames() []string

func (*Set) Clear Uses

func (s *Set) Clear() error

func (*Set) CompareSameType Uses

func (x *Set) CompareSameType(op syntax.Token, y_ Value, depth int) (bool, error)

func (*Set) Delete Uses

func (s *Set) Delete(k Value) (found bool, err error)

func (*Set) Freeze Uses

func (s *Set) Freeze()

func (*Set) Has Uses

func (s *Set) Has(k Value) (found bool, err error)

func (*Set) Hash Uses

func (s *Set) Hash() (uint32, error)

func (*Set) Insert Uses

func (s *Set) Insert(k Value) error

func (*Set) Iterate Uses

func (s *Set) Iterate() Iterator

func (*Set) Len Uses

func (s *Set) Len() int

func (*Set) String Uses

func (s *Set) String() string

func (*Set) Truth Uses

func (s *Set) Truth() Bool

func (*Set) Type Uses

func (s *Set) Type() string

func (*Set) Union Uses

func (s *Set) Union(iter Iterator) (Value, error)

type Side Uses

type Side bool
const (
    Left  Side = false
    Right Side = true
)

type Sliceable Uses

type Sliceable interface {
    Indexable
    // For positive strides (step > 0), 0 <= start <= end <= n.
    // For negative strides (step < 0), -1 <= end <= start < n.
    // The caller must ensure that the start and end indices are valid
    // and that step is non-zero.
    Slice(start, end, step int) Value
}

A Sliceable is a sequence that can be cut into pieces with the slice operator (x[i:j:step]).

All native indexable objects are sliceable. This is a separate interface for backwards-compatibility.

type String Uses

type String string

String is the type of a Starlark string.

A String encapsulates an an immutable sequence of bytes, but strings are not directly iterable. Instead, iterate over the result of calling one of these four methods: codepoints, codepoint_ords, elems, elem_ords.

Warning: the contract of the Value interface's String method is that it returns the value printed in Starlark notation, so s.String() or fmt.Sprintf("%s", s) returns a quoted string. Use string(s) or s.GoString() or fmt.Sprintf("%#v", s) to obtain the raw contents of a Starlark string as a Go string.

func (String) Attr Uses

func (s String) Attr(name string) (Value, error)

func (String) AttrNames Uses

func (s String) AttrNames() []string

func (String) CompareSameType Uses

func (x String) CompareSameType(op syntax.Token, y_ Value, depth int) (bool, error)

func (String) Freeze Uses

func (s String) Freeze()

func (String) GoString Uses

func (s String) GoString() string

func (String) Hash Uses

func (s String) Hash() (uint32, error)

func (String) Index Uses

func (s String) Index(i int) Value

func (String) Len Uses

func (s String) Len() int

func (String) Slice Uses

func (s String) Slice(start, end, step int) Value

func (String) String Uses

func (s String) String() string

func (String) Truth Uses

func (s String) Truth() Bool

func (String) Type Uses

func (s String) Type() string

type StringDict Uses

type StringDict map[string]Value

A StringDict is a mapping from names to values, and represents an environment such as the global variables of a module. It is not a true starlark.Value.

var Universe StringDict

Universe defines the set of universal built-ins, such as None, True, and len.

The Go application may add or remove items from the universe dictionary before Starlark evaluation begins. All values in the dictionary must be immutable. Starlark programs cannot modify the dictionary.

func ExecFile Uses

func ExecFile(thread *Thread, filename string, src interface{}, predeclared StringDict) (StringDict, error)

ExecFile parses, resolves, and executes a Starlark file in the specified global environment, which may be modified during execution.

Thread is the state associated with the Starlark thread.

The filename and src parameters are as for syntax.Parse: filename is the name of the file to execute, and the name that appears in error messages; src is an optional source of bytes to use instead of filename.

predeclared defines the predeclared names specific to this module. Execution does not modify this dictionary, though it may mutate its values.

If ExecFile fails during evaluation, it returns an *EvalError containing a backtrace.

ExampleExecFile demonstrates a simple embedding of the Starlark interpreter into a Go program.

Code:

const data = `
print(greeting + ", world")

squares = [x*x for x in range(10)]
`

thread := &starlark.Thread{
    Name:  "example",
    Print: func(_ *starlark.Thread, msg string) { fmt.Println(msg) },
}
predeclared := starlark.StringDict{
    "greeting": starlark.String("hello"),
}
globals, err := starlark.ExecFile(thread, "apparent/filename.star", data, predeclared)
if err != nil {
    if evalErr, ok := err.(*starlark.EvalError); ok {
        log.Fatal(evalErr.Backtrace())
    }
    log.Fatal(err)
}

// Print the global environment.
fmt.Println("\nGlobals:")
for _, name := range globals.Keys() {
    v := globals[name]
    fmt.Printf("%s (%s) = %s\n", name, v.Type(), v.String())
}

Output:

hello, world

Globals:
squares (list) = [0, 1, 4, 9, 16, 25, 36, 49, 64, 81]

func (StringDict) Freeze Uses

func (d StringDict) Freeze()

func (StringDict) Has Uses

func (d StringDict) Has(key string) bool

Has reports whether the dictionary contains the specified key.

func (StringDict) Keys Uses

func (d StringDict) Keys() []string

Keys returns a new sorted slice of d's keys.

func (StringDict) String Uses

func (d StringDict) String() string

type Thread Uses

type Thread struct {
    // Name is an optional name that describes the thread, for debugging.
    Name string

    // Print is the client-supplied implementation of the Starlark
    // 'print' function. If nil, fmt.Fprintln(os.Stderr, msg) is
    // used instead.
    Print func(thread *Thread, msg string)

    // Load is the client-supplied implementation of module loading.
    // Repeated calls with the same module name must return the same
    // module environment or error.
    // The error message need not include the module name.
    //
    // See example_test.go for some example implementations of Load.
    Load func(thread *Thread, module string) (StringDict, error)
    // contains filtered or unexported fields
}

A Thread contains the state of a Starlark thread, such as its call stack and thread-local storage. The Thread is threaded throughout the evaluator.

func (*Thread) CallFrame Uses

func (thread *Thread) CallFrame(depth int) CallFrame

CallFrame returns a copy of the specified frame of the callstack. It should only be used in built-ins called from Starlark code. Depth 0 means the frame of the built-in itself, 1 is its caller, and so on.

It is equivalent to CallStack().At(depth), but more efficient.

func (*Thread) CallStack Uses

func (thread *Thread) CallStack() CallStack

CallStack returns a new slice containing the thread's stack of call frames.

func (*Thread) CallStackDepth Uses

func (thread *Thread) CallStackDepth() int

CallStackDepth returns the number of frames in the current call stack.

func (*Thread) DebugFrame Uses

func (thread *Thread) DebugFrame(depth int) DebugFrame

DebugFrame returns the debugger interface for the specified frame of the interpreter's call stack. Frame numbering is as for Thread.CallFrame.

This function is intended for use in debugging tools. Most applications should have no need for it; use CallFrame instead.

func (*Thread) Local Uses

func (thread *Thread) Local(key string) interface{}

Local returns the thread-local value associated with the specified key.

func (*Thread) SetLocal Uses

func (thread *Thread) SetLocal(key string, value interface{})

SetLocal sets the thread-local value associated with the specified key. It must not be called after execution begins.

type Tuple Uses

type Tuple []Value

A Tuple represents a Starlark tuple value.

func (Tuple) CompareSameType Uses

func (x Tuple) CompareSameType(op syntax.Token, y_ Value, depth int) (bool, error)

func (Tuple) Freeze Uses

func (t Tuple) Freeze()

func (Tuple) Hash Uses

func (t Tuple) Hash() (uint32, error)

func (Tuple) Index Uses

func (t Tuple) Index(i int) Value

func (Tuple) Iterate Uses

func (t Tuple) Iterate() Iterator

func (Tuple) Len Uses

func (t Tuple) Len() int

func (Tuple) Slice Uses

func (t Tuple) Slice(start, end, step int) Value

func (Tuple) String Uses

func (t Tuple) String() string

func (Tuple) Truth Uses

func (t Tuple) Truth() Bool

func (Tuple) Type Uses

func (t Tuple) Type() string

type Value Uses

type Value interface {
    // String returns the string representation of the value.
    // Starlark string values are quoted as if by Python's repr.
    String() string

    // Type returns a short string describing the value's type.
    Type() string

    // Freeze causes the value, and all values transitively
    // reachable from it through collections and closures, to be
    // marked as frozen.  All subsequent mutations to the data
    // structure through this API will fail dynamically, making the
    // data structure immutable and safe for publishing to other
    // Starlark interpreters running concurrently.
    Freeze()

    // Truth returns the truth value of an object.
    Truth() Bool

    // Hash returns a function of x such that Equals(x, y) => Hash(x) == Hash(y).
    // Hash may fail if the value's type is not hashable, or if the value
    // contains a non-hashable value. The hash is used only by dictionaries and
    // is not exposed to the Starlark program.
    Hash() (uint32, error)
}

Value is a value in the Starlark interpreter.

func Binary Uses

func Binary(op syntax.Token, x, y Value) (Value, error)

Binary applies a strict binary operator (not AND or OR) to its operands. For equality tests or ordered comparisons, use Compare instead.

func Call Uses

func Call(thread *Thread, fn Value, args Tuple, kwargs []Tuple) (Value, error)

Call calls the function fn with the specified positional and keyword arguments.

func Eval Uses

func Eval(thread *Thread, filename string, src interface{}, env StringDict) (Value, error)

Eval parses, resolves, and evaluates an expression within the specified (predeclared) environment.

Evaluation cannot mutate the environment dictionary itself, though it may modify variables reachable from the dictionary.

The filename and src parameters are as for syntax.Parse.

If Eval fails during evaluation, it returns an *EvalError containing a backtrace.

func EvalExpr Uses

func EvalExpr(thread *Thread, expr syntax.Expr, env StringDict) (Value, error)

EvalExpr resolves and evaluates an expression within the specified (predeclared) environment.

Resolving an expression mutates it. Do not call EvalExpr more than once for the same expression.

Evaluation cannot mutate the environment dictionary itself, though it may modify variables reachable from the dictionary.

If Eval fails during evaluation, it returns an *EvalError containing a backtrace.

func Unary Uses

func Unary(op syntax.Token, x Value) (Value, error)

Unary applies a unary operator (+, -, ~, not) to its operand.

Package starlark imports 25 packages (graph) and is imported by 59 packages. Updated 2019-05-17. Refresh now. Tools for package owners.