starlet

package module
v0.0.16 Latest Latest
Warning

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

 Go to latest Published: Apr 13, 2024 License: MIT Imports: 35 Imported by: 15

README

✨ Starlet - Supercharging Starlark, Simply

godoc codecov codacy codeclimate goreportcard

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.

Explore the capabilities of the Starlet command-line tool efficiently by installing it using the command below:

go install -v github.com/1set/starlet/cmd/starlet@latest

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 Starlark environments for loading modules.

func DisableRecursionSupport 

func DisableRecursionSupport()

DisableRecursionSupport disables recursion support in Starlark environments for loading modules.

func EnableGlobalReassign 

func EnableGlobalReassign()

EnableGlobalReassign enables global reassignment in Starlark environments for loading modules.

func EnableRecursionSupport 

func EnableRecursionSupport()

EnableRecursionSupport enables recursion support in Starlark environments for loading modules.

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 ByteCache added in v0.0.8 

type ByteCache interface {
	Get(key string) ([]byte, bool)
	Set(key string, value []byte) error
}

ByteCache is an interface for caching byte data, used for caching compiled Starlark programs.

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) DisableGlobalReassign added in v0.0.5 

func (m *Machine) DisableGlobalReassign()

DisableGlobalReassign disables global reassignment in all Starlark environments.

func (*Machine) DisableRecursionSupport added in v0.0.5 

func (m *Machine) DisableRecursionSupport()

DisableRecursionSupport disables recursion support in all Starlark environments.

func (*Machine) EnableGlobalReassign added in v0.0.5 

func (m *Machine) EnableGlobalReassign()

EnableGlobalReassign enables global reassignment in all Starlark environments.

func (*Machine) EnableRecursionSupport added in v0.0.5 

func (m *Machine) EnableRecursionSupport()

EnableRecursionSupport enables recursion support in all Starlark environments.

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) GetStarlarkPredeclared added in v0.0.8 

func (m *Machine) GetStarlarkPredeclared() starlark.StringDict

GetStarlarkPredeclared returns the Starlark predeclared names of the Starlark runtime environment. It's for advanced usage only, don't use it unless you know what you are doing.

func (*Machine) GetStarlarkThread added in v0.0.8 

func (m *Machine) GetStarlarkThread() *starlark.Thread

GetStarlarkThread returns the Starlark thread of the Starlark runtime environment. It's for advanced usage only, don't use it unless you know what you are doing.

func (*Machine) GetThreadLocal added in v0.0.11 

func (m *Machine) GetThreadLocal(key string) interface{}

GetThreadLocal returns the local value of the Starlark thread of the Starlark runtime environment. It returns nil if the thread is not set or the key is not found. Please ensure the machine already runs before calling this method.

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. Attention: It does not reset the compiled program cache.

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) SetCustomTag added in v0.0.6 

func (m *Machine) SetCustomTag(tag string)

SetCustomTag sets the custom annotation tag of Go struct fields for Starlark.

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. To disable printing, you can set it to NoopPrintFunc. Setting it to nil will invoke the default `fmt.Fprintln(os.Stderr, msg)` instead.

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) SetScriptCache added in v0.0.8 

func (m *Machine) SetScriptCache(cache ByteCache)

SetScriptCache sets the cache for compiled Starlark programs.

func (*Machine) SetScriptCacheEnabled added in v0.0.8 

func (m *Machine) SetScriptCacheEnabled(enabled bool)

SetScriptCacheEnabled controls the cache for compiled Starlark programs with the default in-memory cache. If enabled is true, it creates the default in-memory cache instance, otherwise it uses no cache.

func (*Machine) SetScriptContent added in v0.0.7 

func (m *Machine) SetScriptContent(content []byte)

SetScriptContent sets the script content of the Starlark runtime environment. It differs from SetScript in that it does not change the script name and filesystem.

func (*Machine) String 

func (m *Machine) String() string

type MemoryCache added in v0.0.8 

type MemoryCache struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

MemoryCache is a simple in-memory map-based ByteCache, serves as a default cache for Starlark programs.

func NewMemoryCache added in v0.0.8 

func NewMemoryCache() *MemoryCache

NewMemoryCache creates a new MemoryCache instance.

func (*MemoryCache) Get added in v0.0.8 

func (c *MemoryCache) Get(key string) ([]byte, bool)

Get returns the value for the given key, and whether the key exists.

func (*MemoryCache) Set added in v0.0.8 

func (c *MemoryCache) Set(key string, value []byte) error

Set sets the value for the given key.

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. 

var (
	// NoopPrintFunc is a no-op print function for the Starlark runtime environment, it does nothing.
	NoopPrintFunc PrintFunc = func(thread *starlark.Thread, msg string) {}
)

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
Package dataconv provides helper functions to convert between Starlark and Go types.
 Package dataconv provides helper functions to convert between Starlark and Go types.
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.
replacecr
Package replacecr defines a wrapper for replacing solo carriage return characters (\r) with carriage-return + line feed (\r\n).
 Package replacecr defines a wrapper for replacing solo carriage return characters (\r) with carriage-return + line feed (\r\n).
lib
atom
Package atom provides atomic operations for integers, floats and strings.
 Package atom provides atomic operations for integers, floats and strings.
base64
Package base64 defines base64 encoding & decoding functions for Starlark.
 Package base64 defines base64 encoding & decoding functions for Starlark.
csv
Package csv reads comma-separated values from strings and writes CSV data to strings.
 Package csv reads comma-separated values from strings and writes CSV data to strings.
file
Package file defines functions that manipulate files, it's inspired by file helpers from Amoy.
 Package file defines functions that manipulate files, it's inspired by file helpers from Amoy.
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.
hashlib
Package hashlib defines hash primitives for Starlark.
 Package hashlib defines hash primitives for Starlark.
http
Package http provides tools for integrating HTTP request handling within Go-based web servers and clients with Starlark scripting capabilities.
 Package http provides tools for integrating HTTP request handling within Go-based web servers and clients with Starlark scripting capabilities.
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.
log
Package log provides functionality for logging messages at various severity levels in the Starlark environment.
 Package log provides functionality for logging messages at various severity levels in the Starlark environment.
path
Package path defines functions that manipulate directories, it's inspired by pathlib module from Mojo.
 Package path defines functions that manipulate directories, it's inspired by pathlib module from Mojo.
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.
runtime
Package runtime implements the Starlark module for Go and app runtime information.
 Package runtime implements the Starlark module for Go and app runtime information.
string
Package string defines functions that manipulate strings, it's intended to be a drop-in subset of Python's string module for Starlark.
 Package string defines functions that manipulate strings, it's intended to be a drop-in subset of Python's string 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.