starkit

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 BuiltinCall
• 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))
  • func (e *Environment) StartPath() string
• type Extension
• type Fixture
  • func NewFixture(tb testing.TB, extensions ...Extension) *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) SetContext(ctx context.Context)
  • 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
  • func ExecFile(path string, extensions ...Extension) (Model, error)
  • func ModelFromThread(t *starlark.Thread) (Model, error)
  • func NewModel() Model
  • func (m Model) Load(ptr interface{}) error
• type Module
  • func (m Module) Attr(name string) (starlark.Value, error)
  • func (m Module) AttrNames() []string
  • func (m Module) Freeze()
  • func (m Module) Hash() (uint32, error)
  • func (m Module) String() string
  • func (m Module) Truth() starlark.Bool
  • func (m Module) Type() string
• type OnBuiltinCallExtension
• type OnExecExtension
• type StatefulExtension

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

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

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

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

All builtins should use starkit.UnpackArgs to get instrumentation.

func (*Environment) AddLoadInterceptor

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

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

func (e *Environment) StartPath() string

The absolute path to the entrypoint of the environment.

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 NewFixture

func NewFixture(tb testing.TB, extensions ...Extension) *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

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

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

func (*Fixture) SetLoadInterceptor

func (f *Fixture) SetLoadInterceptor(i LoadInterceptor)

func (*Fixture) Symlink

func (f *Fixture) Symlink(old, new string)

func (*Fixture) TearDown

func (f *Fixture) TearDown()

func (*Fixture) UseRealFS

func (f *Fixture) UseRealFS()

type Function

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

type LoadInterceptor

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 {
	BuiltinCalls []BuiltinCall
	// contains filtered or unexported fields
}

func ExecFile

func ExecFile(path string, extensions ...Extension) (Model, error)

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

func ModelFromThread

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

func NewModel

func NewModel() Model

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 OnBuiltinCallExtension

type OnBuiltinCallExtension interface {
	Extension

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

type OnExecExtension

type OnExecExtension interface {
	Extension

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

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