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 ¶
- func DisableGlobalReassign()
- func DisableRecursionSupport()
- func EnableGlobalReassign()
- func EnableRecursionSupport()
- func GetAllBuiltinModuleNames() []string
- func RunFile(name string, fileSys fs.FS, extras StringAnyMap) (*Machine, StringAnyMap, error)
- func RunScript(content []byte, extras StringAnyMap) (*Machine, StringAnyMap, error)
- func RunTrustedFile(name string, fileSys fs.FS, globals, extras StringAnyMap) (*Machine, StringAnyMap, error)
- func RunTrustedScript(content []byte, globals, extras StringAnyMap) (*Machine, StringAnyMap, error)
- type ByteCache
- type ExecError
- type LoadFunc
- type Machine
- func NewDefault() *Machine
- func NewWithBuiltins(globals StringAnyMap, additionalPreload ModuleLoaderList, ...) *Machine
- func NewWithGlobals(globals StringAnyMap) *Machine
- func NewWithLoaders(globals StringAnyMap, preload ModuleLoaderList, lazyload ModuleLoaderMap) *Machine
- func NewWithNames(globals StringAnyMap, preloads []string, lazyloads []string) *Machine
- func (m *Machine) AddGlobals(globals StringAnyMap)
- func (m *Machine) AddLazyloadModules(mods ModuleLoaderMap)
- func (m *Machine) AddPreloadModules(mods ModuleLoaderList)
- func (m *Machine) Call(name string, args ...interface{}) (out interface{}, err error)
- func (m *Machine) DisableGlobalReassign()
- func (m *Machine) DisableRecursionSupport()
- func (m *Machine) EnableGlobalReassign()
- func (m *Machine) EnableRecursionSupport()
- func (m *Machine) Export() StringAnyMap
- func (m *Machine) GetGlobals() StringAnyMap
- func (m *Machine) GetLazyloadModules() ModuleLoaderMap
- func (m *Machine) GetPreloadModules() ModuleLoaderList
- func (m *Machine) GetStarlarkPredeclared() starlark.StringDict
- func (m *Machine) GetStarlarkThread() *starlark.Thread
- func (m *Machine) GetThreadLocal(key string) interface{}
- func (m *Machine) REPL()
- func (m *Machine) Reset()
- func (m *Machine) Run() (StringAnyMap, error)
- func (m *Machine) RunFile(name string, fileSys fs.FS, extras StringAnyMap) (StringAnyMap, error)
- func (m *Machine) RunScript(content []byte, extras StringAnyMap) (StringAnyMap, error)
- func (m *Machine) RunWithContext(ctx context.Context, extras StringAnyMap) (StringAnyMap, error)
- func (m *Machine) RunWithTimeout(timeout time.Duration, extras StringAnyMap) (StringAnyMap, error)
- func (m *Machine) SetCustomTag(tag string)
- func (m *Machine) SetGlobals(globals StringAnyMap)
- func (m *Machine) SetInputConversionEnabled(enabled bool)
- func (m *Machine) SetLazyloadModules(mods ModuleLoaderMap)
- func (m *Machine) SetOutputConversionEnabled(enabled bool)
- func (m *Machine) SetPreloadModules(mods ModuleLoaderList)
- func (m *Machine) SetPrintFunc(printFunc PrintFunc)
- func (m *Machine) SetScript(name string, content []byte, fileSys fs.FS)
- func (m *Machine) SetScriptCache(cache ByteCache)
- func (m *Machine) SetScriptCacheEnabled(enabled bool)
- func (m *Machine) SetScriptContent(content []byte)
- func (m *Machine) String() string
- type MemoryCache
- type ModuleLoader
- func GetBuiltinModule(name string) ModuleLoader
- func MakeModuleLoaderFromFile(name string, fileSys fs.FS, predeclared starlark.StringDict) ModuleLoader
- func MakeModuleLoaderFromMap(m StringAnyMap) ModuleLoader
- func MakeModuleLoaderFromReader(name string, rd io.Reader, predeclared starlark.StringDict) ModuleLoader
- func MakeModuleLoaderFromString(name, source string, predeclared starlark.StringDict) ModuleLoader
- func MakeModuleLoaderFromStringDict(d starlark.StringDict) ModuleLoader
- type ModuleLoaderList
- type ModuleLoaderMap
- type NamedModuleLoader
- type PrintFunc
- type StringAnyMap
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
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.
type LoadFunc ¶
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 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 ¶
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
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
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
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
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
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 ¶
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 ¶
SetScript sets the script related things of the Starlark runtime environment.
func (*Machine) SetScriptCache ¶ added in v0.0.8
SetScriptCache sets the cache for compiled Starlark programs.
func (*Machine) SetScriptCacheEnabled ¶ added in v0.0.8
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
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.
type MemoryCache ¶ added in v0.0.8
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.
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 ¶
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. It returns an empty map if the current data store is nil.
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 ¶
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. |
types
Package types provides wrappers for Starlark types that can be unpacked by the Unpack helper functions to interpret call arguments.
|
Package types provides wrappers for Starlark types that can be unpacked by the Unpack helper functions to interpret call arguments. |
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. |