starbox

package module
v0.0.5 Latest Latest
Warning

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

 Go to latest Published: Apr 17, 2024 License: MIT Imports: 17 Imported by: 0

README ¶

🥡 starbox

godoc codecov codacy codeclimate go report

Starlark in a box -- a simple Starlark REPL and script runner.

It provides three main features:

  • Execute a Starlark script file or REPL
  • Data exchange between Starlark and Go
  • Function call from Starlark to Go, or vice versa

Documentation ¶

Overview ¶

Package starbox provides a set of utilities for building Starlark virtual machine.

Index ¶

Constants ¶

This section is empty.

Variables ¶

View Source 
var (
	// ErrNoStarbox is the error for RunnerConfig.Execute() when no Starbox instance is set
	ErrNoStarbox = errors.New("no starbox instance")
)

Functions ¶

func NewMemory ¶ added in v0.0.3 

func NewMemory() *dataconv.SharedDict

NewMemory creates a new shared dictionary for la mémoire collective.

func SetLog ¶ 

func SetLog(l *zap.SugaredLogger)

SetLog sets the logger from outside the package.

Types ¶

type FuncMap ¶ added in v0.0.4 

type FuncMap map[string]StarlarkFunc

FuncMap is a map of Starlark functions.

type InspectCondFunc ¶ added in v0.0.2 

type InspectCondFunc func(starlet.StringAnyMap, error) bool

InspectCondFunc is a function type for inspecting the converted output of Run*() and decide whether to continue.

type ModuleSetName ¶ 

type ModuleSetName string

ModuleSetName defines the name of a module set. 

const (
	// EmptyModuleSet represents the predefined module set for empty scripts, it contains no modules.
	EmptyModuleSet ModuleSetName = "none"
	// SafeModuleSet represents the predefined module set for safe scripts, it contains only safe modules that do not have side effects with outside world.
	SafeModuleSet ModuleSetName = "safe"
	// NetworkModuleSet represents the predefined module set for network scripts, it's based on SafeModuleSet with additional network modules.
	NetworkModuleSet ModuleSetName = "network"
	// FullModuleSet represents the predefined module set for full scripts, it includes all available modules.
	FullModuleSet ModuleSetName = "full"
)

type RunnerConfig ¶ added in v0.0.5 

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

RunnerConfig defines the execution configuration for a Starbox instance.

func NewRunConfig ¶ added in v0.0.5 

func NewRunConfig() *RunnerConfig

NewRunConfig creates a new RunnerConfig instance.

func (*RunnerConfig) Context ¶ added in v0.0.5 

func (c *RunnerConfig) Context(ctx context.Context) *RunnerConfig

Context sets the context for the execution.

func (*RunnerConfig) Execute ¶ added in v0.0.5 

func (c *RunnerConfig) Execute() (starlet.StringAnyMap, error)

Execute executes the box with the given configuration.

func (*RunnerConfig) FileName ¶ added in v0.0.5 

func (c *RunnerConfig) FileName(name string) *RunnerConfig

FileName sets the script file name for the execution.

func (*RunnerConfig) Inspect ¶ added in v0.0.5 

func (c *RunnerConfig) Inspect(force bool) *RunnerConfig

Inspect sets the inspection mode for the execution. It works like InspectCond with a condition function that forces the REPL mode, by adding a condition function to force the REPL mode, regardless of the output or error. It can be overridden by InspectCond() or Inspect().

func (*RunnerConfig) InspectCond ¶ added in v0.0.5 

func (c *RunnerConfig) InspectCond(cond InspectCondFunc) *RunnerConfig

InspectCond sets the inspection mode with a condition function for the execution. It can be overridden by InspectCond() or Inspect().

func (*RunnerConfig) KeyValue ¶ added in v0.0.5 

func (c *RunnerConfig) KeyValue(key string, value interface{}) *RunnerConfig

KeyValue sets the key-value pair for the execution.

func (*RunnerConfig) KeyValueMap ¶ added in v0.0.5 

func (c *RunnerConfig) KeyValueMap(extras starlet.StringAnyMap) *RunnerConfig

KeyValueMap merges the key-value pairs for the execution.

func (*RunnerConfig) Script ¶ added in v0.0.5 

func (c *RunnerConfig) Script(content string) *RunnerConfig

Script sets the script content for the execution.

func (*RunnerConfig) Starbox ¶ added in v0.0.5 

func (c *RunnerConfig) Starbox(b *Starbox) *RunnerConfig

Starbox sets the Starbox instance for the execution.

func (*RunnerConfig) String ¶ added in v0.0.5 

func (c *RunnerConfig) String() string

String returns a string representation of the RunnerConfig.

func (*RunnerConfig) Timeout ¶ added in v0.0.5 

func (c *RunnerConfig) Timeout(timeout time.Duration) *RunnerConfig

Timeout sets the timeout for the execution.

type Starbox ¶ 

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

Starbox is a wrapper of starlet.Machine with additional features.

func New ¶ 

func New(name string) *Starbox

New creates a new Starbox instance with default settings.

func (*Starbox) AddBuiltin ¶ 

func (s *Starbox) AddBuiltin(name string, starFunc StarlarkFunc)

AddBuiltin adds a builtin function with name to the global environment before execution. If the name already exists, it will be overwritten. It panics if called after execution.

func (*Starbox) AddHTTPContext ¶ added in v0.0.4 

func (s *Starbox) AddHTTPContext(req *http.Request) *libhttp.ServerResponse

AddHTTPContext adds HTTP request and response data wrapper to the global environment before execution. It takes an HTTP request and returns the response data wrapper for setting response headers and body. It panics if called after execution.

func (*Starbox) AddKeyStarlarkValue ¶ added in v0.0.4 

func (s *Starbox) AddKeyStarlarkValue(key string, value starlark.Value)

AddKeyStarlarkValue adds a key-value pair to the global environment before execution, the value is a Starlark value. If the key already exists, it will be overwritten. It panics if called after execution.

func (*Starbox) AddKeyValue ¶ 

func (s *Starbox) AddKeyValue(key string, value interface{})

AddKeyValue adds a key-value pair to the global environment before execution. If the key already exists, it will be overwritten. It panics if called after execution.

func (*Starbox) AddKeyValues ¶ 

func (s *Starbox) AddKeyValues(keyValues starlet.StringAnyMap)

AddKeyValues adds key-value pairs to the global environment before execution. Usually for output of Run()*. For each key-value pair, if the key already exists, it will be overwritten. It panics if called after execution.

func (*Starbox) AddModuleData ¶ 

func (s *Starbox) AddModuleData(moduleName string, moduleData starlark.StringDict)

AddModuleData creates a module for the given module data along with a module loader, and adds it to the preload and lazyload registry. The given module data can be accessed in script via load("module_name", "key1") or module_name.key1. It panics if called after execution.

func (*Starbox) AddModuleFunctions ¶ added in v0.0.4 

func (s *Starbox) AddModuleFunctions(name string, funcs FuncMap)

AddModuleFunctions adds a module with the given module functions along with a module loader, and adds it to the preload and lazyload registry. The given module function can be accessed in script via load("module_name", "func1") or module_name.func1. It works like AddModuleData() but allows only functions as values. It panics if called after execution.

func (*Starbox) AddModuleLoader ¶ 

func (s *Starbox) AddModuleLoader(moduleName string, moduleLoader starlet.ModuleLoader)

AddModuleLoader adds a custom module loader to the preload and lazyload registry. It will not load the module until the first run, and load result can be accessed in script via load("module_name", "key1") or key1 directly. It panics if called after execution.

func (*Starbox) AddModuleScript ¶ 

func (s *Starbox) AddModuleScript(moduleName, moduleScript string)

AddModuleScript creates a module with given module script in virtual filesystem, and adds it to the preload and lazyload registry. The given module script can be accessed in script via load("module_name", "key1") or load("module_name.star", "key1") if module name has no ".star" suffix. It panics if called after execution.

func (*Starbox) AddNamedModules ¶ 

func (s *Starbox) AddNamedModules(moduleNames ...string)

AddNamedModules adds builtin modules by name to the preload and lazyload registry. It will not load the modules until the first run. It panics if called after execution.

func (*Starbox) AddStarlarkValues ¶ added in v0.0.2 

func (s *Starbox) AddStarlarkValues(keyValues starlark.StringDict)

AddStarlarkValues adds key-value pairs to the global environment before execution, the values are already converted to Starlark values. For each key-value pair, if the key already exists, it will be overwritten. It panics if called after execution.

func (*Starbox) AddStructData ¶ added in v0.0.4 

func (s *Starbox) AddStructData(structName string, structData starlark.StringDict)

AddStructData creates a module for the given struct data along with a module loader, and adds it to the preload and lazyload registry. The given struct data can be accessed in script via load("struct_name", "key1") or struct_name.key1. It panics if called after execution.

func (*Starbox) AddStructFunctions ¶ added in v0.0.4 

func (s *Starbox) AddStructFunctions(name string, funcs FuncMap)

AddStructFunctions adds a module with the given struct functions along with a module loader, and adds it to the preload and lazyload registry. The given struct function can be accessed in script via load("struct_name", "func1") or struct_name.func1. It works like AddStructData() but allows only functions as values. It panics if called after execution.

func (*Starbox) AttachMemory ¶ added in v0.0.3 

func (s *Starbox) AttachMemory(name string, memory *dataconv.SharedDict)

AttachMemory adds a shared dictionary to the global environment before execution.

func (*Starbox) CreateMemory ¶ added in v0.0.3 

func (s *Starbox) CreateMemory(name string) *dataconv.SharedDict

CreateMemory creates a new shared dictionary for la mémoire collective with the given name, and adds it to the global environment before execution.

func (*Starbox) CreateRunConfig ¶ added in v0.0.5 

func (s *Starbox) CreateRunConfig() *RunnerConfig

CreateRunConfig creates a new RunnerConfig instance from a given Starbox instance.

func (*Starbox) GetMachine ¶ 

func (s *Starbox) GetMachine() *starlet.Machine

GetMachine returns the underlying starlet.Machine instance.

func (*Starbox) REPL ¶ 

func (s *Starbox) REPL() error

REPL starts a REPL session.

func (*Starbox) Reset ¶ 

func (s *Starbox) Reset()

Reset creates an new Starlet machine and keeps the settings.

func (*Starbox) Run ¶ 

func (s *Starbox) Run(script string) (starlet.StringAnyMap, error)

Run executes a script and returns the converted output.

func (*Starbox) RunInspect ¶ 

func (s *Starbox) RunInspect(script string) (starlet.StringAnyMap, error)

RunInspect executes a script and then REPL with result and returns the converted output.

func (*Starbox) RunInspectIf ¶ added in v0.0.2 

func (s *Starbox) RunInspectIf(script string, cond InspectCondFunc) (starlet.StringAnyMap, error)

RunInspectIf executes a script and then REPL with result and returns the converted output, if the condition is met. The condition function is called with the converted output and the error from Run*(), and returns true if REPL is needed.

func (*Starbox) RunTimeout ¶ 

func (s *Starbox) RunTimeout(script string, timeout time.Duration) (starlet.StringAnyMap, error)

RunTimeout executes a script and returns the converted output.

func (*Starbox) SetFS ¶ added in v0.0.3 

func (s *Starbox) SetFS(hfs fs.FS)

SetFS sets the virtual filesystem for module scripts. If it's not nil, it'll override all the scripts added by AddModuleScript(). It panics if called after execution.

func (*Starbox) SetModuleSet ¶ 

func (s *Starbox) SetModuleSet(modSet ModuleSetName)

SetModuleSet sets the module set to be loaded before execution. It panics if called after execution.

func (*Starbox) SetPrintFunc ¶ 

func (s *Starbox) SetPrintFunc(printFunc starlet.PrintFunc)

SetPrintFunc sets the print function for Starlark. It panics if called after execution.

func (*Starbox) SetStructTag ¶ 

func (s *Starbox) SetStructTag(tag string)

SetStructTag sets the custom tag of Go struct fields for Starlark. It panics if called after execution.

func (*Starbox) String ¶ 

func (s *Starbox) String() string

String returns the name of the Starbox instance.

type StarlarkFunc ¶ 

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

StarlarkFunc is a function that can be called from Starlark.

Source Files ¶

View all Source files

Directories ¶

Path Synopsis
module
runtime
Package runtime implements the Starlark module for runtime information.
 Package runtime implements the Starlark module for runtime information.

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.