Documentation
¶
Index ¶
- Constants
- Variables
- func DecodeValue[T any](v Value) (T, error)
- func EvaluateAs[T any](ctx context.Context, e Engine, source string, env any) (T, error)
- func Match(ctx context.Context, e Engine, source string, env any) (bool, error)
- type CompileOption
- type CompileOptions
- type Engine
- type Program
- type Value
Constants ¶
const ErrCodeEvaluationFailed = 2500
Response codes for expression API errors (2500-2599).
Variables ¶
var ErrEvaluationFailed = result.Err( i18n.T("expression_evaluation_failed"), result.WithCode(ErrCodeEvaluationFailed), )
ErrEvaluationFailed is the outward error for any expression compile or evaluation failure. Backends wrap their cause with it (via errors join) so the stable code drives API mapping while the cause stays available for logs.
var ErrUnexpectedType = errors.New("expression: unexpected result type")
ErrUnexpectedType is returned when a Value cannot be read as the requested concrete type.
Functions ¶
func DecodeValue ¶
DecodeValue decodes v into a new T. It exists because Go interfaces cannot declare generic methods.
func EvaluateAs ¶
EvaluateAs evaluates source with e and decodes the result into T.
Types ¶
type CompileOption ¶
type CompileOption func(*CompileOptions)
CompileOption customizes compilation.
func AsPredicate ¶
func AsPredicate() CompileOption
AsPredicate marks the expression as boolean-valued.
type CompileOptions ¶
type CompileOptions struct {
// Predicate marks the expression as boolean-valued; the backend evaluates
// it in its boolean idiom.
Predicate bool
}
CompileOptions holds the resolved compilation settings an Engine applies when preparing a Program. Backend adapters read it to choose how to evaluate.
type Engine ¶
type Engine interface {
// Evaluate compiles and evaluates source against env in a single step.
// env holds the variable bindings (a map or struct) the expression reads.
Evaluate(ctx context.Context, source string, env any) (Value, error)
// Compile prepares source for repeated evaluation, returning a Program.
// Options tune compilation, e.g. AsPredicate marks the expression as
// boolean-valued. A backend may validate eagerly or defer parse and
// evaluation errors to Program.Run, so a nil error from Compile does not
// guarantee source is well-formed.
Compile(source string, opts ...CompileOption) (Program, error)
}
Engine evaluates expressions against a runtime environment.
Implementations adapt a concrete expression backend to this contract. Callers depend only on this interface, never on the backend, so the underlying engine can be replaced without touching consumer code.
Context cancellation is best-effort and backend-dependent: a backend should honor an already-canceled context but may be unable to interrupt an evaluation that is already in flight.
The expression syntax itself is defined by the active backend; only the Go API, evaluation lifecycle, result handling and errors are abstracted here.
type Program ¶
type Program interface {
// Run evaluates the compiled program against env.
Run(ctx context.Context, env any) (Value, error)
// Source returns the original expression text.
Source() string
}
Program is a prepared expression that can be evaluated repeatedly. Depending on the backend, parse or validation errors may surface only from Run.
type Value ¶
type Value struct {
// contains filtered or unexported fields
}
Value is the backend-agnostic result of an evaluation. It wraps a plain Go value and never exposes any backend type, so consumers stay decoupled from the underlying engine.
func NewValue ¶
NewValue wraps a raw evaluated value. It is the construction point for backend adapters; ordinary callers obtain Values from Engine or Program.
func (Value) Decode ¶
Decode unmarshals the value into target, which must be a non-nil pointer. Conversion goes through JSON, matching how backends serialize results; integers beyond float64 precision may lose accuracy.
Source Files