expr

README

GoForge Expr

goforge.dev/expr is the /goals/06-expr semantic rewrite of github.com/expr-lang/expr. It pairs a familiar parsing facade with a Go+-authored checked core:

• typed.Expr[T] makes result types intrinsic to the AST;
• typed.SomeExpr is the finite existential parse boundary;
• typed.EvalResult[T] separates evaluation from runtime failure;
• typed.EffectOf exposes environment reads;
• typed.Stack[n] and executable n -> n+1 / n+2 -> n+1 operations make bytecode underflow unrepresentable in Go+;
• Program uses immutable bytecode and a zero-allocation scalar VM lane.

env := expr.Environment{Ints: map[string]int{"price": 9, "count": 4}}
program, err := expr.Compile("price * count + 2", expr.Env(env), expr.AsInt())
if err != nil { /* compile failure */ }
total, err := expr.RunInt(program, env)

See COMPATIBILITY.md for the exact supported language and API tier, PERFORMANCE.md for the reproducible gate, and API_MANIFEST.csv for the complete pinned upstream inventory.

Documentation

Overview

Package expr compiles a statically checked subset of the Expr language to a compact, allocation-free bytecode evaluator. The checked Go+ AST lives in package typed; this package is its ordinary-Go parsing and erasure boundary.

Index

• func Eval(input string, environment any, options ...Option) (any, error)
• func ParseTyped(input string, environment Environment) (typed.SomeExpr, error)
• func Run(program *Program, environment any) (any, error)
• func RunBool(program *Program, environment Environment) (bool, error)
• func RunInt(program *Program, environment Environment) (int, error)
• func RunString(program *Program, environment Environment) (string, error)
• type CompileError
  • func (e *CompileError) Error() string
  • func (e *CompileError) Unwrap() error
• type Environment
• type Kind
  • func (k Kind) String() string
• type Option
  • func AsAny() Option
  • func AsBool() Option
  • func AsInt() Option
  • func Env(environment any) Option
  • func Optimize(_ bool) Option
• type Program
  • func Compile(input string, options ...Option) (program *Program, err error)
  • func (p *Program) Kind() Kind
  • func (p *Program) Source() string
• type RuntimeError
  • func (e *RuntimeError) Error() string
  • func (e *RuntimeError) Unwrap() error

Functions

func Eval

func Eval(input string, environment any, options ...Option) (any, error)

Eval compiles and evaluates input.

func ParseTyped

func ParseTyped(input string, environment Environment) (typed.SomeExpr, error)

ParseTyped parses at the existential boundary and returns one of the finite checked result families. Exhaustive matching on typed.SomeExpr recovers T.

func Run

func Run(program *Program, environment any) (any, error)

Run evaluates program at the compatibility boundary.

func RunBool

func RunBool(program *Program, environment Environment) (bool, error)

RunBool evaluates a boolean program without boxing its result.

func RunInt

func RunInt(program *Program, environment Environment) (int, error)

RunInt evaluates an integer program without boxing its result.

func RunString

func RunString(program *Program, environment Environment) (string, error)

RunString evaluates a string program without boxing its result.

Types

type CompileError

type CompileError struct{ Cause error }

CompileError is a parse, elaboration, option, or static type failure.

func (*CompileError) Error

func (e *CompileError) Error() string

func (*CompileError) Unwrap

func (e *CompileError) Unwrap() error

type Environment

type Environment struct {
	Ints    map[string]int
	Bools   map[string]bool
	Strings map[string]string
}

Environment is the typed, no-reflection execution boundary.

type Kind

type Kind uint8

Kind is the finite result-type universe supported by the checked engine.

const (
	Invalid Kind = iota
	Int
	Bool
	String
)

func (Kind) String

func (k Kind) String() string

type Option

type Option func(*config) error

Option configures compilation. It mirrors the high-value part of Expr's option model while keeping unsupported dynamic features explicit.

func AsAny

func AsAny() Option

AsAny accepts any result in the checked finite type universe.

func AsBool

func AsBool() Option

AsBool requires a boolean result.

func AsInt

func AsInt() Option

AsInt requires an integer result.

func Env

func Env(environment any) Option

Env describes variables available during compilation. Environment, map[string]int/bool/string, map[string]any, structs, and pointers to structs are accepted. Struct field names and expr/json tags are recognized.

func Optimize

func Optimize(_ bool) Option

Optimize is retained for source migration. The checked compiler always performs constant folding and dead-branch elimination.

type Program

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

Program is immutable and safe for concurrent evaluation.

func Compile

func Compile(input string, options ...Option) (program *Program, err error)

Compile parses, checks, folds, and compiles input.

func (*Program) Kind

func (p *Program) Kind() Kind

Kind reports the statically proven result type.

func (*Program) Source

func (p *Program) Source() string

Source returns the original expression.

type RuntimeError

type RuntimeError struct{ Cause error }

RuntimeError is an environment or evaluation failure after compilation.

func (*RuntimeError) Error

func (e *RuntimeError) Error() string

func (*RuntimeError) Unwrap

func (e *RuntimeError) Unwrap() error