executor

Documentation

Index

• Variables
• func CallLambda(ctx context.Context, val any, args []any, start time.Time, depth int) (any, error)
• func NewDebugContext(ctx context.Context) (context.Context, *[]DebugEntry)
• func ToBool(v any) bool
• func ToFloat(v any) float64
• func ToInt(v any) int64
• func ToString(v any) string
• type BuiltinFunc
• type CompiledFunction
• type DebugEntry
• type ExecConfig
• type Executor
  • func New(builtins map[string]*BuiltinFunc, lookup FunctionLookup, config ExecConfig) *Executor
  • func (ex *Executor) Execute(ctx context.Context, fn *CompiledFunction, args map[string]any) (any, error)
  • func (ex *Executor) ExecuteExpr(ctx context.Context, expr ast.ExprNode, vars map[string]any) (any, error)
• type FunctionLookup

Variables

var (
	ErrTimeout  = errors.New("execution timeout exceeded")
	ErrMaxDepth = errors.New("maximum call depth exceeded")
	ErrDivZero  = errors.New("division by zero")
)

Errors returned by the executor.

var ErrUserRaise = errors.New("raise")

ErrUserRaise is returned when a DTL function executes a raise statement.

Functions

func CallLambda

func CallLambda(ctx context.Context, val any, args []any, start time.Time, depth int) (any, error)

CallLambda invokes a lambda closure. Used by stdlib collection functions.

func NewDebugContext

func NewDebugContext(ctx context.Context) (context.Context, *[]DebugEntry)

NewDebugContext returns a context with an attached debug buffer.

func ToBool

func ToBool(v any) bool

ToBool converts a value to bool, used by stdlib functions.

func ToFloat

func ToFloat(v any) float64

ToFloat converts a value to float64, used by stdlib functions.

func ToInt

func ToInt(v any) int64

ToInt converts a value to int64, used by stdlib functions.

func ToString

func ToString(v any) string

ToString converts a value to string, used by stdlib functions.

Types

type BuiltinFunc

type BuiltinFunc struct {
	Name    string
	MinArgs int
	MaxArgs int // -1 for variadic
	Fn      func(args []any) (any, error)
	// CtxFn is an optional context-aware alternative to Fn.
	// When set, the executor passes the evaluation context so the function
	// can access platform services (schema, query, pipeline, etc.).
	// If CtxFn is set, Fn is ignored.
	CtxFn func(ctx context.Context, args []any) (any, error)
	// Doc is a one-line signature and description, surfaced by the language
	// server as hover text and completion detail. The conventional shape is
	// "name(args) -> type -- what it does". Host-registered builtins may set
	// it to document themselves; an empty Doc simply yields no hover text.
	Doc string
}

BuiltinFunc is a Go-implemented function callable from DTL.

type CompiledFunction

type CompiledFunction struct {
	Name   string
	AST    *ast.FnAST
	Deps   []string
	Source string
}

CompiledFunction is a parsed+compiled user-defined function ready for execution.

type DebugEntry

type DebugEntry struct {
	Timestamp time.Time `json:"timestamp"`
	Label     string    `json:"label,omitempty"`
	Values    []any     `json:"values"`
}

DebugEntry represents a single debug/print output line.

type ExecConfig

type ExecConfig struct {
	// Timeout bounds wall-clock time per execution. Zero means unbounded.
	Timeout time.Duration

	// MaxDepth bounds nested user-function calls. Zero means unbounded.
	MaxDepth int
}

ExecConfig holds execution limits.

Both fields use zero to mean "unbounded", which is the right primitive at this layer but the wrong default for a host: unbounded depth ends in `fatal error: stack overflow`, which no recover() can catch. Callers that build an Executor directly own that choice. Anything constructed through registry.New gets registry.DefaultMaxCallDepth instead.

type Executor

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

Executor evaluates compiled DTL AST nodes via tree-walking.

func New

func New(builtins map[string]*BuiltinFunc, lookup FunctionLookup, config ExecConfig) *Executor

New creates an executor with the given built-ins and function resolver.

func (*Executor) Execute

func (ex *Executor) Execute(ctx context.Context, fn *CompiledFunction, args map[string]any) (any, error)

Execute runs a compiled function with the given arguments.

func (*Executor) ExecuteExpr

func (ex *Executor) ExecuteExpr(ctx context.Context, expr ast.ExprNode, vars map[string]any) (any, error)

ExecuteExpr evaluates a standalone expression with the given variable bindings.

type FunctionLookup

type FunctionLookup interface {
	GetCompiled(ctx context.Context, name string) (*CompiledFunction, bool)
}

FunctionLookup resolves function names to compiled user functions.