expr

Documentation

Overview

Package expr is SpecArch's expression subset of CEL: it parses with the CEL parser, refuses whatever is outside the subset, checks types and evaluates with exact numbers.

Index

• Constants
• Variables
• func Check(n *Node, env Env) (Type, []Error)
• func DecodeBytes(s string) (string, error)
• func Equal(a, b Value) bool
• func Fits(got, want Type) (bool, string)
• func FitsInt(r *big.Rat, bits int) bool
• func FormatDecimal(r *big.Rat) string
• func Parse(src string) (*Node, []Error)
• func Round(r *big.Rat, places int) *big.Rat
• type Env
• type Error
• type ErrorKind
• type EvalError
  • func (e *EvalError) Error() string
• type Kind
• type Node
• type Type
  • func (t Type) String() string
• type Value
  • func Eval(n *Node, vals map[string]Value) (Value, error)
  • func (v Value) String() string

Constants

const (
	OpInt    = "int"
	OpUint   = "uint"
	OpDouble = "double"
	OpText   = "text"
	OpBool   = "bool"
	OpNull   = "null"
	OpName   = "name"
	OpCall   = "call" // Text is the function name
	OpNeg    = "-x"
	OpNot    = "!"
	OpCond   = "?:"
)

Node operations.

const FunctionList = "int, uint, double, decimal, string, date, timestamp, size, round, floor, ceil, min and max"

FunctionList names the functions for messages.

const UnknownScale = -1

UnknownScale marks a decimal whose scale is not fixed, the result of /.

Variables

var Functions = map[string]bool{
	"int": true, "uint": true, "double": true, "decimal": true, "string": true,
	"date": true, "timestamp": true, "size": true, "round": true, "floor": true,
	"ceil": true, "min": true, "max": true,
}

Functions lists the functions of the subset.

Functions

func Check

func Check(n *Node, env Env) (Type, []Error)

Check type-checks a parsed expression and returns its type.

func DecodeBytes

func DecodeBytes(s string) (string, error)

DecodeBytes reads a base64 example value.

func Equal

func Equal(a, b Value) bool

Equal compares two values of one type; decimals by value, so "3.50" equals "3.5".

func Fits

func Fits(got, want Type) (bool, string)

Fits reports whether a formula's type can be returned as the declared output, and says why not.

func FitsInt

func FitsInt(r *big.Rat, bits int) bool

FitsInt reports whether r is a whole number inside a signed width.

func FormatDecimal

func FormatDecimal(r *big.Rat) string

FormatDecimal writes an exact number with as many places as it needs.

func Parse

func Parse(src string) (*Node, []Error)

Parse parses one expression and turns it into the subset's nodes. It refuses anything outside the subset by name.

func Round

func Round(r *big.Rat, places int) *big.Rat

Round rounds half away from zero to the given number of decimal places.

Types

type Env

type Env map[string]Type

Env holds the names an expression may use and their types.

type Error

type Error struct {
	Line    int
	Column  int
	Kind    ErrorKind
	Message string
}

Error is one problem in an expression. Line and Column count from 1, inside the expression text.

type ErrorKind

type ErrorKind int

ErrorKind sorts errors into the validator's rules.

const (
	Syntax ErrorKind = iota
	Name
	TypeMismatch
)

type EvalError

type EvalError struct {
	Line, Column int
	Message      string
}

EvalError is a value an expression cannot compute.

func (*EvalError) Error

func (e *EvalError) Error() string

type Kind

type Kind string

Kind is the type of a value, as CEL names it, plus SpecArch's decimal, date and enum.

const (
	Int       Kind = "int"
	Uint      Kind = "uint"
	Double    Kind = "double"
	Decimal   Kind = "decimal"
	String    Kind = "string"
	Bool      Kind = "bool"
	Bytes     Kind = "bytes"
	Date      Kind = "date"
	Timestamp Kind = "timestamp"
	Duration  Kind = "duration"
	TimeOfDay Kind = "time"
	Enum      Kind = "enum"
	List      Kind = "list"
	Object    Kind = "object"
	Null      Kind = "null"
)

type Node

type Node struct {
	Op     string   // see the constants below
	Int    *big.Int // for OpInt and OpUint
	Double float64  // for OpDouble
	Text   string   // a string literal, a name, or a function name
	Bool   bool
	Args   []*Node
	Line   int
	Column int
}

Node is one node of a parsed expression.

type Type

type Type struct {
	Kind     Kind
	Scale    int      // for Decimal: digits after the point, or UnknownScale
	Bits     int      // for Int: 32 or 64, the declared width
	EnumName string   // for Enum
	Values   []string // for Enum
	Nullable bool
}

Type is the type of a name or of an expression.

func (Type) String

func (t Type) String() string

type Value

type Value struct {
	Kind   Kind
	Num    *big.Rat // Int, Uint, Decimal
	Double float64
	Text   string // String, Enum, Bytes (raw)
	Bool   bool
	Time   time.Time     // Date, Timestamp, TimeOfDay
	Dur    time.Duration // Duration
	Items  int           // List: the length
}

Value is a value during evaluation. Int, uint and decimal values are exact; a double is a float64, as CEL has it.

func Eval

func Eval(n *Node, vals map[string]Value) (Value, error)

Eval computes a checked expression with the given values.

func (Value) String

func (v Value) String() string

String shows a value the way a worked example writes it.