starlet

package module
v0.0.4 Latest Latest
Warning

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

 Go to latest Published: Jul 21, 2023 License: MIT Imports: 25 Imported by: 15

README

✨ Starlet - Supercharging Starlark, Simply

godoc codecov codacy codeclimate

Enhancing your Starlark scripting experience with powerful extensions and enriched wrappers. Start your Starlark journey with Starlet, where simplicity meets functionality.

⚠ Under Active Development: Please note that this library is currently under active development. As a result, the API may undergo significant changes in the future. Use at your own risk, or consider waiting until a more stable release before using it in production.

Documentation

Overview

Package starlet provides powerful extensions and enriched wrappers for Starlark scripting.

Its goal is to enhance the user's scripting experience by combining simplicity and functionality. It offers robust, thread-safe types such as Machine, which serves as a wrapper for Starlark runtime environments. With Starlet, users can easily manage global variables, load modules, and control the script execution flow.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DisableGlobalReassign 

func DisableGlobalReassign()

DisableGlobalReassign disables global reassignment in all Starlark environments.

func DisableRecursionSupport 

func DisableRecursionSupport()

DisableRecursionSupport disables recursion support in all Starlark environments.

func EnableGlobalReassign 

func EnableGlobalReassign()

EnableGlobalReassign enables global reassignment in all Starlark environments.

func EnableRecursionSupport 

func EnableRecursionSupport()

EnableRecursionSupport enables recursion support in all Starlark environments.

func GetAllBuiltinModuleNames 

func GetAllBuiltinModuleNames() []string

GetAllBuiltinModuleNames returns a list of all builtin module names.

func RunFile 

func RunFile(name string, fileSys fs.FS, extras StringAnyMap) (*Machine, StringAnyMap, error)

RunFile initiates a Machine, executes a script from a file with extra variables, and returns the Machine and the execution result.

func RunScript 

func RunScript(content []byte, extras StringAnyMap) (*Machine, StringAnyMap, error)

RunScript initiates a Machine, executes a script with extra variables, and returns the Machine and the execution result.

func RunTrustedFile 

func RunTrustedFile(name string, fileSys fs.FS, globals, extras StringAnyMap) (*Machine, StringAnyMap, error)

RunTrustedFile initiates a Machine, executes a script from a file with all builtin modules loaded and extra variables, returns the Machine and the result. Use with caution as it allows script access to file system and network.

func RunTrustedScript 

func RunTrustedScript(content []byte, globals, extras StringAnyMap) (*Machine, StringAnyMap, error)

RunTrustedScript initiates a Machine, executes a script with all builtin modules loaded and extra variables, returns the Machine and the result. Use with caution as it allows script access to file system and network.

Types

type ExecError 

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

ExecError is a custom error type for Starlet execution errors.

func (ExecError) Error 

func (e ExecError) Error() string

Error returns the error message.

func (ExecError) Unwrap 

func (e ExecError) Unwrap() error

Unwrap returns the cause of the error.

type LoadFunc 

type LoadFunc func(thread *starlark.Thread, module string) (starlark.StringDict, error)

LoadFunc is a function that tells Starlark how to find and load other scripts using the load() function. If you don't use load() in your scripts, you can pass in nil.

type Machine 

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

Machine is a thread-safe type that wraps Starlark runtime environments. Machine ensures thread safety by using a sync.RWMutex to control access to the environment's state.

The Machine struct stores the state of the environment, including scripts, modules, and global variables. It provides methods for setting and getting these values, and for running the script. A Machine instance can be configured to preload modules and global variables before running a script or after resetting the environment. It can also lazyload modules right before running the script, the lazyload modules are defined in a list of module loaders and are invoked when the script is run.

The global variables and preload modules can be set before the first run of the script or after resetting the environment. Additionally, extra variables can be set for each run of the script.

Modules are divided into two types: preload and lazyload. Preload modules are loaded before the script is run, while lazyload modules are loaded as and when they are required during the script execution.

The order of precedence for overriding is as follows: global variables, preload modules, and then extra variables before the run, while lazyload modules have the highest precedence during the run.

Setting a print function allows the script to output text to the console or another output stream.

The script to be run is defined by its name and content, and potentially a filesystem (fs.FS) if the script is to be loaded from a file.

The result of each run is cached and written back to the environment, so that it can be used in the next run of the script.

The environment can be reset, allowing the script to be run again with a fresh set of variables and modules.

func NewDefault 

func NewDefault() *Machine

NewDefault creates a new Starlark runtime environment.

func NewWithBuiltins 

func NewWithBuiltins(globals StringAnyMap, additionalPreload ModuleLoaderList, additionalLazyload ModuleLoaderMap) *Machine

NewWithBuiltins creates a new Starlark runtime environment with given global variables and all preload & lazyload built-in modules.

func NewWithGlobals 

func NewWithGlobals(globals StringAnyMap) *Machine

NewWithGlobals creates a new Starlark runtime environment with given global variables.

func NewWithLoaders 

func NewWithLoaders(globals StringAnyMap, preload ModuleLoaderList, lazyload ModuleLoaderMap) *Machine

NewWithLoaders creates a new Starlark runtime environment with given global variables and preload & lazyload module loaders.

func NewWithNames 

func NewWithNames(globals StringAnyMap, preloads []string, lazyloads []string) *Machine

NewWithNames creates a new Starlark runtime environment with given global variables, preload and lazyload module names. The modules should be built-in modules, and it panics if any of the given modules fails to load.

func (*Machine) AddGlobals 

func (m *Machine) AddGlobals(globals StringAnyMap)

AddGlobals adds the globals of the Starlark runtime environment. These variables only take effect before the first run or after a reset.

func (*Machine) AddLazyloadModules 

func (m *Machine) AddLazyloadModules(mods ModuleLoaderMap)

AddLazyloadModules adds the modules allowed to be loaded later of the Starlark runtime environment.

func (*Machine) AddPreloadModules 

func (m *Machine) AddPreloadModules(mods ModuleLoaderList)

AddPreloadModules adds the preload modules of the Starlark runtime environment. These modules only take effect before the first run or after a reset.

func (*Machine) Call 

func (m *Machine) Call(name string, args ...interface{}) (out interface{}, err error)

Call executes a Starlark function or builtin saved in the thread and returns the result.

func (*Machine) Export 

func (m *Machine) Export() StringAnyMap

Export returns the current variables of the Starlark runtime environment.

func (*Machine) GetGlobals 

func (m *Machine) GetGlobals() StringAnyMap

GetGlobals gets the globals of the Starlark runtime environment.

func (*Machine) GetLazyloadModules 

func (m *Machine) GetLazyloadModules() ModuleLoaderMap

GetLazyloadModules gets the modules allowed to be loaded later of the Starlark runtime environment.

func (*Machine) GetPreloadModules 

func (m *Machine) GetPreloadModules() ModuleLoaderList

GetPreloadModules gets the preload modules of the Starlark runtime environment.

func (*Machine) REPL 

func (m *Machine) REPL()

REPL is a Read-Eval-Print-Loop for Starlark. It loads the predeclared symbols and modules into the global environment,

func (*Machine) Reset 

func (m *Machine) Reset()

Reset resets the machine to initial state before the first run.

func (*Machine) Run 

func (m *Machine) Run() (StringAnyMap, error)

Run executes a preset script and returns the output.

func (*Machine) RunFile 

func (m *Machine) RunFile(name string, fileSys fs.FS, extras StringAnyMap) (StringAnyMap, error)

RunFile executes a script from a file with additional variables, which take precedence over global variables and modules, returns the result.

func (*Machine) RunScript 

func (m *Machine) RunScript(content []byte, extras StringAnyMap) (StringAnyMap, error)

RunScript executes a script with additional variables, which take precedence over global variables and modules, returns the result.

func (*Machine) RunWithContext 

func (m *Machine) RunWithContext(ctx context.Context, extras StringAnyMap) (StringAnyMap, error)

RunWithContext executes a preset script within a specified context and additional variables, which take precedence over global variables and modules, returns the result.

func (*Machine) RunWithTimeout 

func (m *Machine) RunWithTimeout(timeout time.Duration, extras StringAnyMap) (StringAnyMap, error)

RunWithTimeout executes a preset script with a timeout and additional variables, which take precedence over global variables and modules, returns the result.

func (*Machine) SetGlobals 

func (m *Machine) SetGlobals(globals StringAnyMap)

SetGlobals sets global variables in the Starlark runtime environment. These variables only take effect before the first run or after a reset.

func (*Machine) SetInputConversionEnabled added in v0.0.4 

func (m *Machine) SetInputConversionEnabled(enabled bool)

SetInputConversionEnabled controls the conversion of Starlark variables from input into Starlight wrappers.

func (*Machine) SetLazyloadModules 

func (m *Machine) SetLazyloadModules(mods ModuleLoaderMap)

SetLazyloadModules sets the modules allowed to be loaded later of the Starlark runtime environment.

func (*Machine) SetOutputConversionEnabled added in v0.0.4 

func (m *Machine) SetOutputConversionEnabled(enabled bool)

SetOutputConversionEnabled controls the conversion of Starlark variables from output into Starlight wrappers.

func (*Machine) SetPreloadModules 

func (m *Machine) SetPreloadModules(mods ModuleLoaderList)

SetPreloadModules sets the preload modules of the Starlark runtime environment. These modules only take effect before the first run or after a reset.

func (*Machine) SetPrintFunc 

func (m *Machine) SetPrintFunc(printFunc PrintFunc)

SetPrintFunc sets the print function of the Starlark runtime environment.

func (*Machine) SetScript 

func (m *Machine) SetScript(name string, content []byte, fileSys fs.FS)

SetScript sets the script related things of the Starlark runtime environment.

func (*Machine) String 

func (m *Machine) String() string

type ModuleLoader 

type ModuleLoader func() (starlark.StringDict, error)

ModuleLoader is a function that loads a Starlark module and returns the module's string dict.

func GetBuiltinModule 

func GetBuiltinModule(name string) ModuleLoader

GetBuiltinModule returns the builtin module with the given name.

func MakeModuleLoaderFromFile 

func MakeModuleLoaderFromFile(name string, fileSys fs.FS, predeclared starlark.StringDict) ModuleLoader

MakeModuleLoaderFromFile creates a module loader from the given file.

func MakeModuleLoaderFromMap 

func MakeModuleLoaderFromMap(m StringAnyMap) ModuleLoader

MakeModuleLoaderFromMap creates a module loader from the given map, it converts the map to a string dict when loading.

func MakeModuleLoaderFromReader 

func MakeModuleLoaderFromReader(name string, rd io.Reader, predeclared starlark.StringDict) ModuleLoader

MakeModuleLoaderFromReader creates a module loader from the given IO reader.

func MakeModuleLoaderFromString 

func MakeModuleLoaderFromString(name, source string, predeclared starlark.StringDict) ModuleLoader

MakeModuleLoaderFromString creates a module loader from the given source code.

func MakeModuleLoaderFromStringDict 

func MakeModuleLoaderFromStringDict(d starlark.StringDict) ModuleLoader

MakeModuleLoaderFromStringDict creates a module loader from the given string dict.

type ModuleLoaderList 

type ModuleLoaderList []ModuleLoader

ModuleLoaderList is a list of Starlark module loaders, usually used to load a list of modules in order.

func GetAllBuiltinModules 

func GetAllBuiltinModules() ModuleLoaderList

GetAllBuiltinModules returns a list of all builtin modules.

func MakeBuiltinModuleLoaderList 

func MakeBuiltinModuleLoaderList(names ...string) (ModuleLoaderList, error)

MakeBuiltinModuleLoaderList creates a list of module loaders from a list of module names. It returns an error as second return value if any module is not found.

func (ModuleLoaderList) Clone 

func (l ModuleLoaderList) Clone() []ModuleLoader

Clone returns a copy of the list.

func (ModuleLoaderList) LoadAll 

func (l ModuleLoaderList) LoadAll(d starlark.StringDict) error

LoadAll loads all modules in the list into the given StringDict. It returns an error as second return value if any module fails to load.

type ModuleLoaderMap 

type ModuleLoaderMap map[string]ModuleLoader

ModuleLoaderMap is a map of Starlark module loaders, usually used to load a map of modules by name.

func GetBuiltinModuleMap 

func GetBuiltinModuleMap() ModuleLoaderMap

GetBuiltinModuleMap returns a map of all builtin modules.

func MakeBuiltinModuleLoaderMap 

func MakeBuiltinModuleLoaderMap(names ...string) (ModuleLoaderMap, error)

MakeBuiltinModuleLoaderMap creates a map of module loaders from a list of module names. It returns an error as second return value if any module is not found.

func (ModuleLoaderMap) Clone 

func (m ModuleLoaderMap) Clone() ModuleLoaderMap

Clone returns a copy of the map.

func (ModuleLoaderMap) GetLazyLoader 

func (m ModuleLoaderMap) GetLazyLoader() NamedModuleLoader

GetLazyLoader returns a lazy loader that loads the module with the given name. It returns an error as second return value if the module is found but fails to load. Otherwise, the first return value is nil if the module is not found. Note that the loader is usually used by the Starlark thread, so that the errors should not be wrapped.

func (ModuleLoaderMap) Keys 

func (m ModuleLoaderMap) Keys() []string

Keys returns the keys of the map, sorted in ascending order of the keys.

func (ModuleLoaderMap) Merge 

func (m ModuleLoaderMap) Merge(other ModuleLoaderMap)

Merge merges the given map into the map. It does nothing if the current map is nil.

func (ModuleLoaderMap) Values 

func (m ModuleLoaderMap) Values() []ModuleLoader

Values returns the elements of the map, sorted in ascending order of the keys.

type NamedModuleLoader 

type NamedModuleLoader func(string) (starlark.StringDict, error)

NamedModuleLoader is a function that loads a Starlark module with the given name and returns the module's string dict. If the module is not found, it returns nil as the first and second return value.

type PrintFunc 

type PrintFunc func(thread *starlark.Thread, msg string)

PrintFunc is a function that tells Starlark how to print messages. If nil, the default `fmt.Fprintln(os.Stderr, msg)` will be used instead.

type StringAnyMap 

type StringAnyMap map[string]interface{}

StringAnyMap type is a map of string to interface{} and is used to store global variables like StringDict of Starlark, but not a Starlark type.

func (StringAnyMap) Clone 

func (d StringAnyMap) Clone() StringAnyMap

Clone returns a copy of the data store.

func (StringAnyMap) Merge 

func (d StringAnyMap) Merge(other StringAnyMap)

Merge merges the given data store into the current data store. It does nothing if the current data store is nil.

func (StringAnyMap) MergeDict 

func (d StringAnyMap) MergeDict(other starlark.StringDict)

MergeDict merges the given string dict into the current data store.

Source Files

View all Source files

Directories

Path Synopsis
cmd
starlet Module
lib
base64
Package base64 defines base64 encoding & decoding functions for Starlark.
 Package base64 defines base64 encoding & decoding functions for Starlark.
goidiomatic
Package goidiomatic provides a Starlark module that defines Go idiomatic functions and values.
 Package goidiomatic provides a Starlark module that defines Go idiomatic functions and values.
hash
Package hash defines hash primitives for Starlark.
 Package hash defines hash primitives for Starlark.
http
Package http defines a module for doing http operations in Starlark.
 Package http defines a module for doing http operations in Starlark.
internal
Package internal contains types and utilities that are not part of the public API, and may change without notice.
 Package internal contains types and utilities that are not part of the public API, and may change without notice.
json
Package json defines utilities for converting Starlark values to/from JSON strings based on go.starlark.net/lib/json.
 Package json defines utilities for converting Starlark values to/from JSON strings based on go.starlark.net/lib/json.
random
Package random defines functions that generate random values for various distributions, it's intended to be a drop-in subset of Python's random module for Starlark.
 Package random defines functions that generate random values for various distributions, it's intended to be a drop-in subset of Python's random module for Starlark.
re
Package re defines regular expression functions, it's intended to be a drop-in subset of Python's re module for Starlark.
 Package re defines regular expression functions, it's intended to be a drop-in subset of Python's re module for Starlark.

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.