Predicator

A secure, non-evaluative condition engine for processing end-user boolean predicates in Elixir. Predicator allows you to safely evaluate user-defined expressions without the security risks of dynamic code execution.

Features

🔒 Secure: No eval() or dynamic code execution - safe for end-user input
🎯 Simple: Clean, intuitive expression syntax (score > 85, name = 'John')
🚀 Fast: Compiled expressions execute efficiently with minimal overhead
🛡️ Type Safe: Built with comprehensive specs and rigorous testing
🎨 Flexible: Support for literals, identifiers, comparisons, and parentheses
📊 Observable: Detailed error reporting with line/column information
🔄 Reversible: Convert AST back to string expressions with formatting options
🧮 Arithmetic: Full arithmetic operations (+, -, *, /, %) with proper precedence
📅 Date Support: Native date and datetime literals with ISO 8601 format
⏳ Durations & Relative Dates: Natural-language durations and relative time expressions with date arithmetic
📋 Lists: List literals with membership operations (in, contains)
🧠 Smart Logic: Logical operators with proper precedence (AND, OR, NOT)
🔧 Functions: Built-in functions for string, numeric, and date operations
🌳 Nested Access: Dot notation and bracket access for deep data structures (user.profile.name, user['profile']['name'], items[0])
📦 Object Literals: JavaScript-style object notation with {key: value} syntax for complex data structures

Installation

Add predicator to your list of dependencies in mix.exs:

def deps do
  [
    {:predicator, "~> 3.5"}
  ]
end

Quick Start

# Basic evaluation
iex> Predicator.evaluate!("score > 85", %{"score" => 92})
true

# String comparisons (double or single quotes)
iex> Predicator.evaluate!("name = &#39;Alice&#39;", %{"name" => "Alice"})
true

iex> Predicator.evaluate!("name = \"Alice\"", %{"name" => "Alice"})
true

# Date and datetime literals
iex> Predicator.evaluate!("#2024-01-15# > #2024-01-10#", %{})
true

iex> Predicator.evaluate!("created_at < #2024-01-15T10:30:00Z#", %{"created_at" => ~U[2024-01-10 09:00:00Z]})
true

# Durations, relative dates, and date arithmetic
iex> Predicator.evaluate!("created_at > 3d ago", %{"created_at" => ~U[2024-01-20 00:00:00Z]})
true

iex> Predicator.evaluate!("due_at < 2w from now", %{"due_at" => Date.add(Date.utc_today(), 10)})
true

iex> Predicator.evaluate!("#2024-01-10# + 5d = #2024-01-15#", %{})
true

iex> Predicator.evaluate!("#2024-01-15T10:30:00Z# - 2h < #2024-01-15T10:30:00Z#", %{})
true

# List literals and membership
iex> Predicator.evaluate!("role in [&#39;admin&#39;, &#39;manager&#39;]", %{"role" => "admin"})
true

iex> Predicator.evaluate!("[1, 2, 3] contains 2", %{})
true

# Arithmetic operations with proper precedence
iex> Predicator.evaluate!("2 + 3 * 4", %{})
14

iex> Predicator.evaluate!("(10 - 5) * 2", %{})
10

iex> Predicator.evaluate!("score + bonus > 100", %{"score" => 85, "bonus" => 20})
true

iex> Predicator.evaluate!("-amount > -50", %{"amount" => 30})
true

# Float support and type coercion
iex> Predicator.evaluate!("3.14 * 2", %{})
6.28

iex> Predicator.evaluate!("&#39;Hello&#39; + &#39; World&#39;", %{})
"Hello World"

iex> Predicator.evaluate!("&#39;Count: &#39; + 42", %{})
"Count: 42"

iex> Predicator.evaluate!("score + &#39; points&#39;", %{"score" => 100})
"100 points"

# Logical operators with proper precedence
iex> Predicator.evaluate!("score > 85 AND age >= 18", %{"score" => 92, "age" => 25})
true

iex> Predicator.evaluate!("role = &#39;admin&#39; OR role = &#39;manager&#39;", %{"role" => "admin"})  
true

iex> Predicator.evaluate!("NOT expired AND active", %{"expired" => false, "active" => true})
true

# Complex expressions with parentheses
iex> Predicator.evaluate!("(score > 85 OR admin) AND active", %{"score" => 80, "admin" => true, "active" => true})
true

# Built-in functions
iex> Predicator.evaluate!("len(name) > 3", %{"name" => "Alice"})
true

iex> Predicator.evaluate!("upper(role) = &#39;ADMIN&#39;", %{"role" => "admin"})
true

iex> Predicator.evaluate!("year(created_at) = 2024", %{"created_at" => ~D[2024-03-15]})
true

# Compile once, evaluate many times for performance
iex> {:ok, instructions} = Predicator.compile("score > threshold AND active")
iex> Predicator.evaluate!(instructions, %{"score" => 95, "threshold" => 80, "active" => true})
true

# Using evaluate/2 (returns {:ok, result} or {:error, message})
iex> Predicator.evaluate("score > 85", %{"score" => 92})
{:ok, true}

iex> Predicator.evaluate("invalid >> syntax", %{})
{:error, "Expected number, string, boolean, date, datetime, identifier, function call, list, or &#39;(&#39; but found &#39;>&#39; at line 1, column 10"}

# Using evaluate/1 for expressions without context (strings or instruction lists)
iex> Predicator.evaluate("#2024-01-15# > #2024-01-10#")
{:ok, true}

iex> Predicator.evaluate([["lit", 42]])
{:ok, 42}

# Round-trip: parse and decompile expressions (preserves quote style)
iex> {:ok, ast} = Predicator.parse("name = &#39;John&#39;")
iex> Predicator.decompile(ast)
"name = &#39;John&#39;"

iex> {:ok, ast} = Predicator.parse("score > 85 AND #2024-01-15# in dates")
iex> Predicator.decompile(ast)
"score > 85 AND #2024-01-15# IN dates"

# Object literals - JavaScript-style object notation
iex> Predicator.evaluate!("{}", %{})
%{}

iex> Predicator.evaluate!("{name: \"John\", age: 30}", %{})
%{"name" => "John", "age" => 30}

# Objects with variable references and expressions
iex> Predicator.evaluate!("{user: name, total: price + tax}", %{"name" => "Alice", "price" => 100, "tax" => 10})
%{"user" => "Alice", "total" => 110}

# Nested objects for complex data structures
iex> Predicator.evaluate!("{user: {name: \"Bob\", role: \"admin\"}, active: true}", %{})
%{"user" => %{"name" => "Bob", "role" => "admin"}, "active" => true}

# String keys for complex property names
iex> Predicator.evaluate!("{\"first name\": \"John\", \"user-id\": 42}", %{})
%{"first name" => "John", "user-id" => 42}

# Object comparisons
iex> Predicator.evaluate!("{score: 85} == user_data", %{"user_data" => %{"score" => 85}})
true

# Objects work with functions and all operators
iex> Predicator.evaluate!("{username: upper(name), active: score > 80}", %{"name" => "alice", "score" => 95})
%{"username" => "ALICE", "active" => true}

Nested Data Access

Predicator supports nested data structure access using both dot notation and bracket notation, allowing you to reference deeply nested values in your context:

# Context with nested data structures
context = %{
  "user" => %{
    "age" => 47,
    "name" => %{"first" => "John", "last" => "Doe"},
    "profile" => %{"role" => "admin"},
    "settings" => %{"theme" => "dark", "notifications" => true}
  },
  "config" => %{
    "database" => %{"host" => "localhost", "port" => 5432}
  },
  "items" => ["apple", "banana", "cherry"],
  "scores" => [85, 92, 78, 96]
}

# Access nested values with dot notation
iex> Predicator.evaluate("user.name.first = &#39;John&#39;", context)
{:ok, true}

iex> Predicator.evaluate("user.age > 18", context)
{:ok, true}

iex> Predicator.evaluate("config.database.port = 5432", context)
{:ok, true}

# Access with bracket notation
iex> Predicator.evaluate("user[&#39;name&#39;][&#39;first&#39;] = &#39;John&#39;", context)
{:ok, true}

iex> Predicator.evaluate("user[&#39;settings&#39;][&#39;theme&#39;] = &#39;dark&#39;", context)
{:ok, true}

# Array access with bracket notation
iex> Predicator.evaluate("items[0] = &#39;apple&#39;", context)
{:ok, true}

iex> Predicator.evaluate("scores[1] > 90", context)
{:ok, true}

# Mixed notation styles
iex> Predicator.evaluate("user.settings[&#39;theme&#39;] = &#39;dark&#39;", context)
{:ok, true}

iex> Predicator.evaluate("user[&#39;profile&#39;].role = &#39;admin&#39;", context)
{:ok, true}

# Dynamic array access
iex> Predicator.evaluate("scores[index] > 80", Map.put(context, "index", 2))
{:ok, false}

# Chained bracket access
iex> Predicator.evaluate("user[&#39;name&#39;][&#39;first&#39;] + &#39; &#39; + user[&#39;name&#39;][&#39;last&#39;]", context)
{:ok, "John Doe"}

# Use in complex expressions
iex> Predicator.evaluate("user.profile.role = &#39;admin&#39; AND user.settings.notifications", context)
{:ok, true}

# Missing paths return :undefined
iex> Predicator.evaluate("user.profile.email = &#39;test&#39;", context)
{:ok, :undefined}

# Works with both string and atom keys
atom_context = %{user: %{name: %{first: "Jane"}}}
iex> Predicator.evaluate("user.name.first = &#39;Jane&#39;", atom_context)
{:ok, true}

# Access nested lists
list_context = %{"user" => %{"hobbies" => ["reading", "coding"]}}
iex> Predicator.evaluate("&#39;coding&#39; in user.hobbies", list_context)
{:ok, true}

Key Features

Dot notation: user.profile.name for nested object access
Bracket notation: user['profile']['name'] for dynamic key access
Array indexing: items[0], scores[index] for list access
Mixed styles: user.settings['theme'] combining both notations
Unlimited nesting depth: app.database.config.settings.ssl
Mixed key types: Works with string keys, atom keys, or both
Graceful fallback: Returns :undefined for missing paths or out-of-bounds access
Type preservation: Maintains original data types (strings, numbers, booleans, lists)
Backwards compatible: Simple variable names work exactly as before

Supported Operations

Arithmetic Operators

Operator	Description	Example
`+`	Addition	`score + bonus`, `2 + 3 * 4`
`-`	Subtraction	`total - discount`, `100 - 25`
`*`	Multiplication	`price * quantity`, `3 * 4`
`/`	Division (integer)	`total / count`, `10 / 3`
`%`	Modulo	`id % 2`, `17 % 5`
`-`	Unary minus	`-amount`, `-(x + y)`

Comparison Operators

Operator	Description	Example
`>`	Greater than	`score > 85`, `#2024-01-15# > #2024-01-10#`
`<`	Less than	`age < 30`, `created_at < #2024-01-15T10:00:00Z#`
`>=`	Greater than or equal	`points >= 100`
`<=`	Less than or equal	`count <= 5`
`=`	Equal	`status = 'active'`, `date = #2024-01-15#`
`!=`	Not equal	`role != 'guest'`

Logical Operators

Operator	Description	Example
`AND`	Logical AND (case-insensitive)	`score > 85 AND age >= 18`
`OR`	Logical OR (case-insensitive)	`role = 'admin' OR role = 'manager'`
`NOT`	Logical NOT (case-insensitive)	`NOT expired`

Membership Operators

Operator	Description	Example
`in`	Element in collection	`role in ['admin', 'manager']`
`contains`	Collection contains element	`[1, 2, 3] contains 2`

Built-in Functions

String Functions

Function	Description	Example
`len(string)`	String length	`len(name) > 3`
`upper(string)`	Convert to uppercase	`upper(role) = 'ADMIN'`
`lower(string)`	Convert to lowercase	`lower(name) = 'alice'`
`trim(string)`	Remove whitespace	`len(trim(input)) > 0`

Numeric Functions

Function	Description	Example
`abs(number)`	Absolute value	`abs(balance) < 100`
`max(a, b)`	Maximum of two numbers	`max(score1, score2) > 85`
`min(a, b)`	Minimum of two numbers	`min(age, 65) >= 18`

Date Functions

Function	Description	Example
`year(date)`	Extract year	`year(created_at) = 2024`
`month(date)`	Extract month	`month(birthday) = 12`
`day(date)`	Extract day	`day(deadline) <= 15`

Data Types

Numbers: 42, -17 (integers), 3.14, -2.5 (floats)
Strings: 'hello', 'world' (single-quoted) or "hello", "world" (double-quoted, with escape sequences)
Booleans: true, false (or plain identifiers like active, expired)
Dates: #2024-01-15# (ISO 8601 date format)
DateTimes: #2024-01-15T10:30:00Z# (ISO 8601 datetime format with timezone)
Durations: Natural units for time spans (e.g., 3d, 2h, 15m)
- In relative expressions: 3d ago, 2w from now, next 1mo, last 1y
- In arithmetic: #2024-01-10# + 5d, #2024-01-15T10:30:00Z# - 2h
Lists: [1, 2, 3], ['admin', 'manager'] (homogeneous collections)
Objects: {}, {name: "John", age: 30}, {user: {role: "admin"}} (JavaScript-style object literals)
Identifiers: score, user_name, is_active, user.profile.name, user['key'], items[0] (variable references with dot notation and bracket notation for nested data)

Architecture

Predicator uses a multi-stage compilation pipeline:

  Expression String  →  Lexer → Parser → Compiler → Evaluator
         ↓                ↓       ↓         ↓           ↓
'score > 85 OR admin' → Tokens → AST → Instructions → Result

Grammar

expression   → logical_or
logical_or   → logical_and ( ("OR" | "or") logical_and )*
logical_and  → logical_not ( ("AND" | "and") logical_not )*
logical_not  → ("NOT" | "not") logical_not | comparison
comparison   → addition ( ( ">" | "<" | ">=" | "<=" | "=" | "==" | "!=" | "===" | "!==" | "in" | "contains" ) addition )?
addition     → multiplication ( ( "+" | "-" ) multiplication )*
multiplication → unary ( ( "*" | "/" | "%" ) unary )*
unary        → ( "-" | "!" ) unary | postfix
postfix      → primary ( "[" expression "]" | "." IDENTIFIER )*
primary      → NUMBER | FLOAT | STRING | BOOLEAN | DATE | DATETIME | IDENTIFIER | duration | relative_date | function_call | list | object | "(" expression ")"
function_call → FUNCTION_NAME "(" ( expression ( "," expression )* )? ")"
list         → "[" ( expression ( "," expression )* )? "]"
object       → "{" ( object_entry ( "," object_entry )* )? "}"
object_entry → object_key ":" expression
object_key   → IDENTIFIER | STRING
duration     → NUMBER UNIT+
relative_date → duration "ago" | duration "from" "now" | "next" duration | "last" duration

Core Components

Lexer (Predicator.Lexer): Tokenizes input with position tracking
Parser (Predicator.Parser): Builds Abstract Syntax Tree with error reporting
Compiler (Predicator.Compiler): Converts AST to executable instructions
Evaluator (Predicator.Evaluator): Executes instructions against data
Visitors: AST transformation modules
- StringVisitor (Predicator.Visitors.StringVisitor): Converts AST back to expressions
- InstructionsVisitor (Predicator.Visitors.InstructionsVisitor): Converts AST to instructions
Functions: Function system components
- SystemFunctions (Predicator.Functions.SystemFunctions): Built-in system functions
- Registry (Predicator.Functions.Registry): Function registration and dispatch

Error Handling

Predicator provides detailed error information with exact positioning:

iex> Predicator.evaluate("score >> 85", %{})
{:error, "Unexpected character &#39;>&#39; at line 1, column 8"}

iex> Predicator.evaluate("score AND", %{})
{:error, "Expected number, string, boolean, date, datetime, identifier, function call, list, or &#39;(&#39; but found end of input at line 1, column 1"}

Advanced Usage

Custom Functions

You can provide custom functions when evaluating expressions using the functions: option:

# Define custom functions in a map
custom_functions = %{
  "double" => {1, fn [n], _context -> {:ok, n * 2} end},
  "user_role" => {0, fn [], context -> 
    {:ok, Map.get(context, "current_user_role", "guest")} 
  end},
  "divide" => {2, fn [a, b], _context ->
    if b == 0 do
      {:error, "Division by zero"}
    else
      {:ok, a / b}
    end
  end}
}

# Use custom functions in expressions
iex> Predicator.evaluate("double(score) > 100", %{"score" => 60}, functions: custom_functions)
{:ok, true}

iex> Predicator.evaluate("user_role() = &#39;admin&#39;", %{"current_user_role" => "admin"}, functions: custom_functions)
{:ok, true}

iex> Predicator.evaluate("divide(10, 2) = 5", %{}, functions: custom_functions)
{:ok, true}

iex> Predicator.evaluate("divide(10, 0)", %{}, functions: custom_functions)
{:error, "Division by zero"}

# Custom functions can override built-in functions
override_functions = %{
  "len" => {1, fn [_], _context -> {:ok, "custom_result"} end}
}

iex> Predicator.evaluate("len(&#39;anything&#39;)", %{}, functions: override_functions)
{:ok, "custom_result"}

# Without custom functions, built-ins work as expected
iex> Predicator.evaluate("len(&#39;hello&#39;)", %{})
{:ok, 5}

Function Format

Custom functions must follow this format:

Map Key: Function name (string)
Map Value: {arity, function} tuple where:
- arity: Number of arguments the function expects (integer)
- function: Anonymous function that takes [args], context and returns {:ok, result} or {:error, message}

String Formatting Options

The StringVisitor supports multiple formatting modes:

# Compact formatting (no spaces)
iex> Predicator.decompile(ast, spacing: :compact)
"score>85"

# Verbose formatting (extra spaces)  
iex> Predicator.decompile(ast, spacing: :verbose)
"score  >  85"

# Explicit parentheses
iex> Predicator.decompile(ast, parentheses: :explicit)
"(score > 85)"

SCXML Location Expressions

Predicator provides specialized support for SCXML datamodel location expressions, which determine valid assignment targets (l-values) for <assign> operations:

# Resolve location paths for assignment operations
iex> Predicator.context_location("user.profile.name", %{})
{:ok, ["user", "profile", "name"]}

iex> Predicator.context_location("items[0]", %{})
{:ok, ["items", 0]}

iex> Predicator.context_location("data[&#39;users&#39;][index][&#39;profile&#39;]", %{"index" => 2})
{:ok, ["data", "users", 2, "profile"]}

# Detect invalid assignment targets
iex> Predicator.context_location("len(name)", %{})
{:error, %Predicator.Errors.LocationError{type: :not_assignable, message: "Cannot assign to function call"}}

iex> Predicator.context_location("42", %{})
{:error, %Predicator.Errors.LocationError{type: :not_assignable, message: "Cannot assign to literal value"}}

# Variable keys must exist in context
iex> Predicator.context_location("items[missing_var]", %{})
{:error, %Predicator.Errors.LocationError{type: :undefined_variable, message: "Bracket key variable not found"}}

Assignable vs Non-Assignable Expressions

✅ Valid Assignment Targets:

Simple identifiers: user, score, config
Property access: user.name, config.database.host
Bracket access: items[0], user['profile'], data["key"]
Mixed notation: user.settings['theme'], data['users'][0].profile

❌ Invalid Assignment Targets:

Literals: 42, "hello", true, #2024-01-15#
Function calls: len(name), upper(role), max(a, b)
Arithmetic expressions: score + 1, items[i + 1]
Comparison results: score > 85, name = "John"
Any computed expressions that cannot serve as memory locations

Location Path Format

Location paths are returned as lists representing the navigation path to a specific location:

# Examples of location paths
["user"]                           # user
["user", "name"]                   # user.name
["items", 0]                       # items[0]
["user", "profile", "settings", "theme"]  # user.profile.settings[&#39;theme&#39;]
["data", "users", 2, "name"]       # data[&#39;users&#39;][2][&#39;name&#39;]

This feature enables safe assignment operations in SCXML processors while preventing assignment to computed values or literals.

Development

Setup

mix deps.get
mix test

Quality Checks

# Run all quality checks
mix quality

# Individual checks  
mix format              # Format code
mix credo --strict     # Linting
mix coveralls          # Test coverage  
mix dialyzer           # Type checking

Documentation

Full documentation is available at HexDocs.