Elex (Elex v0.2.1)

View Source

Elex is an expression language library for parsing, validating, and evaluating expressions.

It supports:

  • Arithmetic operations (+, -, *, /, %) and unary minus
  • Comparison operators (<, >, <=, >=, ==, !=) for decimals, booleans, strings, and null
  • Boolean operations (and, or, not) with short-circuit evaluation
  • Literals: decimals, booleans (true/false, yes/no), strings, null
  • Variables and built-in functions (abs, between, ceil, clamp, coalesce, concat, contains, ends_with, floor, if, length, lower, max, min, mod, pi, pow, rem, round, sqrt, starts_with, trim, upper)
  • Variadic min, max, and coalesce (two or more arguments)
  • Type checking and validation

Quick start

context =
  Elex.new_context()
  |> Elex.add_variable("x", 10)
  |> Elex.add_variable("y", 5)

Elex.evaluate("x + y * 2", context)
#=> {:ok, #Decimal<20>}

Elex.validate("x > 0", context)
#=> {:ok, :boolean}

Elex.extract_variables("x + y")
#=> {:ok, ["x", "y"]}

Guides

See Elex.Parser for parsing, Elex.Evaluator for direct AST evaluation, and Elex.Context for custom variables and functions.

Summary

Functions

add_variable(context, name, value)

Add a single variable to a context.

add_variables(context, variables_map)

Add multiple variables to a context at once.

evaluate(expression_string, context)

Parses, validates, and evaluates an expression string.

extract_variables(expression_string)

Extracts variable names referenced in an expression string.

new_context(variables \\ %{})

Creates a new evaluation context with standard functions and optional variables.

validate(expression_string, context)

Parses and validates an expression string without evaluating it.

Functions

add_variable(context, name, value)

@spec add_variable(Elex.Context.t(), String.t(), any()) :: Elex.Context.t()

Add a single variable to a context.

This creates a Elex.Variable struct with the value and adds it to the context.

Examples

context = new_context()
|> add_variable("setting_a", 42.5)

add_variables(context, variables_map)

@spec add_variables(Elex.Context.t(), map()) :: Elex.Context.t()

Add multiple variables to a context at once.

This is useful for setting up an evaluation context with all known setting values.

Examples

context = new_context()
|> add_variables(%{"setting_a" => 10, "setting_b" => 20})

evaluate(expression_string, context)

@spec evaluate(String.t(), Elex.Context.t()) ::
  {:ok, Decimal.t() | boolean() | String.t() | nil} | {:error, String.t()}

Parses, validates, and evaluates an expression string.

Returns {:ok, result} on success or {:error, reason} on parse, validation, or evaluation failure (including arithmetic errors such as division by zero).

Parameters

  • expression_string - The expression to evaluate
  • context - A Elex.Context with variables and functions

Returns

  • {:ok, result} - The evaluated result (Decimal.t(), boolean(), String.t(), or nil)
  • {:error, reason} - A human-readable error message

Examples

context = Elex.new_context() |> Elex.add_variable("x", 10)
Elex.evaluate("x + 5", context)
#=> {:ok, #Decimal<15>}

extract_variables(expression_string)

@spec extract_variables(String.t()) :: {:ok, [String.t()]} | {:error, String.t()}

Extracts variable names referenced in an expression string.

Parsing is performed without validation, so variables need not exist in the context.

Parameters

  • expression_string - The expression to analyse

Returns

  • {:ok, names} - A deduplicated list of variable name strings
  • {:error, reason} - A parse error message

Examples

Elex.extract_variables("x + y * 2")
#=> {:ok, ["x", "y"]}

new_context(variables \\ %{})

@spec new_context(%{optional(String.t()) => Elex.Variable.t()}) :: Elex.Context.t()

Creates a new evaluation context with standard functions and optional variables.

Parameters

  • variables - Map of variable names to Elex.Variable structs. Defaults to an empty map.

Returns

A Elex.Context struct ready for parsing and evaluation.

Examples

Elex.new_context()

Elex.new_context(%{
  "x" => %Elex.Variable{value: Decimal.new(1), type: :decimal}
})

validate(expression_string, context)

@spec validate(String.t(), Elex.Context.t()) :: {:ok, atom()} | {:error, String.t()}

Parses and validates an expression string without evaluating it.

Parameters

  • expression_string - The expression to validate
  • context - A Elex.Context with variables and functions

Returns

  • {:ok, type} - The expression's result type (:decimal, :boolean, or :string)
  • {:error, reason} - A human-readable error message

Examples

context = Elex.new_context() |> Elex.add_variable("x", 10)
Elex.validate("x > 0", context)
#=> {:ok, :boolean}