Documentation
¶
Index ¶
- func Get(script string) (*ast.Program, bool)
- func GetKey(script string) (cacheKey, *ast.Program, bool)
- func Set(script string, program *ast.Program)
- func SetWithKey(key cacheKey, script string, program *ast.Program)
- type ContextLibraryLoader
- type Kwargs
- type LibraryLoader
- type Scriptling
- func (p *Scriptling) CallFunction(name string, args ...interface{}) (object.Object, error)
- func (p *Scriptling) CallFunctionWithContext(ctx context.Context, name string, args ...interface{}) (object.Object, error)
- func (p *Scriptling) CallMethod(obj object.Object, methodName string, args ...interface{}) (object.Object, error)
- func (p *Scriptling) CallMethodWithContext(ctx context.Context, obj object.Object, methodName string, args ...interface{}) (object.Object, error)
- func (p *Scriptling) Clone() *Scriptling
- func (p *Scriptling) CreateInstance(className string, args ...interface{}) (object.Object, error)
- func (p *Scriptling) CreateInstanceWithContext(ctx context.Context, className string, args ...interface{}) (object.Object, error)
- func (p *Scriptling) EnableOutputCapture()
- func (p *Scriptling) Eval(input string) (object.Object, error)
- func (p *Scriptling) EvalFile(path string) (object.Object, error)
- func (p *Scriptling) EvalWithContext(ctx context.Context, input string) (result object.Object, err error)
- func (p *Scriptling) EvalWithTimeout(timeout time.Duration, input string) (object.Object, error)
- func (p *Scriptling) GetLibraryLoader() LibraryLoader
- func (p *Scriptling) GetOutput() string
- func (p *Scriptling) GetVar(name string) (interface{}, object.Object)
- func (p *Scriptling) GetVarAsBool(name string) (bool, object.Object)
- func (p *Scriptling) GetVarAsDict(name string) (map[string]object.Object, object.Object)
- func (p *Scriptling) GetVarAsFloat(name string) (float64, object.Object)
- func (p *Scriptling) GetVarAsInt(name string) (int64, object.Object)
- func (p *Scriptling) GetVarAsList(name string) ([]object.Object, object.Object)
- func (p *Scriptling) GetVarAsObject(name string) (object.Object, error)
- func (p *Scriptling) GetVarAsSet(name string) (*object.Set, object.Object)
- func (p *Scriptling) GetVarAsString(name string) (string, object.Object)
- func (p *Scriptling) GetVarAsTuple(name string) ([]object.Object, object.Object)
- func (p *Scriptling) HasLibrary(name string) bool
- func (p *Scriptling) Import(names interface{}) error
- func (p *Scriptling) ImportWithContext(ctx context.Context, names interface{}) error
- func (p *Scriptling) ListVars() []string
- func (p *Scriptling) LoadLibraryIntoEnv(name string, env *object.Environment) error
- func (p *Scriptling) LoadLibraryIntoEnvWithContext(ctx context.Context, name string, env *object.Environment) error
- func (p *Scriptling) RegisterFunc(name string, ...)
- func (p *Scriptling) RegisterLibrary(lib *object.Library)
- func (p *Scriptling) RegisterScriptFunc(name string, script string) error
- func (p *Scriptling) RegisterScriptLibrary(name string, script string) error
- func (p *Scriptling) Reset()
- func (p *Scriptling) ResetEnv(keepKeys ...string)
- func (p *Scriptling) SetErrorWriter(w io.Writer)
- func (p *Scriptling) SetInputReader(r io.Reader)
- func (p *Scriptling) SetLibraryLoader(loader LibraryLoader)
- func (p *Scriptling) SetObjectVar(name string, obj object.Object) error
- func (p *Scriptling) SetOutputWriter(w io.Writer)
- func (p *Scriptling) SetSourceFile(name string)
- func (p *Scriptling) SetVar(name string, value interface{}) error
- func (p *Scriptling) UnregisterLibrary(name string)
- func (p *Scriptling) UnregisterScriptLibrary(name string)
- func (p *Scriptling) UnsetVar(name string)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GetKey ¶ added in v0.5.5
GetKey retrieves the cache key and cached program by script content. For normal cache entries this avoids hashing the full script on a miss.
func SetWithKey ¶ added in v0.5.5
SetWithKey stores a program in the cache using a previously computed key. This path is kept for compatibility; the normal parser path now uses Set().
Types ¶
type ContextLibraryLoader ¶ added in v0.23.0
type ContextLibraryLoader interface {
LoadWithContext(ctx context.Context, name string) (source string, found bool, err error)
}
ContextLibraryLoader is an optional extension for loaders that support caller cancellation, deadlines, or context values.
type Kwargs ¶
type Kwargs map[string]interface{}
Kwargs is a wrapper type to explicitly pass keyword arguments to CallFunction. Use this to distinguish between a map being passed as a dict argument vs kwargs.
type LibraryLoader ¶ added in v0.2.9
type LibraryLoader interface {
Load(name string) (source string, found bool, err error)
Description() string
}
LibraryLoader is the interface for loading libraries from various sources. This is an alias for the libloader.LibraryLoader interface to avoid import cycles.
type Scriptling ¶
type Scriptling struct {
// contains filtered or unexported fields
}
func New ¶
func New() *Scriptling
func (*Scriptling) CallFunction ¶
func (p *Scriptling) CallFunction(name string, args ...interface{}) (object.Object, error)
CallFunction calls a registered function by name with Go arguments. Args are Go types (int, string, etc.) that will be converted to Object. Returns object.Object - use .AsInt(), .AsString(), etc. to extract value.
Works with both Go-registered functions (via RegisterFunc) and script-defined functions.
To pass a map as a dict argument, use map[string]interface{} directly. To pass keyword arguments, wrap the map in Kwargs{}.
Example:
p.RegisterFunc("add", addFunc)
result, err := p.CallFunction("add", 10, 32)
sum, _ := result.AsInt()
// Pass a map as a dict argument
dataMap := map[string]interface{}{"key": "value"}
result, err := p.CallFunction("process", dataMap)
// With keyword arguments (use Kwargs wrapper)
result, err := p.CallFunction("format", "value", Kwargs{"prefix": ">>"})
func (*Scriptling) CallFunctionWithContext ¶
func (p *Scriptling) CallFunctionWithContext(ctx context.Context, name string, args ...interface{}) (object.Object, error)
CallFunctionWithContext calls a registered function by name with Go arguments and a context. The context can be used for cancellation or timeouts. Args are Go types (int, string, etc.) that will be converted to Object. Returns object.Object - use .AsInt(), .AsString(), etc. to extract value.
Works with both Go-registered functions (via RegisterFunc) and script-defined functions.
To pass a map as a dict argument, use map[string]interface{} directly. To pass keyword arguments, wrap the map in Kwargs{}.
Example:
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
result, err := p.CallFunctionWithContext(ctx, "add", 10, 32)
sum, _ := result.AsInt()
// Pass a map as a dict argument
dataMap := map[string]interface{}{"key": "value"}
result, err := p.CallFunctionWithContext(ctx, "process", dataMap)
// With keyword arguments (use Kwargs wrapper)
result, err := p.CallFunctionWithContext(ctx, "format", "value", Kwargs{"prefix": ">>"})
func (*Scriptling) CallMethod ¶
func (p *Scriptling) CallMethod(obj object.Object, methodName string, args ...interface{}) (object.Object, error)
CallMethod calls a method on a Scriptling object (typically an Instance). The obj should be an object.Object (usually obtained from CreateInstance or script evaluation). Args are Go types that will be converted to Object. Returns object.Object - use .AsInt(), .AsString(), etc. to extract value.
Example:
instance, _ := p.CreateInstance("Counter", 10)
result, err := p.CallMethod(instance, "increment")
value, _ := result.AsInt()
func (*Scriptling) CallMethodWithContext ¶
func (p *Scriptling) CallMethodWithContext(ctx context.Context, obj object.Object, methodName string, args ...interface{}) (object.Object, error)
CallMethodWithContext calls a method on a Scriptling object with a context. The context can be used for cancellation or timeouts.
Example:
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
instance, _ := p.CreateInstance("Counter", 10)
result, err := p.CallMethodWithContext(ctx, instance, "increment")
func (*Scriptling) Clone ¶ added in v0.2.0
func (p *Scriptling) Clone() *Scriptling
Clone creates a new Scriptling interpreter that shares library registrations (both Go and script libraries) with the parent but starts with a fresh, isolated environment. Already-imported libraries are NOT copied; each clone re-evaluates script libraries on first import, so no mutable state is shared. Useful for per-request / multi-tenant isolation.
func (*Scriptling) CreateInstance ¶
func (p *Scriptling) CreateInstance(className string, args ...interface{}) (object.Object, error)
CreateInstance creates an instance of a Scriptling class and returns it as an object.Object. The className should be the name of a class defined in the script or registered via a library. Args are Go types that will be converted to Object and passed to __init__.
Example:
p.Eval("class Counter:\n def __init__(self, start=0):\n self.value = start")
instance, err := p.CreateInstance("Counter", 10)
if err != nil {
// handle error
}
// Now you can use CallMethod on this instance
func (*Scriptling) CreateInstanceWithContext ¶
func (p *Scriptling) CreateInstanceWithContext(ctx context.Context, className string, args ...interface{}) (object.Object, error)
CreateInstanceWithContext creates an instance of a Scriptling class with a context. The context can be used for cancellation or timeouts.
Example:
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) defer cancel() instance, err := p.CreateInstanceWithContext(ctx, "Counter", 10)
func (*Scriptling) EnableOutputCapture ¶
func (p *Scriptling) EnableOutputCapture()
EnableOutputCapture enables capturing print output instead of sending to stdout
func (*Scriptling) Eval ¶
func (p *Scriptling) Eval(input string) (object.Object, error)
Eval executes script without timeout (backwards compatible)
func (*Scriptling) EvalFile ¶ added in v0.2.0
func (p *Scriptling) EvalFile(path string) (object.Object, error)
EvalFile reads a file from disk and evaluates it.
func (*Scriptling) EvalWithContext ¶
func (p *Scriptling) EvalWithContext(ctx context.Context, input string) (result object.Object, err error)
EvalWithContext executes script with context for timeout/cancellation. This method is safe against deep recursion (via call depth tracking) and recovers from panics during script execution.
func (*Scriptling) EvalWithTimeout ¶
EvalWithTimeout executes script with timeout
func (*Scriptling) GetLibraryLoader ¶ added in v0.4.0
func (p *Scriptling) GetLibraryLoader() LibraryLoader
GetLibraryLoader returns the current library loader, or nil if none is set.
func (*Scriptling) GetOutput ¶
func (p *Scriptling) GetOutput() string
GetOutput returns captured output and clears the buffer
func (*Scriptling) GetVarAsBool ¶
func (p *Scriptling) GetVarAsBool(name string) (bool, object.Object)
func (*Scriptling) GetVarAsDict ¶
func (*Scriptling) GetVarAsFloat ¶
func (p *Scriptling) GetVarAsFloat(name string) (float64, object.Object)
func (*Scriptling) GetVarAsInt ¶
func (p *Scriptling) GetVarAsInt(name string) (int64, object.Object)
func (*Scriptling) GetVarAsList ¶
func (*Scriptling) GetVarAsObject ¶
func (p *Scriptling) GetVarAsObject(name string) (object.Object, error)
GetVarAsObject retrieves a variable from the environment as a scriptling Object.
func (*Scriptling) GetVarAsSet ¶ added in v0.2.0
func (*Scriptling) GetVarAsString ¶
func (p *Scriptling) GetVarAsString(name string) (string, object.Object)
Convenience methods for type-safe variable access
func (*Scriptling) GetVarAsTuple ¶ added in v0.2.0
func (*Scriptling) HasLibrary ¶ added in v0.23.0
func (p *Scriptling) HasLibrary(name string) bool
HasLibrary reports whether a library (native or script) is registered under the given name. The plugin loader uses it to refuse a plugin whose declared name collides with a library the host already has.
func (*Scriptling) Import ¶
func (p *Scriptling) Import(names interface{}) error
Import imports a library into the current environment, making it available for use without needing an import statement in scripts.
func (*Scriptling) ImportWithContext ¶ added in v0.23.0
func (p *Scriptling) ImportWithContext(ctx context.Context, names interface{}) error
ImportWithContext imports one or more libraries while preserving caller cancellation, deadlines, and values through dynamic loading and evaluation.
func (*Scriptling) ListVars ¶ added in v0.2.0
func (p *Scriptling) ListVars() []string
ListVars returns a sorted list of variable names in the current environment, excluding internal names (import builtin).
func (*Scriptling) LoadLibraryIntoEnv ¶
func (p *Scriptling) LoadLibraryIntoEnv(name string, env *object.Environment) error
LoadLibraryIntoEnv loads a library into the specified environment. This is useful for loading libraries into cloned environments for background tasks. Returns an error if the library cannot be loaded.
func (*Scriptling) LoadLibraryIntoEnvWithContext ¶ added in v0.23.0
func (p *Scriptling) LoadLibraryIntoEnvWithContext(ctx context.Context, name string, env *object.Environment) error
LoadLibraryIntoEnvWithContext loads a library into an environment while preserving caller context through nested evaluation and dynamic loading.
func (*Scriptling) RegisterFunc ¶
func (*Scriptling) RegisterLibrary ¶
func (p *Scriptling) RegisterLibrary(lib *object.Library)
RegisterLibrary registers a new library that can be imported by scripts The library name is extracted from the library itself
func (*Scriptling) RegisterScriptFunc ¶
func (p *Scriptling) RegisterScriptFunc(name string, script string) error
RegisterScriptFunc registers a function written in Scriptling The script should define a function and this method will extract it and register it by name
func (*Scriptling) RegisterScriptLibrary ¶
func (p *Scriptling) RegisterScriptLibrary(name string, script string) error
RegisterScriptLibrary registers a library written in Scriptling The script should define functions/values that will be available when the library is imported
func (*Scriptling) Reset ¶ added in v0.17.1
func (p *Scriptling) Reset()
Reset restores the environment to a pristine state suitable for evaluating an unrelated script, with no need for the caller to enumerate which bindings to keep. It is the no-argument counterpart to ResetEnv and is intended for reusing a Scriptling instance across independent scripts — for example, from a pool — without paying the cost of New() plus library registration again.
What Reset preserves:
- Registered libraries (both Go-registered and script-registered). They are not unregistered; the next Eval re-imports any that the script needs.
- The "import" builtin and the configured library loader.
What Reset clears:
- Every global binding created by the most recent Eval: variables, functions, classes, and the dicts bound by previous imports. Libraries are re-imported on demand by the next script (import dedup is keyed on the binding store, so clearing the store re-enables import).
- __file__ (set by EvalFile). __name__ is restored to "__main__".
- Any output captured since the last GetOutput() call.
Reset does NOT preserve a specific import set. If a caller needs certain libraries to remain imported across resets, either re-issue the import after Reset or use ResetEnv(keepKeys...) to keep named bindings.
func (*Scriptling) ResetEnv ¶ added in v0.2.7
func (p *Scriptling) ResetEnv(keepKeys ...string)
ResetEnv clears all user-defined variables from the environment, keeping only the listed keys (plus the "import" builtin which is always preserved). Imported library dicts remain if their names are passed in keepKeys. This allows VM reuse across requests without re-registering libraries.
func (*Scriptling) SetErrorWriter ¶ added in v0.21.0
func (p *Scriptling) SetErrorWriter(w io.Writer)
SetErrorWriter sets a custom writer for error/diagnostic output written via sys.stderr (e.g., for streaming warnings to a separate log)
func (*Scriptling) SetInputReader ¶
func (p *Scriptling) SetInputReader(r io.Reader)
SetInputReader sets a custom reader for input (e.g., for reading from a websocket)
func (*Scriptling) SetLibraryLoader ¶ added in v0.2.9
func (p *Scriptling) SetLibraryLoader(loader LibraryLoader)
SetLibraryLoader sets a loader for dynamically loading libraries. This is the preferred way to load libraries from various sources (filesystem, API, etc.) using the libloader package.
Example:
loader := libloader.NewChain(
libloader.NewFilesystem("/app/libs"),
libloader.NewAPI("https://api.example.com/libs"),
)
p.SetLibraryLoader(loader)
func (*Scriptling) SetObjectVar ¶
func (p *Scriptling) SetObjectVar(name string, obj object.Object) error
SetObjectVar sets a variable in the environment from a scriptling Object. This is useful when you already have a scriptling object (like an Instance) and want to set it directly without converting from Go types.
func (*Scriptling) SetOutputWriter ¶
func (p *Scriptling) SetOutputWriter(w io.Writer)
SetOutputWriter sets a custom writer for output (e.g., for streaming to a websocket or logger)
func (*Scriptling) SetSourceFile ¶
func (p *Scriptling) SetSourceFile(name string)
SetSourceFile sets the source file name used in error messages and sets the __file__ and __name__ variables in the script environment. When a script file is set, __name__ is set to "__main__".
func (*Scriptling) SetVar ¶
func (p *Scriptling) SetVar(name string, value interface{}) error
func (*Scriptling) UnregisterLibrary ¶ added in v0.12.1
func (p *Scriptling) UnregisterLibrary(name string)
UnregisterLibrary removes a registered Go library and any imported binding from the current environment.
func (*Scriptling) UnregisterScriptLibrary ¶ added in v0.12.1
func (p *Scriptling) UnregisterScriptLibrary(name string)
UnregisterScriptLibrary removes a registered Scriptling library and any imported binding from the current environment.
func (*Scriptling) UnsetVar ¶ added in v0.2.0
func (p *Scriptling) UnsetVar(name string)
UnsetVar removes a variable from the current environment.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package build contains build-time version information for Scriptling
|
Package build contains build-time version information for Scriptling |
|
Package evaliface provides an interface for calling functions from libraries without creating circular dependencies
|
Package evaliface provides an interface for calling functions from libraries without creating circular dependencies |
|
examples
|
|
|
call_method
command
|
|
|
embed-fetcher-plugin
command
embed-fetcher-plugin shows a host application embedding scriptling with fetcher plugins enabled: scripts and libraries are pulled from a plugin over the plugin protocol, on demand, with nothing on the local filesystem.
|
embed-fetcher-plugin shows a host application embedding scriptling with fetcher plugins enabled: scripts and libraries are pulled from a plugin over the plugin protocol, on demand, with nothing on the local filesystem. |
|
extending
command
|
|
|
mcp-client/direct
command
|
|
|
mcp-client/shared
command
|
|
|
mcp-client/with-openai
command
|
|
|
mcp-client/with-openai-instance
command
|
|
|
multi-environment
command
|
|
|
openai/shared
command
|
|
|
plugins/callback
command
|
|
|
plugins/fetcher-go
command
fetcher-go is the full-example plugin: it registers a function and a class like any Go plugin (importable as plugin.demo), and additionally serves a fetcher — the one RegisterFetcher("demo", ...) call — so the same plugin owns the demo:// scheme.
|
fetcher-go is the full-example plugin: it registers a function and a class like any Go plugin (importable as plugin.demo), and additionally serves a fetcher — the one RegisterFetcher("demo", ...) call — so the same plugin owns the demo:// scheme. |
|
plugins/hello-go
command
|
|
|
plugins/http-go
command
|
|
|
plugins/logger
command
|
|
|
plugins/mixed-wrapper
command
|
|
|
plugins/properties
command
|
|
|
script-metadata
command
script-metadata shows an embedding host checking a script's inline metadata block before running it: parse the block, verify it against the host's real environment — the host's own version, the libraries and loaders it wired up, the plugins it loaded — and refuse to run anything with unmet requirements.
|
script-metadata shows an embedding host checking a script's inline metadata block before running it: parse the block, verify it against the host's real environment — the host's own version, the libraries and loaders it wired up, the plugins it loaded — and refuse to run anything with unmet requirements. |
|
Package extlibs provides external libraries that need explicit registration
|
Package extlibs provides external libraries that need explicit registration |
|
console
Example demonstrating the module-level console API and how background tasks can access the shared TUI.
|
Example demonstrating the module-level console API and how background tasks can access the shared TUI. |
|
netsecurity
Package netsecurity restricts outbound network access for script-facing libraries (requests, wait_for, websocket).
|
Package netsecurity restricts outbound network access for script-facing libraries (requests, wait_for, websocket). |
|
nomad
Package nomad implements the scriptling.nomad extended library: a thin client over the HashiCorp Nomad HTTP API covering CSI volumes and jobs.
|
Package nomad implements the scriptling.nomad extended library: a thin client over the HashiCorp Nomad HTTP API covering CSI volumes and jobs. |
|
Package libloader provides a flexible library loading system for Scriptling.
|
Package libloader provides a flexible library loading system for Scriptling. |
|
Package lint provides code analysis functionality for Scriptling scripts.
|
Package lint provides code analysis functionality for Scriptling scripts. |
|
Package metadata parses and verifies PEP 723-style inline script metadata: a TOML block carried in comments before a script's first statement.
|
Package metadata parses and verifies PEP 723-style inline script metadata: a TOML block carried in comments before a script's first statement. |
|
plugins
|
|
|
badgerdb
Package badgerdb is the BadgerDB embedded key-value plugin.
|
Package badgerdb is the BadgerDB embedded key-value plugin. |
|
badgerdb/cmd
command
Command badgerdb serves the BadgerDB plugin over the Scriptling plugin protocol (stdio JSON-RPC).
|
Command badgerdb serves the BadgerDB plugin over the Scriptling plugin protocol (stdio JSON-RPC). |
|
internal/kv
Package kv provides the shared key/value client class used by the valkey and badgerdb plugins.
|
Package kv provides the shared key/value client class used by the valkey and badgerdb plugins. |
|
internal/kwarg
Package kwarg converts object-side argument errors into Go errors, for typed class constructors whose signatures require an error return.
|
Package kwarg converts object-side argument errors into Go errors, for typed class constructors whose signatures require an error return. |
|
internal/plugintest
Package plugintest drives database plugins in external mode: it builds the plugin's cmd binary, loads it through a Manager (handshake, policy, script-shim connect wrappers, object protocol) and evaluates a script against it — the full wire path a real deployment uses.
|
Package plugintest drives database plugins in external mode: it builds the plugin's cmd binary, loads it through a Manager (handshake, policy, script-shim connect wrappers, object protocol) and evaluates a script against it — the full wire path a real deployment uses. |
|
internal/relational
Package relational provides the shared Connection and Transaction classes used by the database plugins (sqlite, sql).
|
Package relational provides the shared Connection and Transaction classes used by the database plugins (sqlite, sql). |
|
sql
Package sql is the network relational database plugin covering MySQL, MariaDB and PostgreSQL.
|
Package sql is the network relational database plugin covering MySQL, MariaDB and PostgreSQL. |
|
sql/cmd
command
Command sql serves the MySQL/MariaDB/PostgreSQL plugin over the Scriptling plugin protocol (stdio JSON-RPC).
|
Command sql serves the MySQL/MariaDB/PostgreSQL plugin over the Scriptling plugin protocol (stdio JSON-RPC). |
|
sqlite
Package sqlite is the sqlite database plugin.
|
Package sqlite is the sqlite database plugin. |
|
sqlite/cmd
command
Command sqlite serves the sqlite database plugin over the Scriptling plugin protocol (stdio JSON-RPC).
|
Command sqlite serves the sqlite database plugin over the Scriptling plugin protocol (stdio JSON-RPC). |
|
valkey
Package valkey is the valkey/redis key-value plugin.
|
Package valkey is the valkey/redis key-value plugin. |
|
valkey/cmd
command
Command valkey serves the valkey/redis plugin over the Scriptling plugin protocol (stdio JSON-RPC).
|
Command valkey serves the valkey/redis plugin over the Scriptling plugin protocol (stdio JSON-RPC). |
|
pluginpack
Package pluginpack bridges fetcher plugins into the pack scheme registry: every loaded plugin that advertises the fetch capability gets its schemes registered, so knot://libs as a --package value (or as a script source) resolves to a bundle whose files are fetched on demand over the plugin protocol.
|
Package pluginpack bridges fetcher plugins into the pack scheme registry: every loaded plugin that advertises the fetch capability gets its schemes registered, so knot://libs as a --package value (or as a script source) resolves to a bundle whose files are fetched on demand over the plugin protocol. |
|
scripts
|
|
|
homebrew-formula
command
|
|
|
tools
|
|
|
echo
command
|
|
|
getversion
command
|
|