aimx/

evaluate.rs

//! Core evaluation traits and utilities for AIMX expressions.
//!
//! This module defines the core traits and utilities for evaluating expressions
//! within a context. It provides the foundation for the AIMX evaluation system,
//! including the main [`ExpressionLike`] trait that all expression types implement,
//! and utility functions for type promotion and static evaluation.
//!
//! The evaluation system follows a recursive descent pattern where each expression
//! type knows how to evaluate itself within a given context. This design allows for
//! flexible extension and maintains separation of concerns between parsing and evaluation.
//!
//! # Key Components
//!
//! - [`ExpressionLike`] - The core trait that all expression types implement
//! - [`evaluate_and_promote`] - Helper function for binary operator evaluation with type promotion
//! - [`statically_evaluate`] - Function for evaluating expressions without external context
//!
//! # Architecture
//!
//! The evaluation system is designed around the [`ExpressionLike`] trait, which provides
//! a uniform interface for evaluating different types of expressions. Each expression
//! type (arithmetic, logical, conditional, etc.) implements this trait to provide
//! its specific evaluation logic.
//!
//! ## Type Promotion
//!
//! AIMX uses a sophisticated type promotion system where the left operand's type
//! determines how the right operand is converted. The [`evaluate_and_promote`] function
//! implements this logic for binary operators.
//!
//! ## Static Evaluation
//!
//! The [`statically_evaluate`] function allows evaluating expressions that contain
//! only literals and built-in functions, without requiring external context. This is
//! useful for constant folding, optimization, and testing.
//!
//! # Examples
//!
//! ## Basic Expression Evaluation
//!
//! ```rust
//! use aimx::{aimx_parse, ExpressionLike, Context};
//!
//! let expression = aimx_parse("2 + 3");
//! let mut context = Context::new();
//! let result = expression.evaluate(&mut context).unwrap();
//! assert_eq!(result.to_string(), "5");
//! ```
//!
//! ## Using Static Evaluation
//!
//! ```rust
//! use aimx::{aimx_parse, evaluate::statically_evaluate};
//!
//! let expression = aimx_parse("sqrt(16) + abs(-5)");
//! let result = statically_evaluate(&expression).unwrap();
//! assert_eq!(result.to_string(), "9");
//! ```
//!
//! ## Implementing Custom Expression Types
//!
//! ```rust
//! use aimx::{ExpressionLike, ContextLike, Value, Writer};
//! use anyhow::Result;
//!
//! struct CustomExpression {
//!     value: Value,
//! }
//!
//! impl ExpressionLike for CustomExpression {
//!     fn evaluate(&self, _context: &mut dyn ContextLike) -> Result<Value> {
//!         Ok(self.value.clone())
//!     }
//!
//!     fn write(&self, writer: &mut Writer) {
//!         writer.print_value(&writer.prefix(), &self.value);
//!     }
//!
//!     fn to_sanitized(&self) -> String {
//!         self.value.to_sanitized()
//!     }
//!
//!     fn to_formula(&self) -> String {
//!         self.value.to_formula()
//!     }
//! }
//! ```

use crate::{
    ContextLike,
    Value,
    Reference,
    FunctionRegistry,
    Writer,
};
use anyhow::{anyhow, Result};
use std::mem::replace;

/// Core trait for evaluating expressions and serializing them to text representations.
///
/// This trait defines the interface that all expression types in the AIMX grammar must
/// implement. It provides methods for evaluation within a context and for converting
/// expressions to various string representations.
///
/// The trait is designed to be implemented by all AST node types, allowing the
/// evaluation engine to work uniformly across different expression types without
/// needing to know their specific implementation details.
///
/// # Implementation Guidelines
///
/// When implementing this trait:
/// - **Evaluation**: Should handle type checking, type promotion, and error handling
/// - **Serialization**: Should produce representations that can be parsed back
/// - **Context Usage**: Should properly interact with the context for variable lookup
///
/// # Examples
///
/// ## Basic Usage
///
/// ```rust
/// use aimx::{aimx_parse, ExpressionLike, Context};
///
/// 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");
/// ```
///
/// ## Custom Implementation
///
/// ```rust
/// use aimx::{ExpressionLike, ContextLike, Value, Writer};
/// use anyhow::Result;
///
/// struct ConstantExpression {
///     value: Value,
/// }
///
/// impl ExpressionLike for ConstantExpression {
///     fn evaluate(&self, _context: &mut dyn ContextLike) -> Result<Value> {
///         Ok(self.value.clone())
///     }
///
///     fn write(&self, writer: &mut Writer) {
///         writer.print_value(&writer.prefix(), &self.value);
///     }
///
///     fn to_sanitized(&self) -> String {
///         self.value.to_sanitized()
///     }
///
///     fn to_formula(&self) -> String {
///         self.value.to_formula()
///     }
/// }
/// ```
pub trait ExpressionLike {
    /// Write this expression to the provided writer.
    ///
    /// This method serializes the expression to a text representation using the
    /// writer's current formatting mode. The writer handles indentation, quoting,
    /// and other formatting concerns.
    ///
    /// # Arguments
    ///
    /// * `writer` - The writer to serialize the expression to
    ///
    /// # Examples
    ///
    /// ```rust
    /// use aimx::{aimx_parse, ExpressionLike, Writer, PrintMode, Prefix};
    ///
    /// let expression = aimx_parse("2 + 3");
    /// let mut writer = Writer::new(PrintMode::None, Prefix::None);
    /// expression.write(&mut writer);
    /// let result = writer.finish();
    /// assert_eq!(result, "2 + 3");
    /// ```
    fn write(&self, writer: &mut Writer);
    
    /// Convert this expression to a sanitized string representation.
    ///
    /// This method produces a string with special characters escaped to make it
    /// safe for various contexts like JSON output, HTML embedding, or other
    /// contexts where escaping is required.
    ///
    /// # Returns
    ///
    /// A sanitized string representation of this expression.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use aimx::{aimx_parse, ExpressionLike};
    ///
    /// let expression = aimx_parse(r#""hello" + "world""#);
    /// let sanitized = expression.to_sanitized();
    /// // Contains properly escaped characters
    /// ```
    fn to_sanitized(&self) -> String;
    
    /// Convert this expression to a formula string representation.
    ///
    /// This method produces a string with proper quoting and escaping for use
    /// in formulas. The output should be round-trippable, meaning it can be
    /// parsed back into an equivalent expression.
    ///
    /// # Returns
    ///
    /// A formula string representation of this expression.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use aimx::{aimx_parse, ExpressionLike};
    ///
    /// let expression = aimx_parse("2 + 3");
    /// let formula = expression.to_formula();
    /// assert_eq!(formula, "2 + 3");
    /// ```
    fn to_formula(&self) -> String;

    /// Evaluate the expression within the given context.
    ///
    /// This is the core method that performs the actual evaluation of the expression.
    /// It uses the provided context to resolve variables, call functions, and
    /// perform other runtime operations.
    ///
    /// # Arguments
    ///
    /// * `context` - A mutable reference to the evaluation context that provides
    ///               variable values, function implementations, and other runtime
    ///               information needed for evaluation.
    ///
    /// # Returns
    ///
    /// Returns a `Result<Value>` containing the evaluated result or an error
    /// if evaluation fails.
    ///
    /// # Errors
    ///
    /// This method can return various errors including:
    /// - `Undefined variable` errors when referencing undefined variables
    /// - `Type mismatch` errors when operations are performed on incompatible types
    /// - `Function not found` errors when calling undefined functions
    /// - `Circular reference` errors when detecting infinite recursion
    /// - `Division by zero` errors in arithmetic operations
    /// - Other evaluation errors as appropriate for the expression type
    ///
    /// # Examples
    ///
    /// ```rust
    /// use aimx::{aimx_parse, ExpressionLike, Context};
    ///
    /// let expression = aimx_parse("x + 5");
    /// let mut context = Context::new().with_value("x", aimx::Value::from_number(10.0));
    /// let result = expression.evaluate(&mut context).unwrap();
    /// assert_eq!(result.to_string(), "15");
    /// ```
    fn evaluate(&self, context: &mut dyn ContextLike) -> Result<Value>;
}

/// Helper function to evaluate two expressions and promote the right operand
/// to match the type of the left operand.
///
/// This function implements AIMX's type promotion system for binary operators.
/// It evaluates both operands, then promotes the right operand's type to match
/// the left operand's type according to AIMX grammar rules.
///
/// # Type Promotion Rules
///
/// The type promotion follows these rules:
/// - If the left operand is `Bool`, the right operand is converted to boolean
/// - If the left operand is `Date`, the right operand is converted to date
/// - If the left operand is `Number`, the right operand is converted to number
/// - If the left operand is `Task`, the right operand is converted to task
/// - If the left operand is `Text`, the right operand is converted to text
///
/// # Usage
///
/// This function is primarily used internally by binary operator implementations
/// (arithmetic, logical, relational, etc.) to ensure type compatibility.
///
/// # Arguments
///
/// * `context` - The evaluation context used for evaluating both operands
/// * `left` - The left operand expression
/// * `right` - The right operand expression
///
/// # Returns
///
/// Returns a `Result` containing a tuple of `(Value, Value)` where:
/// - The first value is the evaluated left operand
/// - The second value is the evaluated right operand, promoted to match the left operand's type
///
/// # Errors
///
/// This function can return errors if:
/// - Either operand fails to evaluate
/// - The right operand cannot be promoted to match the left operand's type
///
/// # Examples
///
/// ```rust
/// use aimx::{aimx_parse, evaluate::evaluate_and_promote, Context};
///
/// let mut context = Context::new();
/// let left_expr = aimx_parse("5");
/// let right_expr = aimx_parse("\"3\"");
/// 
/// let (left_val, right_val) = evaluate_and_promote(
///     &mut context,
///     &left_expr,
///     &right_expr
/// ).unwrap();
/// 
/// // The string "3" is promoted to number 3.0
/// assert!(left_val.is_number());
/// assert!(right_val.is_number());
/// assert_eq!(right_val.to_number().unwrap(), 3.0);
/// ```
pub fn evaluate_and_promote(
    context: &mut dyn ContextLike,
    left: &dyn ExpressionLike,
    right: &dyn ExpressionLike,
) -> Result<(Value, Value)> {
    // evaluate left operand
    let left_val = left.evaluate(context)?;
    // evaluate right operand
    let unknown_type = right.evaluate(context)?;
    // promote right result to left operands' type
    match unknown_type.as_type(&left_val) {
        Ok(right_val) => Ok((left_val, right_val)),
        Err(err) => {
            let message = format!("{}~{}", err, right.to_formula());
            Err(anyhow!(message))
        }
    }
    // return matching types
    
}

/// Evaluate an expression statically without external context.
///
/// This function evaluates expressions that contain only literals, operators,
/// and function calls. It cannot evaluate expressions that reference variables
/// or perform assignments. The function uses a thread-safe singleton context
/// with access to all the built-in functions.
///
/// # Purpose
///
/// Static evaluation is useful for:
/// - Constant folding and optimization
/// - Evaluating pure mathematical expressions
/// - Testing and debugging expression parsing
/// - Pre-computing values that don't depend on external state
///
/// # Supported Expressions
///
/// **Allowed:**
/// - All literal values: `42`, `true`, `"hello"`, `_`
/// - Arithmetic operations: `1 + 2 * 3`, `(4 - 1) * 5`
/// - Logical operations: `true & false | true`
/// - Relational operations: `5 > 3`, `2 == 1 + 1`
/// - Conditional expressions: `true ? 1 : 2`
/// - Type casting: `(Number) "123"`, `(Text) 42`
/// - Unary operations: `-5`, `!true`, `+10`
/// - Arrays: `(1, 2, 3)`, `(1, "hello", true)`
/// - Function calls: `abs(-5)`, `max((1, 5, 3))`, `length("hello")`
/// - Method calls: `"hello".length()`, `3.14.round()`
/// - Complex nested expressions: `abs(-5) + max((1, 2)) * length("test")`
///
/// **Not Allowed:**
/// - Variable references: `x + 5`, `my_var`
/// - Assignment operations: `x = 5`
/// - Any expression requiring external context
///
/// # Thread Safety
///
/// This function uses a thread-safe singleton pattern with `OnceLock<Mutex<>>`
/// to ensure that the function registry is initialized only once and can be
/// safely accessed from multiple threads simultaneously.
///
/// # Examples
///
/// ```rust
/// use aimx::{ExpressionLike, evaluate::statically_evaluate};
/// use aimx::expression::parse_expression;
///
/// // Basic arithmetic
/// let (_, expression) = parse_expression("1 + 2 * 3").unwrap();
/// let result = statically_evaluate(&expression).unwrap();
/// // Result: 7
///
/// // Function calls
/// let (_, expression) = parse_expression("abs(-5) + max((1, 2))").unwrap();
/// let result = statically_evaluate(&expression).unwrap();
/// // Result: 7 (5 + 2)
///
/// // Complex expressions
/// let (_, expression) = parse_expression("5 > 3 ? \"yes\" : \"no\"").unwrap();
/// let result = statically_evaluate(&expression).unwrap();
/// // Result: "yes"
///
/// // Array operations
/// let (_, expression) = parse_expression("max((1, 5, 3))").unwrap();
/// let result = statically_evaluate(&expression).unwrap();
/// // Result: 5
/// ```
///
/// # Errors
///
/// This function will return an error for:
/// - Expressions containing variable references
/// - Assignment operations
/// - Invalid syntax or parsing errors
/// - Runtime errors (division by zero, type mismatches, etc.)
/// - Function calls to undefined functions
///
/// ```rust
/// use aimx::{ExpressionLike, evaluate::statically_evaluate};
/// use aimx::expression::parse_expression;
///
/// // This will fail because it references a variable
/// let (_, expression) = parse_expression("x + 5").unwrap();
/// let result = statically_evaluate(&expression);
/// assert!(result.is_err()); // Error: "Non-static expression"
///
/// // This will fail due to division by zero
/// let (_, expression) = parse_expression("10 / 0").unwrap();
/// let result = statically_evaluate(&expression);
/// assert!(result.is_err()); // Error: Division by zero
/// ```
///
/// # Performance
///
/// The singleton pattern ensures that function registration happens only once,
/// making subsequent calls very efficient. The function registry is shared
/// across all threads, minimizing memory usage.
///
/// # Arguments
///
/// * `expression` - The evaluatable expression to statically evaluate
///
/// # Returns
///
/// Returns a `Result<Value>` containing the evaluated result or an error
/// if the expression cannot be evaluated statically.
pub fn statically_evaluate(expression: &dyn ExpressionLike) -> Result<Value> {
    // Create a static context that only supports function calls
    struct StaticContext {
        stack: [(String, Value); 2],
    }

    impl StaticContext {
        pub fn new() -> Self {
            Self {
                stack: [
                    (String::new(), Value::Empty),
                    (String::new(), Value::Empty)
                ],
            }
        }
    }
    
    impl ContextLike for StaticContext {
        fn start_closure(&mut self) -> [(String, Value); 2] {
            replace(&mut self.stack, [
                    (String::new(), Value::Empty),
                    (String::new(), Value::Empty)
                ])
        }

        fn set_key(&mut self, index: usize, identifier: &str) {
            if self.stack[index].0 != *identifier {
                self.stack[index].0 = identifier.to_string();
            }
        }
        fn set_value(&mut self, index: usize, value: &Value) {
            self.stack[index].1 = value.clone();
        }

        fn end_closure(&mut self, stack: [(String, Value); 2]) {
            self.stack = stack;
        }
        fn get_referenced(&mut self, reference: &Reference) -> Result<Value> {
            if *reference == self.stack[0].0 {
                Ok(self.stack[0].1.clone())
            } else if *reference == self.stack[1].0 {
                Ok(self.stack[1].1.clone())
            } else {
                Err(anyhow!("Non-static expression"))
            }
        }
        fn set_referenced(&mut self, reference: &Reference, value: Value) -> Result<()> {
            if *reference == self.stack[0].0 {
                self.stack[0].1 = value;
                Ok(())
            } else if *reference == self.stack[1].0 {
                self.stack[1].1 = value;
                Ok(())
            } else {
                Err(anyhow!("Non-static expression"))
            }
        }
        fn function_call(&mut self, name: &str, arg: Value) -> Result<Value> {
            let registry = FunctionRegistry::read_lock()?;
            registry.function_call(self, name, arg)
        }
        fn method_call(&mut self, name: &str, value: Value, arg: Value) -> Result<Value> {
            let registry = FunctionRegistry::read_lock()?;
            registry.method_call(self, name, value, arg)
        }
        fn inference_call(&mut self, _reference: &Reference, _arg: Value) -> Result<Value> {
            Err(anyhow!("Non-static inference"))
        }
    }
    
    // Use OnceLock for thread-safe one-time initialization
    use std::sync::OnceLock;
    use std::sync::Mutex;
    
    static INSTANCE: OnceLock<Mutex<StaticContext>> = OnceLock::new();
    
    let context = INSTANCE.get_or_init(|| {
        Mutex::new(StaticContext::new())
    });
    
    let mut context = context.lock().unwrap();
    expression.evaluate(&mut *context)
}