API Reference

This page documents the public functions and options in the risor package.

Functions

risor.Eval

func Eval(ctx context.Context, source string, opts ...Option) (any, error)

Compiles and executes a Risor script in a single call. Returns the result of the last expression in the script, converted to a native Go value.

result, err := risor.Eval(ctx, `[1, 2, 3].map(x => x * 2)`)

risor.Compile

func Compile(ctx context.Context, source string, opts ...Option) (*vm.Code, error)

Compiles a Risor script to bytecode without executing it. The returned *vm.Code is safe for concurrent use across goroutines. The environment provided at compile time determines which names are available during compilation.

code, err := risor.Compile(ctx, source, risor.WithEnv(risor.Builtins()))

risor.Run

func Run(ctx context.Context, code *vm.Code, opts ...Option) (any, error)

Executes previously compiled bytecode. Each call creates a new VM instance, so the same *vm.Code can be run concurrently.

result, err := risor.Run(ctx, code, risor.WithEnv(env))

risor.Builtins

func Builtins() map[string]any

Returns a map containing all of Risor's standard built-in functions. This map can be modified before being passed as an environment.

env := risor.Builtins()
env["custom_var"] = 42
result, err := risor.Eval(ctx, source, risor.WithEnv(env))

Options

Options configure the behavior of Eval, Compile, and Run. Multiple options can be combined in a single call.

risor.WithEnv

risor.WithEnv(env map[string]any)

Provides an environment map to the script. Multiple WithEnv calls are additive; if the same key appears more than once, the last value wins.

risor.WithFilename

risor.WithFilename(name string)

Sets the filename used in error messages and stack traces. Useful when evaluating scripts loaded from files.

risor.WithObserver

risor.WithObserver(obs vm.Observer)

Attaches an execution observer that receives callbacks during VM execution. See the Observer page for details.

risor.WithTypeRegistry

risor.WithTypeRegistry(registry *TypeRegistry)

Provides a custom type registry for converting between Go and Risor types. See the Type Registry page for details.

risor.WithRawResult

risor.WithRawResult()

When set, Eval and Run return the raw object.Object instead of converting the result to a native Go value. This is useful when you need access to the Risor type system directly.

risor.WithMaxSteps

risor.WithMaxSteps(n int64)

Limits the total number of bytecode instructions the VM will execute. A value of 0 means unlimited. If the limit is exceeded, an ErrStepLimitExceeded error is returned. See Resource Limits.

risor.WithMaxStackDepth

risor.WithMaxStackDepth(depth int)

Limits the maximum call stack depth. If the limit is exceeded, an ErrStackOverflow error is returned. See Resource Limits.

risor.WithTimeout

risor.WithTimeout(d time.Duration)

Sets an execution timeout. If the timeout is exceeded, a context.DeadlineExceeded error is returned. See Resource Limits.

risor.WithSyntax

risor.WithSyntax(config SyntaxConfig)

Restricts which language constructs are allowed. Risor provides three built-in presets: ExpressionOnly, BasicScripting, and FullLanguage. See Syntax Restriction.

risor.WithValidator

risor.WithValidator(v ast.Validator)

Provides a custom AST validator that runs after parsing. The validator can reject scripts that use disallowed constructs.

risor.WithTransform

risor.WithTransform(t ast.Transformer)

Provides a custom AST transformer that runs after parsing and validation. The transformer can modify the AST before compilation.

Result Conversion

When a script finishes, the result is converted from the Risor type system to native Go types. The following table shows the default conversions.

For types not listed above, the result is the string returned by the object's Inspect() method. To receive the raw object.Object value instead, use the WithRawResult() option.