Documentation
¶
Overview ¶
Package embed provides a high-level API for embedding AILANG in Go programs.
This package simplifies using AILANG as a scripting/extension language within Go applications. It handles module compilation, caching, and provides convenient value conversion between Go and AILANG types.
Basic usage:
engine := embed.New()
defer engine.Close()
// Load and call an AILANG function
result, err := engine.Call("my/module", "myFunction", 42, "hello")
if err != nil {
log.Fatal(err)
}
// Extract Go value
value, err := embed.ToInt(result)
Index ¶
- func FromGo(v interface{}) (eval.Value, error)
- func FromGoPreserveFloats(v interface{}) (eval.Value, error)
- func FromJSON(data []byte) (eval.Value, error)
- func IsUnit(v eval.Value) bool
- func ToBool(v eval.Value) (bool, error)
- func ToBytes(v eval.Value) ([]byte, error)
- func ToFloat(v eval.Value) (float64, error)
- func ToGo(v eval.Value) (interface{}, error)
- func ToInt(v eval.Value) (int, error)
- func ToJSON(v eval.Value) ([]byte, error)
- func ToList(v eval.Value) ([]eval.Value, error)
- func ToRecord(v eval.Value) (map[string]eval.Value, error)
- func ToString(v eval.Value) (string, error)
- type Engine
- func (e *Engine) Call(modulePath, funcName string, args ...interface{}) (eval.Value, error)
- func (e *Engine) CallJSON(modulePath, funcName string, inputJSON []byte) ([]byte, error)
- func (e *Engine) CallPreserveFloats(modulePath, funcName string, args ...interface{}) (eval.Value, error)
- func (e *Engine) Close() error
- func (e *Engine) Eval(code string) (eval.Value, error)
- func (e *Engine) GetCallValue() func(eval.Value, eval.Value) (eval.Value, error)
- func (e *Engine) GetCallValueN() func(eval.Value, []eval.Value) (eval.Value, error)
- func (e *Engine) HasExport(modulePath, name string) bool
- func (e *Engine) InvalidateModule(modulePath string)
- func (e *Engine) ListExports(modulePath string) ([]string, error)
- func (e *Engine) Load(modulePath string) error
- func (e *Engine) PreloadModule(path string, loaded *loader.LoadedModule)
- func (e *Engine) SetEffContext(ctx interface{})
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FromGo ¶
FromGo converts a Go value to an AILANG value. Supported types:
- nil → UnitValue
- bool → BoolValue
- int, int8, int16, int32, int64 → IntValue
- uint, uint8, uint16, uint32, uint64 → IntValue
- float32, float64 → FloatValue
- string → StringValue
- []byte → BytesValue
- []T → ListValue (recursive)
- map[string]T → RecordValue (recursive)
- struct → RecordValue (exported fields only)
func FromGoPreserveFloats ¶
FromGoPreserveFloats converts a Go value to an AILANG value, preserving float64 as FloatValue even for whole numbers. Use this for direct Go calls where you want float64 to remain as float (not converted to int for JSON compatibility).
func ToGo ¶
ToGo converts an AILANG value to a Go value. The result type depends on the input:
- UnitValue → nil
- BoolValue → bool
- IntValue → int
- FloatValue → float64
- StringValue → string
- BytesValue → []byte
- ListValue → []interface{}
- ArrayValue → []interface{}
- TupleValue → []interface{}
- RecordValue → map[string]interface{}
- TaggedValue → map[string]interface{} with "__tag" key
Types ¶
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine manages AILANG module compilation and execution. It caches compiled modules for efficient repeated calls.
func New ¶
New creates a new AILANG embedding engine. basePath is the root directory for resolving module imports. The basePath should be the root of the project containing both user modules and the stdlib directory.
func (*Engine) Call ¶
Call invokes an exported function from a module with the given arguments. Arguments are automatically converted from Go types to AILANG values. The module is loaded if not already cached.
func (*Engine) CallJSON ¶
CallJSON is a convenience method that accepts JSON input and returns JSON output. Useful for language-agnostic integrations.
func (*Engine) CallPreserveFloats ¶
func (e *Engine) CallPreserveFloats(modulePath, funcName string, args ...interface{}) (eval.Value, error)
CallPreserveFloats is like Call but preserves Go float64 values as AILANG FloatValue, even for whole numbers like 100.0. Use this for direct Go calls where you need float arguments to stay as floats (not be converted to int for JSON compatibility).
func (*Engine) Eval ¶
Eval compiles and evaluates AILANG code directly (not from a file). Useful for one-off expressions or REPL-like functionality.
func (*Engine) GetCallValue ¶
GetCallValue returns the evaluator's CallValue function, which can be used to invoke AILANG function values from Go code (e.g., for stream event handlers). Returns a function with signature: func(fn eval.Value, arg eval.Value) (eval.Value, error)
func (*Engine) GetCallValueN ¶
GetCallValueN returns the evaluator's CallValueN function for multi-arg callbacks. M-ITERATIVE-LIST: Used by iterative builtins (foldl, etc.) via serve-api.
func (*Engine) InvalidateModule ¶
InvalidateModule clears all caches for a module, forcing recompilation on next call. This is used by hot reload to pick up source file changes.
func (*Engine) ListExports ¶
ListExports returns the names of all exported functions/values in a module.
func (*Engine) Load ¶
Load compiles and loads a module, caching it for future calls. modulePath is the path relative to basePath (e.g., "internal/transforms/event_formatter").
func (*Engine) PreloadModule ¶
func (e *Engine) PreloadModule(path string, loaded *loader.LoadedModule)
HasExport checks if a module exports a value with the given name. PreloadModule preloads a compiled module into the runtime's loader cache. This ensures transitive dependencies are available when functions execute.
func (*Engine) SetEffContext ¶
func (e *Engine) SetEffContext(ctx interface{})
SetEffContext configures the effect context for all subsequent calls. This enables effectful AILANG functions (IO, FS, Net, AI, etc.). The ctx parameter should be an *effects.EffContext; it uses interface{} to avoid an import cycle between embed and effects packages.
Source Files