starkit

package
v0.33.21 Latest Latest
Warning

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

 Go to latest Published: Nov 8, 2024 License: Apache-2.0 Imports: 18 Imported by: 0

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

Constants

This section is empty.

Variables

View Source 
var ErrStopExecution = errors.New("stop execution")

ErrStopExecution is a sentinel value to stop Starlark execution but will not be propagated back to callers.

It is used by the custom exit() built-in to allow halting Tiltfile execution in a non-fatal manner.

Functions

func AbsPath 

func AbsPath(t *starlark.Thread, path string) string

We want to resolve paths relative to the dir where the currently executing file lives, not relative to the working directory.

func AbsWorkingDir 

func AbsWorkingDir(t *starlark.Thread) string

func ContextFromThread added in v0.14.0 

func ContextFromThread(t *starlark.Thread) (context.Context, error)

func CurrentExecPath 

func CurrentExecPath(t *starlark.Thread) string

Path to the file that's currently executing

func NewThread added in v0.27.2 

func NewThread(ctx context.Context, model Model) *starlark.Thread

func SetState 

func SetState(t *starlark.Thread, valOrFn interface{}) error

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 plugin 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 StartTiltfileFromThread added in v0.22.10 

func StartTiltfileFromThread(t *starlark.Thread) (*v1alpha1.Tiltfile, error)

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 

func UnpackBacktrace(err error) error

Keep unwrapping errors until we find an error with a backtrace.

Types

type ArgUnpacker 

type ArgUnpacker func(fnName string, args starlark.Tuple, kwargs []starlark.Tuple, pairs ...interface{}) error

type BuiltinCall added in v0.17.3 

type BuiltinCall struct {
	Name string
	Args starlark.Tuple
	Dur  time.Duration
}

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 plugin.

All builtins should use starkit.UnpackArgs to get instrumentation.

func (*Environment) AddLoadInterceptor added in v0.14.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.14.0 

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.

func (*Environment) SetPrint 

func (e *Environment) SetPrint(print func(thread *starlark.Thread, msg string))

func (*Environment) StartTiltfile added in v0.22.10 

func (e *Environment) StartTiltfile() *v1alpha1.Tiltfile

The tiltfile model driving this environment.

type Fixture 

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

A fixture for test setup/teardown

func NewFixture 

func NewFixture(tb testing.TB, plugins ...Plugin) *Fixture

func (*Fixture) ExecFile 

func (f *Fixture) ExecFile(name string) (Model, error)

func (*Fixture) File 

func (f *Fixture) File(name, contents string)

func (*Fixture) JoinPath added in v0.10.24 

func (f *Fixture) JoinPath(elem ...string) string

func (*Fixture) OnStart 

func (f *Fixture) OnStart(e *Environment) error

func (*Fixture) Path 

func (f *Fixture) Path() string

func (*Fixture) PrintOutput 

func (f *Fixture) PrintOutput() string

func (*Fixture) SetContext added in v0.18.3 

func (f *Fixture) SetContext(ctx context.Context)

func (*Fixture) SetLoadInterceptor added in v0.14.0 

func (f *Fixture) SetLoadInterceptor(i LoadInterceptor)

func (*Fixture) SetOutput added in v0.22.4 

func (f *Fixture) SetOutput(out *bytes.Buffer)
func (f *Fixture) Symlink(old, new string)

func (*Fixture) Tiltfile added in v0.22.10 

func (f *Fixture) Tiltfile() *v1alpha1.Tiltfile

func (*Fixture) UseRealFS added in v0.10.15 

func (f *Fixture) UseRealFS()

type Function added in v0.10.22 

type Function func(thread *starlark.Thread, fn *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error)

type LoadInterceptor added in v0.14.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 Plugin to intercept a load to set the contents based on the requested path.

type Model 

type Model struct {
	BuiltinCalls []BuiltinCall
	// contains filtered or unexported fields
}

func ExecFile 

func ExecFile(tf *v1alpha1.Tiltfile, plugins ...Plugin) (Model, error)

The main entrypoint to starkit. Execute a file with a set of starlark plugins.

func ModelFromThread 

func ModelFromThread(t *starlark.Thread) (Model, error)

func NewModel 

func NewModel(plugins ...Plugin) (Model, error)

func (Model) Load 

func (m Model) Load(ptr interface{}) error

type Module 

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

A frozen starlark module object. Can only be changed from Go.

func (Module) Attr 

func (m Module) Attr(name string) (starlark.Value, error)

func (Module) AttrNames 

func (m Module) AttrNames() []string

func (Module) Freeze 

func (m Module) Freeze()

func (Module) Hash 

func (m Module) Hash() (uint32, error)

func (Module) String 

func (m Module) String() string

func (Module) Truth 

func (m Module) Truth() starlark.Bool

func (Module) Type 

func (m Module) Type() string

type OnBuiltinCallPlugin added in v0.22.4 

type OnBuiltinCallPlugin interface {
	Plugin

	// Called before each builtin is called
	OnBuiltinCall(name string, fn *starlark.Builtin)
}

type OnExecPlugin added in v0.22.4 

type OnExecPlugin interface {
	Plugin

	// Called before each new Starlark file is loaded
	OnExec(t *starlark.Thread, path string, contents []byte) error
}

type Plugin added in v0.22.4 

type Plugin interface {
	// Called when execution begins.
	OnStart(e *Environment) error
}

An plugin to a starlark execution environment.

type StatefulPlugin added in v0.22.4 

type StatefulPlugin interface {
	Plugin

	NewState() interface{}
}

Starkit plugins 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 plugins manage state with an init/reduce pattern. That means each plugin 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 plugins.

See: https://github.com/google/starlark-go/blob/master/doc/spec.md#identity-and-mutation

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.