script

Documentation

Index

• func CompileString(code, name string) (*lua.FunctionProto, error)
• func SandboxSetup(scopes ...Scope) func(*lua.LState)
• type Engine
  • func NewEngine(ctx context.Context) *Engine
  • func (e *Engine) Close()
  • func (e *Engine) FireHook(event string, args ...lua.LValue)
  • func (e *Engine) Load(path string) error
  • func (e *Engine) LoadString(code, name string) error
  • func (e *Engine) RegisterAddon(name string, loader lua.LGFunction)
  • func (e *Engine) SetGlobal(name string, v lua.LValue)
• type Pool
  • func NewPool(size int, setup func(*lua.LState)) *Pool
  • func (p *Pool) Close()
  • func (p *Pool) Run(ctx context.Context, code string, env map[string]lua.LValue) ([]lua.LValue, error)
  • func (p *Pool) RunProto(ctx context.Context, proto *lua.FunctionProto, env map[string]lua.LValue) ([]lua.LValue, error)
  • func (p *Pool) WithState(ctx context.Context, fn func(*lua.LState) ([]lua.LValue, error)) ([]lua.LValue, error)
• type Scope

Functions

func CompileString

func CompileString(code, name string) (*lua.FunctionProto, error)

CompileString compiles Lua source into a reusable FunctionProto without needing a live LState. The name is used in error messages.

func SandboxSetup

func SandboxSetup(scopes ...Scope) func(*lua.LState)

SandboxSetup returns a state-initialization function that applies the requested scopes. It is intended to be passed to NewPool.

Types

type Engine

type Engine struct {
	L *lua.LState
	// contains filtered or unexported fields
}

Engine is a generic Lua VM. It holds the gopher-lua state and a registry of addon libraries that get loaded on demand via require("res-<name>").

Usage:

e := script.NewEngine(ctx)
e.RegisterAddon("res-console", consoleLoader)
if err := e.Load("/path/to/script.lua"); err != nil { ... }

func NewEngine

func NewEngine(ctx context.Context) *Engine

NewEngine creates an Engine with a fresh Lua VM. The res-core stdlib (has_binary, has_file, read_file, env, sleep) is automatically registered and available to scripts via require("res-core") or as direct globals.

func (*Engine) Close

func (e *Engine) Close()

Close shuts down the Lua VM and releases its resources.

func (*Engine) FireHook

func (e *Engine) FireHook(event string, args ...lua.LValue)

FireHook calls all functions registered under the named event table entry. This helper is a convenience for host apps that store hook lists in a Lua table named "res_hooks".

func (*Engine) Load

func (e *Engine) Load(path string) error

Load compiles and executes the Lua file at path.

func (*Engine) LoadString

func (e *Engine) LoadString(code, name string) error

LoadString compiles and executes Lua source from an in-memory string. name is used as the chunk name in error messages.

func (*Engine) RegisterAddon

func (e *Engine) RegisterAddon(name string, loader lua.LGFunction)

RegisterAddon registers a Lua loader function under the given module name (e.g. "res-console"). The loader is invoked when a script calls require("res-console").

func (*Engine) SetGlobal

func (e *Engine) SetGlobal(name string, v lua.LValue)

SetGlobal exposes a Go value as a Lua global.

type Pool

type Pool struct {
	// contains filtered or unexported fields
}

Pool is a fixed-size pool of reusable, sandboxed Lua VMs. Each worker holds its own *lua.LState and the sandbox setup installed by the caller. Between calls the stack top is restored and per-run env globals are cleared so the next evaluation starts from a known state.

func NewPool

func NewPool(size int, setup func(*lua.LState)) *Pool

NewPool creates a pool of the given size. If size <= 0 it defaults to runtime.NumCPU(). The setup function is called once per worker when the worker is created; use SandboxSetup to install scope-based sandboxes.

func (*Pool) Close

func (p *Pool) Close()

Close shuts down the pool and closes all worker VMs. It blocks until any in-flight evaluations finish. It is safe to call multiple times.

func (*Pool) Run

func (p *Pool) Run(ctx context.Context, code string, env map[string]lua.LValue) ([]lua.LValue, error)

Run compiles code and executes it in a pooled VM, injecting env as globals for this run only. It returns all values returned by the chunk.

func (*Pool) RunProto

func (p *Pool) RunProto(ctx context.Context, proto *lua.FunctionProto, env map[string]lua.LValue) ([]lua.LValue, error)

RunProto executes an already-compiled proto in a pooled VM. env is injected as globals for this run only.

func (*Pool) WithState

func (p *Pool) WithState(ctx context.Context, fn func(*lua.LState) ([]lua.LValue, error)) ([]lua.LValue, error)

WithState checks out a pooled VM and calls fn with it. The caller is responsible for stack hygiene; the pool restores the pre-call stack top and clears any env globals after fn returns.

type Scope

type Scope string

Scope names a sandbox capability that controls which globals and standard libraries are available to scripts running in a pooled VM.

const (
	// ScopeBase installs the safe subset of Lua base globals: assert, error,
	// ipairs, next, pairs, pcall, select, tonumber, tostring, type, xpcall,
	// _G, _VERSION. Unsafe base functions (dofile, load, loadfile, loadstring,
	// getfenv, setfenv, collectgarbage, print) are removed.
	ScopeBase Scope = "base"

	// ScopeMath opens the math library.
	ScopeMath Scope = "math"

	// ScopeString opens the string library.
	ScopeString Scope = "string"

	// ScopeTable opens the table library.
	ScopeTable Scope = "table"
)