Crate hel 

HEL — Heuristics Expression Language

A deterministic, auditable expression language designed for security analysis, rule engines, and policy evaluation systems.

Features

• Simple Expression Evaluation: Validate and evaluate boolean expressions with facts
• Script Support: Multi-line scripts with reusable let bindings
• Type-Safe: Strong typing with compile-time guarantees
• Deterministic: Stable evaluation order, reproducible results
• Auditable: Comprehensive trace capture for debugging and compliance
• Extensible: Plugin architecture for domain-specific built-in functions

Quick Start

Expression Validation

use hel::validate_expression;

// Validate syntax without evaluation
let expr = r#"binary.arch == "x86_64" AND security.nx == false"#;
assert!(validate_expression(expr).is_ok());

Expression Evaluation

use hel::{evaluate, FactsEvalContext, Value};

let mut ctx = FactsEvalContext::new();
ctx.add_fact("binary.arch", Value::String("x86_64".into()));
ctx.add_fact("security.nx", Value::Bool(false));

let expr = r#"binary.arch == "x86_64" AND security.nx == false"#;
let result = evaluate(expr, &ctx).expect("evaluation failed");
assert!(result);

Script Evaluation with Let Bindings

use hel::{evaluate_script, FactsEvalContext, Value};

let mut ctx = FactsEvalContext::new();
ctx.add_fact("manifest.permissions", Value::List(vec![
    Value::String("READ_SMS".into()),
]));
ctx.add_fact("binary.entropy", Value::Number(8.0));

let script = r#"
    let has_sms = manifest.permissions CONTAINS "READ_SMS"
    let has_obfuscation = binary.entropy > 7.5
    has_sms AND has_obfuscation
"#;

let result = evaluate_script(script, &ctx).expect("evaluation failed");
assert!(result);

Architecture

HEL is designed as a modular expression language with several key components:

Core Components

• Parser: Pest-based grammar for parsing HEL expressions
• AST: Compact Abstract Syntax Tree representation
• Evaluator: Deterministic expression evaluation engine
• Resolver: Trait-based attribute resolution for custom integrations

Extension Systems

• Built-ins: Pluggable function registry for domain-specific operations
• Schema: Type definitions for data validation
• Packages: Modular schema distribution and loading
• Trace: Audit trail generation for compliance and debugging

Advanced Usage

Custom Built-in Functions

use hel::{BuiltinsProvider, BuiltinFn, Value, EvalError};
use std::collections::BTreeMap;
use std::sync::Arc;

struct MyProvider;

impl BuiltinsProvider for MyProvider {
    fn namespace(&self) -> &str { "custom" }

    fn get_builtins(&self) -> BTreeMap<String, BuiltinFn> {
        let mut map = BTreeMap::new();
        map.insert("double".to_string(), Arc::new(|args: &[Value]| {
            match args.get(0) {
                Some(Value::Number(n)) => Ok(Value::Number(n * 2.0)),
                _ => Err(EvalError::InvalidOperation("Expected number".to_string())),
            }
        }) as BuiltinFn);
        map
    }
}

Evaluation Tracing

use hel::{evaluate_with_trace, HelResolver, Value};

struct MyResolver;
impl HelResolver for MyResolver {
    fn resolve_attr(&self, object: &str, field: &str) -> Option<Value> {
        match (object, field) {
            ("binary", "format") => Some(Value::String("elf".into())),
            _ => None,
        }
    }
}

let trace = evaluate_with_trace(
    r#"binary.format == "elf""#,
    &MyResolver,
    None
).expect("trace failed");

assert!(trace.result);
assert_eq!(trace.atoms.len(), 1);

Re-exports

pub use schema::package::PackageError;

pub use schema::package::PackageManifest;

pub use schema::package::PackageRegistry;

pub use schema::package::SchemaPackage;

pub use schema::package::TypeEnvironment;

pub use schema::parse_schema;

pub use schema::FieldDef;

pub use schema::FieldType;

pub use schema::Schema;

pub use schema::TypeDef;

pub use builtins::BuiltinFn;

pub use builtins::BuiltinsProvider;

pub use builtins::BuiltinsRegistry;

pub use builtins::CoreBuiltinsProvider;

pub use trace::evaluate_with_trace;

pub use trace::AtomTrace as TraceAtom;

pub use trace::EvalTrace;

Modules

builtins

Built-in function registry for HEL

schema

Schema definition support for HEL

trace

Trace capture for HEL rule evaluation

Structs

EvalContext

Evaluation context that includes resolver and optional built-ins registry

FactsEvalContext

Evaluation context with facts/data for expression evaluation

HelError

Enhanced error type for HEL with line/column information

HelParser

HEL parser generated by Pest

Script

Represents a parsed HEL script with let bindings

Enums

AstNode

Abstract Syntax Tree node representing a parsed HEL expression

Comparator

Comparison operators supported by HEL

ErrorKind

Classification of HEL errors

EvalError

Error type for HEL evaluation (legacy)

Rule

Value

Runtime value type for HEL evaluation

Traits

HelResolver

Resolver interface for host integration

Functions

evaluate

Evaluate expression against context

evaluate_script

Evaluate a script and return the final boolean result

evaluate_with_context

Evaluate a HEL expression with resolver and built-in functions (low-level API)

evaluate_with_resolver

Evaluate a HEL expression with a custom resolver (low-level API)

parse_expression

Parse a HEL expression into an AST (for advanced use cases)

parse_rule

Parse a HEL expression into an AST (low-level API)

parse_script

Parse and validate a .hel script file (may contain multiple expressions, let bindings)

validate_expression

Validates HEL expression syntax without evaluation

Type Aliases

Expression

Represents a parsed HEL expression