Function aimx_parse

pub fn aimx_parse(input: &str) -> Expression

Parse an AIMX expression string into an Abstract Syntax Tree (AST).

This is the main entry point for parsing AIM Expressions. It transforms a string representation of an expression into an Expression AST that can be evaluated within a Context. The parser handles the complete AIMX grammar including operator precedence, type annotations, arrays, closures, and conditional expressions.

Arguments

• input - A string slice containing the AIMX expression to parse

Returns

Returns an Expression representing the parsed abstract syntax tree. If parsing succeeds, the returned expression can be evaluated to produce a Value. If parsing fails, the returned expression will contain error information wrapped in an Errata variant.

Grammar Coverage

The parser supports the complete AIMX grammar including:

• Arithmetic expressions: 2 + 3 * 4
• Boolean logic: true & false | !flag
• Conditional expressions: 5 > 3 ? "yes" : "no"
• Function calls: sqrt(16) + abs(-5)
• Array expressions: (1, 2, 3).sum()
• Closures: x => x * 2
• Type annotations: (Number) "42"
• Task definitions: [x] "Completed task"
• Variable references: employee.salary * 0.15

Error Handling

The parser returns an Expression that may contain error information in the following scenarios:

• Syntax Errors: Malformed expressions that violate AIMX grammar rules
• Incomplete Expressions: Input that ends before a complete expression is parsed
• Unexpected Input: Valid expressions followed by additional unparsed text

Errors are represented as Errata variants within the returned Expression, allowing the calling code to handle parsing failures gracefully.

Examples

Basic usage for parsing and evaluating expressions:

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

// Parse a simple arithmetic expression
let expression = aimx_parse("2 + 3 * 4");
let mut context = Context::new();
let result = expression.evaluate(&mut context).unwrap();
assert_eq!(result.to_string(), "14");

// Parse a complex expression with functions and arrays
let expression = aimx_parse("sqrt(pow(2, 2) + max((1, 3))).round_to(5)");
let result = expression.evaluate(&mut context).unwrap();
assert_eq!(result.to_string(), "2.64575");

// Or use a simpler example:
let expression = aimx_parse("sqrt(16)");
let result = expression.evaluate(&mut context).unwrap();
assert_eq!(result.to_string(), "4");

// Handle parsing errors gracefully
let expression = aimx_parse("2 + * 3"); // Invalid syntax
if expression.has_error() {
    println!("Parsing failed: {}", expression);
}

Implementation Details

The parser uses a recursive descent approach built on the nom parser combinator library. It handles operator precedence through a hierarchy of expression types, with the highest precedence operators being parsed first. The parser is designed to be efficient and handle the complete AIMX grammar without backtracking.

After successful parsing, the function validates that no input remains unparsed. If additional text follows a valid expression, it is treated as an error to prevent ambiguity in expression boundaries.

Panics

This function does not panic. All parsing errors are captured and returned as Errata variants within the Expression result.

See Also

• Expression - The abstract syntax tree returned by the parser
• ExpressionLike - Trait for evaluating expressions
• Context - Evaluation context for expression evaluation
• Value - Runtime values produced by expression evaluation
• Errata - Error information wrapper