Error Handling

The expression language implements comprehensive error handling to help developers identify and fix issues in their expressions. This document details the various types of errors that can occur, how they are handled, and best practices for dealing with them.

1. Syntax Errors

1.1 Empty Input

The parser immediately validates that input is not empty. Empty expressions are invalid and will result in an error:

""  // Error: empty input

1.2 Invalid Expression Structure

The parser checks for proper expression structure and reports specific errors for malformed expressions:

// Missing operands
price ==        // Error: incomplete comparison
status and      // Error: missing right operand

// Invalid operator placement
not == value    // Error: invalid not operator placement
field == !123   // Error: invalid negation placement

// Unclosed expressions
status in "active"  // Error: missing parentheses

2. Function-Related Errors

2.1 Function Name Validation

Function names must follow strict naming rules:

// Must start with @
length(field)        // Error: function without @ prefix

// Cannot start with numbers
@123length(field)    // Error: invalid function name

// Cannot contain special characters
@length-test(field)  // Error: invalid function name characters

// Cannot be empty
@(field)             // Error: empty function name

2.2 Function Call Structure

Function calls must be properly structured:

// Must include parentheses
@length             // Error: missing function arguments

// Must be properly closed
@length(field       // Error: unclosed function call

// Cannot be used after field access
field.@length()     // Error: function call after field access

// Arguments must be properly separated
@length(field1 field2)  // Error: invalid arguments (no comma)

2.3 Function Resolution

The expression evaluator validates function existence and argument counts:

// Function must exist in registry
@nonexistent(field)  // Error: undefined function 'nonexistent'

// Argument count must match function definition
@length(arg1, arg2)  // Error: function length expects 1 argument, got 2

3. Type System Errors

3.1 Number Format Validation

Numbers must follow valid format rules:

price == 10.5.5    // Error: invalid number format
amount == 12.      // Error: invalid number format

3.2 Type Mismatches

The evaluator enforces type compatibility in operations:

// String vs Number comparisons
"abc" > 123        // Error: cannot compare string with number

// Boolean context errors
@count(items)      // Error: numeric function used in boolean context

4. Collection Operation Errors

4.1 IN Operator Structure

The IN operator requires proper list structure:

// Must use parentheses
status in "active"      // Error: missing parentheses

// List items must be properly separated
status in ("a" "b")     // Error: missing comma between items

5. Error Handling Best Practices

1. Validate Input Early

   • Check for empty or null expressions before processing
   • Validate basic syntax structure before detailed parsing

2. Provide Clear Error Messages

   • Error messages should indicate both the issue and location
   • Include suggestions for fixing common errors

3. Handle Multiple Errors

   • The parser collects multiple errors when possible
   • This helps fix all issues at once rather than one at a time

4. Type Safety

   • Always validate type compatibility in operations
   • Ensure function arguments match expected types

5. Function Validation

   • Verify function existence before evaluation
   • Validate argument count and types
   • Check return type compatibility with context

8. Common Error Patterns and Solutions

Error Pattern	Example	Solution
Missing Operand	status ==	Provide right-hand operand: status == "active"
Invalid Function	@123test()	Use valid function name: @test()
Type Mismatch	"abc" > 123	Compare compatible types: length > 123
Malformed List	in ("a" "b")	Use commas: in ("a", "b")
Invalid Number	amount == 12.	Use valid number format: amount == 12.0

9. Debugging Tips

1. Check error messages for specific syntax issues
2. Verify function names and argument counts
3. Ensure type compatibility in operations
4. Validate collection operation syntax
5. Check for proper expression closure
6. Verify operator placement and usage
7. Ensure proper field access syntax