Documentation
¶
Overview ¶
Starkit is a toolkit for implementing Starlark interpreters, with support for:
(1) reusable sets of builtins (2) collecting state on a starlark thread (3) instrumenting builtins with analytics
So that builtins from different packages can be composed.
This package is designed to eventually be a separate repo.
Index ¶
- func AbsPath(t *starlark.Thread, path string) string
- func AbsWorkingDir(t *starlark.Thread) string
- func ContextFromThread(t *starlark.Thread) (context.Context, error)
- func CurrentExecPath(t *starlark.Thread) string
- func SetState(t *starlark.Thread, valOrFn interface{}) error
- func UnpackArgs(t *starlark.Thread, fnName string, args starlark.Tuple, ...) error
- func UnpackBacktrace(err error) error
- type ArgUnpacker
- type Environment
- func (e *Environment) AddBuiltin(name string, f Function) error
- func (e *Environment) AddLoadInterceptor(i LoadInterceptor)
- func (e *Environment) AddValue(name string, val starlark.Value) error
- func (e *Environment) SetArgUnpacker(unpackArgs ArgUnpacker)
- func (e *Environment) SetContext(ctx context.Context)
- func (e *Environment) SetFakeFileSystem(files map[string]string)
- func (e *Environment) SetPrint(print func(thread *starlark.Thread, msg string))
- type Extension
- type Fixture
- func (f *Fixture) ExecFile(name string) (Model, error)
- func (f *Fixture) File(name, contents string)
- func (f *Fixture) JoinPath(elem ...string) string
- func (f *Fixture) OnStart(e *Environment) error
- func (f *Fixture) Path() string
- func (f *Fixture) PrintOutput() string
- func (f *Fixture) SetLoadInterceptor(i LoadInterceptor)
- func (f *Fixture) Symlink(old, new string)
- func (f *Fixture) TearDown()
- func (f *Fixture) UseRealFS()
- type Function
- type LoadInterceptor
- type Model
- type Module
- type OnBuiltinCallExtension
- type OnExecExtension
- type StatefulExtension
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AbsPath ¶
We want to resolve paths relative to the dir where the currently executing file lives, not relative to the working directory.
func AbsWorkingDir ¶
func ContextFromThread ¶ added in v0.12.1
func CurrentExecPath ¶
Path to the file that's currently executing
func SetState ¶
SetState works like SetState in React. It can take a value or a function.
That function should transform old state into new state. It can have the signature `func(T) T` or `func(T) (T, error)`.
For example, an extension that accumulated strings might use SetState() like this:
err := starkit.SetState(t, func(strings []string) {
return append([]string{newString}, strings...)
})
This would be so much easier with generics :grimace:
SetState will return an error if it can't match the type of anything in the state store.
func UnpackArgs ¶
func UnpackArgs(t *starlark.Thread, fnName string, args starlark.Tuple, kwargs []starlark.Tuple, pairs ...interface{}) error
Unpacks args, using the arg unpacker on the current thread.
func UnpackBacktrace ¶ added in v0.10.16
Keep unwrapping errors until we find an error with a backtrace.
Types ¶
type ArgUnpacker ¶
type Environment ¶
type Environment struct {
// contains filtered or unexported fields
}
A starlark execution environment.
func (*Environment) AddBuiltin ¶
func (e *Environment) AddBuiltin(name string, f Function) error
Add a builtin to the environment.
All builtins will be wrapped to invoke OnBuiltinCall on every extension.
All builtins should use starkit.UnpackArgs to get instrumentation.
func (*Environment) AddLoadInterceptor ¶ added in v0.12.0
func (e *Environment) AddLoadInterceptor(i LoadInterceptor)
func (*Environment) AddValue ¶
func (e *Environment) AddValue(name string, val starlark.Value) error
func (*Environment) SetArgUnpacker ¶
func (e *Environment) SetArgUnpacker(unpackArgs ArgUnpacker)
func (*Environment) SetContext ¶ added in v0.12.1
func (e *Environment) SetContext(ctx context.Context)
func (*Environment) SetFakeFileSystem ¶
func (e *Environment) SetFakeFileSystem(files map[string]string)
Set a fake file system so that we can write tests that don't touch the file system. Expressed as a map from paths to contents.
type Extension ¶
type Extension interface {
// Called when execution begins.
OnStart(e *Environment) error
}
An extension to a starlark execution environment.
type Fixture ¶
type Fixture struct {
// contains filtered or unexported fields
}
A fixture for test setup/teardown
func (*Fixture) OnStart ¶
func (f *Fixture) OnStart(e *Environment) error
func (*Fixture) PrintOutput ¶
func (*Fixture) SetLoadInterceptor ¶ added in v0.12.0
func (f *Fixture) SetLoadInterceptor(i LoadInterceptor)
type LoadInterceptor ¶ added in v0.12.0
type LoadInterceptor interface {
// LocalPath returns the path that the Tiltfile code should be read from.
// Must be stable, because it's used as a cache key
// Ensure the content is present in the path returned
// Returns "" if this interceptor doesn't act on this path
LocalPath(t *starlark.Thread, path string) (string, error)
}
LoadInterceptor allows an Extension to intercept a load to set the contents based on the requested path.
type Model ¶
type Model struct {
// contains filtered or unexported fields
}
type Module ¶
type Module struct {
// contains filtered or unexported fields
}
A frozen starlark module object. Can only be changed from Go.
type OnBuiltinCallExtension ¶
type OnExecExtension ¶
type StatefulExtension ¶
type StatefulExtension interface {
Extension
NewState() interface{}
}
Starkit extensions are not allowed to have mutable state.
Starlark has different ideas about mutable state than most programming languages. In particular, state is mutable during file execution, but becomes immutable when it's imported into other files.
This allows Starlark to execute files in parallel without locks.
To play more nicely with Starlark, Starkit extensions manage state with an init/reduce pattern. That means each extension should define:
1) An initial state (created with NewModel()) 2) Make subsequent mutations to state with starkit.SetState
At the end of execution, Starkit will return a data model with the accumulated state from all extensions.
See: https://github.com/google/starlark-go/blob/master/doc/spec.md#identity-and-mutation
Source Files