Documentation
¶
Overview ¶
Package embed provides a lightweight, dependency-minimal API for embedding the Rye scripting language in Go applications.
Build tags ¶
This sub-module is always built with the two tags below, which exclude optional heavy batteries from the dependency graph:
no_baseio – exclude OS/filesystem/terminal I/O builtins and their deps
(fsnotify, keyboard, seccomp, landlock, yaml, …)
no_vector – exclude govector / primes math extensions
The only external dependencies added to a consuming project are:
golang.org/x/text – unicode case-folding (builtins_base_strings) golang.org/x/crypto – PBKDF2 (util/securesave)
Quick start ¶
engine := embed.New()
engine.RegisterBuiltin("double", 1, func(ps *env.ProgramState, a0, _, _, _, _ env.Object) env.Object {
return *env.NewInteger(a0.(env.Integer).Value * 2)
})
result, err := engine.Eval(`double 21`)
fmt.Println(result) // 42
Index ¶
- type BuiltinFn
- type Engine
- func (e *Engine) Eval(code string) (string, error)
- func (e *Engine) EvalBool(code string) (bool, error)
- func (e *Engine) EvalBytes(src []byte) (string, error)
- func (e *Engine) EvalDecimal(code string) (float64, error)
- func (e *Engine) EvalGetObject(code string) (env.Object, error)
- func (e *Engine) EvalInteger(code string) (int64, error)
- func (e *Engine) EvalString(code string) (string, error)
- func (e *Engine) GetWord(name string) (env.Object, bool)
- func (e *Engine) ProgramState() *env.ProgramState
- func (e *Engine) RegisterBuiltin(name string, argCount int, fn BuiltinFn)
- func (e *Engine) RegisterBuiltinDoc(name string, argCount int, doc string, fn BuiltinFn)
- func (e *Engine) Reset()
- func (e *Engine) SetVar(name string, val env.Object)
- func (e *Engine) SetWord(name string, val env.Object)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BuiltinFn ¶
type BuiltinFn = env.BuiltinFunction
BuiltinFn is the Go function signature required by Rye builtins. ps is the running program state; a0–a4 are positional arguments. Unused argument slots receive env.Void{}.
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine is a single Rye interpreter instance with its own word index and execution context. Create one with New or NewBlank.
func New ¶
func New() *Engine
New creates an Engine pre-loaded with all base Rye builtins (arithmetic, strings, collections, control flow, …) but WITHOUT OS-level I/O (no file access, no shell commands, no os.Exit, no os.Args). This keeps the embedded sandbox safe by default. If you need file/shell access in the embedded engine, call baseio.Register(engine.ProgramState()) after New(). Register additional Go functions with Engine.RegisterBuiltin.
func NewBlank ¶
func NewBlank() *Engine
NewBlank creates an Engine with NO pre-registered builtins. Useful when you want complete control over the available vocabulary.
func (*Engine) Eval ¶
Eval parses and evaluates Rye source code. Returns the result serialised as a human-readable string, or an error if parsing or evaluation fails.
func (*Engine) EvalBool ¶
EvalBool evaluates code and returns the result as a Go bool. Returns an error if the result is not a Rye Integer with value 0 or 1 (Rye's boolean representation).
func (*Engine) EvalBytes ¶
EvalBytes is a convenience wrapper that evaluates a []byte source. Useful when the script is read from a file:
src, _ := os.ReadFile("config.rye")
result, err := engine.EvalBytes(src)
func (*Engine) EvalDecimal ¶
EvalDecimal evaluates code and returns the result as a Go float64. Returns an error if the result is not a Rye Decimal.
func (*Engine) EvalGetObject ¶
EvalGetObject parses and evaluates Rye source code and returns the raw env.Object result. Callers can type-assert to env.Integer, env.String, env.Block, etc.
func (*Engine) EvalInteger ¶
EvalInteger evaluates code and returns the result as a Go int64. Returns an error if the result is not a Rye Integer.
func (*Engine) EvalString ¶
EvalString evaluates code and returns the result as a Go string. Returns an error if the result is not a Rye String.
func (*Engine) GetWord ¶
GetWord retrieves the value of a Rye word from the current context. Returns (nil, false) if the word has not been set.
func (*Engine) ProgramState ¶
func (e *Engine) ProgramState() *env.ProgramState
ProgramState returns the underlying *env.ProgramState for advanced integration (e.g. reading back Rye values, inspecting the word index, registering context-aware builtins manually).
func (*Engine) RegisterBuiltin ¶
RegisterBuiltin registers a Go function as a Rye builtin word.
- name – the Rye word (e.g. "greet", "db-query")
- argCount – number of arguments the function accepts (0–5)
- fn – the Go implementation (signature: BuiltinFn)
func (*Engine) RegisterBuiltinDoc ¶
RegisterBuiltinDoc is like Engine.RegisterBuiltin but also attaches a documentation string visible via the Rye `doc` word.
func (*Engine) Reset ¶
func (e *Engine) Reset()
Reset re-initialises the engine with a fresh context and re-registers all base Rye builtins (no OS I/O, matching the behaviour of New). Custom builtins registered with RegisterBuiltin are removed - call RegisterBuiltin again to re-add them, or use New to create a fresh engine.
func (*Engine) SetVar ¶
SetVar injects a Rye word as a mutable variable into the current context. Unlike Engine.SetWord, the Rye script can modify this value using the modword operator (word::).
Example:
engine.SetVar("score", *env.NewInteger(0))
engine.Eval(`score:: score + 10`) // score is now 10
val, _ := engine.GetWord("score")
func (*Engine) SetWord ¶
SetWord injects a Rye word as a constant into the current context. The word cannot be modified by Rye scripts (it is not a variable). Use Engine.SetVar when you need the script to be able to modify the value.
Example:
engine.SetWord("port", *env.NewInteger(8080))
engine.Eval(`print "listening on port" + string port`)
Source Files