expression

Documentation

Overview

Package expression provides a small, typed, reflection-free expression language for compiler-validated framework policies.

Expressions can use explicitly declared Boolean and string variables and functions. They support !, &&, ||, ==, !=, literals, calls, and parentheses. There is no property traversal, bean lookup, method invocation, assignment, allocation, I/O, or access to ambient process state.

Index

• type CompileError
  • func (err *CompileError) Error() string
• type Function
• type FunctionSpec
• type Inputs
• type Kind
• type Program
  • func Compile(source string, schema Schema) (Program, error)
  • func (program Program) Evaluate(ctx context.Context, inputs Inputs) (bool, error)
  • func (program Program) Source() string
• type Schema
• type Value
  • func Bool(value bool) Value
  • func Text(value string) Value
  • func (value Value) BooleanValue() (bool, bool)
  • func (value Value) Kind() Kind
  • func (value Value) StringValue() (string, bool)
• type Variable

Examples

• Compile

Types

type CompileError

type CompileError struct {
	Offset  int
	Message string
}

CompileError is a source-positioned expression failure. Offset is a zero-based UTF-8 byte offset into the expression literal.

func (*CompileError) Error

func (err *CompileError) Error() string

Error renders a bounded message without including the expression source.

type Function

type Function func(context.Context, []Value) (Value, error)

Function evaluates one declared function. Arguments and results are checked against the compiled schema before values enter or leave the function.

type FunctionSpec

type FunctionSpec struct {
	Name       string
	Parameters []Kind
	Result     Kind
}

FunctionSpec declares one positional function available to an expression.

type Inputs

type Inputs struct {
	Variables []Value
	Functions []Function
}

Inputs binds variables and functions in the declaration order of the schema passed to Compile. Slices are read only for the duration of Evaluate.

type Kind

type Kind uint8

Kind identifies one expression value type.

const (

	// Boolean identifies a Boolean expression value.
	Boolean Kind
	// String identifies a string expression value.
	String
)

type Program

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

Program is an immutable compiled Boolean expression.

func Compile

func Compile(source string, schema Schema) (Program, error)

Compile parses and type-checks one Boolean expression against an explicit schema. The schema and source are defensively copied into the returned immutable program.

Example

program, err := Compile(`enabled && hasLabel("stable")`, Schema{
	Variables: []Variable{{Name: "enabled", Kind: Boolean}},
	Functions: []FunctionSpec{{
		Name:       "hasLabel",
		Parameters: []Kind{String},
		Result:     Boolean,
	}},
})
if err != nil {
	fmt.Println(err)
	return
}
allowed, err := program.Evaluate(context.Background(), Inputs{
	Variables: []Value{Bool(true)},
	Functions: []Function{func(_ context.Context, arguments []Value) (Value, error) {
		label, _ := arguments[0].StringValue()
		return Bool(label == "stable"), nil
	}},
})
fmt.Println(allowed, err)

Output:
true <nil>

func (Program) Evaluate

func (program Program) Evaluate(ctx context.Context, inputs Inputs) (bool, error)

Evaluate executes a compiled expression against exact positional bindings. A nil context, wrong binding count/type, nil function, cancellation, or function failure fails closed.

func (Program) Source

func (program Program) Source() string

Source returns the canonical caller-supplied expression.

type Schema

type Schema struct {
	Variables []Variable
	Functions []FunctionSpec
}

Schema is the complete immutable symbol surface accepted by Compile. Declaration order becomes the positional runtime binding order.

type Value

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

Value is one immutable typed expression value.

func Bool

func Bool(value bool) Value

Bool constructs a Boolean value.

func Text

func Text(value string) Value

Text constructs a string value.

func (Value) BooleanValue

func (value Value) BooleanValue() (bool, bool)

BooleanValue returns a Boolean value and whether its type matches.

func (Value) Kind

func (value Value) Kind() Kind

Kind reports the value's expression type.

func (Value) StringValue

func (value Value) StringValue() (string, bool)

StringValue returns a string value and whether its type matches.

type Variable

type Variable struct {
	Name string
	Kind Kind
}

Variable declares one positional input available to an expression.