Enum Expression

pub enum Expression {
    Empty,
    Errata(Errata),
    Single(Conditional),
    Array(Vec<Box<Conditional>>),
    ArgumentList(Vec<Box<Closure>>),
    Primary(Box<Primary>),
}

The root of the Abstract Syntax Tree (AST) for parsed AIMX expressions.

This enum represents all possible types of expressions that can be parsed and evaluated in the AIMX language. It encompasses the complete grammar hierarchy from the top-level expression types down to individual literals and references through the flattened Primary variant.

The Expression enum serves as the entry point for expression evaluation and provides methods for checking expression properties and invoking evaluation.

Variants

• Empty - An empty expression representing no operation
• Errata - An expression containing parsing or evaluation errors
• Single - A single conditional expression (ternary operator)
• Array - An array of conditional expressions separated by commas
• ArgumentList - A list of closure expressions for function arguments
• Primary - A flattened primary expression for optimization

AST Flattening

The Primary variant represents an optimization where expressions that consist solely of primary expressions (literals, references, parentheses) are flattened to reduce AST depth and improve evaluation performance. This flattening occurs during parsing when an expression doesn’t contain any higher-level operators.

Examples

Parsing expressions with the public API:

use aimx::{aimx_parse, ExpressionLike, Context};

// Parse a simple literal (gets flattened to Primary)
let expression = aimx_parse("42");
assert!(matches!(expression, aimx::Expression::Primary(_)));

// Parse conditional expressions (not flattened)
let expression = aimx_parse("true ? 1 : 0");
assert!(matches!(expression, aimx::Expression::Single(_)));

// Parse another conditional expression
let expression = aimx_parse("5 > 3 ? \"yes\" : \"no\"");
assert!(matches!(expression, aimx::Expression::Single(_)));

See Also

• parse_expression - Function that produces Expression values
• ExpressionLike - Trait for expression evaluation
• Primary - Flattened primary expression type

Variants

Empty

Errata(Errata)

Single(Conditional)

Array(Vec<Box<Conditional>>)

ArgumentList(Vec<Box<Closure>>)

Primary(Box<Primary>)

Primary flattened AST optimization

Implementations

impl Expression

pub fn is_empty(&self) -> bool

Check if this expression is empty.

Returns true if this expression represents an empty expression (no operation), false otherwise.

Examples

use aimx::expression::{parse_expression, Expression};

let (_, empty_expr) = parse_expression("").unwrap();
assert!(empty_expr.is_empty());

let (_, non_empty_expr) = parse_expression("42").unwrap();
assert!(!non_empty_expr.is_empty());

pub fn has_error(&self) -> bool

Check if this expression contains an error.

Returns true if this expression represents an error condition (parsing failure or evaluation error), false otherwise.

Examples

use aimx::expression::{parse_expression, Expression};
use aimx::{aimx_parse, ExpressionLike};

// Valid expressions do not have errors
let expression = aimx_parse("42");
assert!(!expression.has_error());

// Parsing errors are wrapped in Errata variants
let expression = aimx_parse("2 + * 3"); // Invalid syntax
assert!(expression.has_error());

pub fn invoke(&self, context: &mut dyn ContextLike) -> Value

Evaluate this expression and return a Value, handling errors gracefully. Invoke is the evaluation entry point for expression formulas, whereas Expression::evaluate is used within the expression to evaluate nested expression instances.

This method provides a simplified evaluation interface that catches evaluation errors and converts them into Errata values. Unlike evaluate, this method never returns a Result error - all errors are captured in the returned Value.

Arguments

• context - The evaluation context providing variable values and function implementations

Returns

Returns a Value representing the result of evaluation. If evaluation succeeds, returns the computed value. If evaluation fails, returns an Errata value containing error information.

Examples

use aimx::expression::{parse_expression, Expression};
use aimx::{Context, ExpressionLike};

// Parse an expression
let (_, expression) = parse_expression("2 + 2").unwrap();
let mut context = Context::new();
let result = expression.invoke(&mut context);
assert_eq!(result.to_string(), "4");

See Also

• ExpressionLike::evaluate - The underlying evaluation method that returns Result
• Value - The result type returned by evaluation

Trait Implementations

impl Clone for Expression

fn clone(&self) -> Expression

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Expression

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Expression

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Format this expression as a string.

This implementation delegates to the write method using a string-based writer.

impl ExpressionLike for Expression

fn evaluate(&self, context: &mut dyn ContextLike) -> Result<Value>

Evaluate this expression within the given context. Evaluate is called within an expression formula to evaluate nested expressions.

This method recursively evaluates the expression tree, delegating to the appropriate evaluation methods for each expression variant.

Expression::invoke is the evaluation entry point for expression formulas.

Arguments

• context - The evaluation context providing variable values and function implementations

Returns

Returns a Result containing the evaluated Value if successful, or an error if evaluation fails.

Evaluation Strategy

• Empty expressions return Value::Empty
• Errata expressions return Value::Empty
• Single expressions delegate to Conditional::evaluate
• Array expressions evaluate each element and return an array
• ArgumentList expressions evaluate each closure and return an array
• Primary expressions delegate to Primary::evaluate

fn write(&self, writer: &mut Writer)

Write this expression to a Writer for formatting.

This method recursively writes the expression tree to the provided writer, producing a formatted representation of the expression.

Arguments

• writer - The writer to write the formatted expression to

fn to_sanitized(&self) -> String

Convert this expression to a sanitized string representation.

Sanitized expressions are suitable for display purposes and may omit certain implementation details or sensitive information.

fn to_formula(&self) -> String

Convert this expression to its original formula representation.

The formula representation attempts to reconstruct the original expression text as it was parsed.

impl PartialEq for Expression

fn eq(&self, other: &Expression) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for Expression