aimx/expressions/

equality.rs

//! Equality expression parsing and evaluation for the AIMX language.
//!
//! This module provides parsers and evaluation logic for equality expressions
//! using the `=` and `!=` operators. The AIMX grammar accepts both `==` and `=` 
//! for equality comparison, and both `!=` and `<>` for inequality comparison.
//!
//! Equality expressions form an important part of the expression hierarchy,
//! handling comparisons between values of the same type. They have lower
//! precedence than relational operators (`<`, `<=`, `>`, `>=`) but higher
//! precedence than logical operators (`&`, `|`).
//!
//! # Grammar
//!
//! The equality operators have left associativity and follow this grammar rule:
//!
//! ```text
//! equality := relational (S? ('=' | "!=" | '==') S? relational)?
//! ```
//!
//! Where `S` represents optional whitespace.
//!
//! # Operator Support
//!
//! | Operator | Meaning | Aliases |
//! |----------|---------|---------|
//! | `=` | Equality | `==` |
//! | `!=` | Inequality | |
//!
//! # Examples
//!
//! ```text
//! 5 = 5                    // true (number equality)
//! "hello" != "world"       // true (text inequality)
//! 1 + 2 = 3                // true (arithmetic result comparison)
//! x > 0 = y < 10           // (x > 0) = (y < 10) - relational comparison equality
//! true = false             // false (boolean equality)
//! ```
//!
//! # Type Behavior
//!
//! Equality operations require operands of compatible types. The evaluation
//! system uses type promotion via [`evaluate_and_promote`]
//! to ensure both operands have the same type before comparison:
//!
//! - **Boolean**: `true = false` → `false`
//! - **Number**: `5 = 5.0` → `true` (numeric equality)
//! - **Text**: `"abc" = "abc"` → `true` (string equality)
//! - **Date**: DateTime equality comparison
//! - **Task**: Task status equality comparison
//!
//! # AST Flattening Optimization
//!
//! Like other expression modules, equality expressions use AST flattening
//! where expressions that don't contain equality operators are flattened
//! to [`Primary`] expressions for improved evaluation performance.
//!
//! # Error Handling
//!
//! Equality evaluation provides detailed error messages when type promotion
//! fails or incompatible types are compared:
//!
//! ```text
//! "Expected Bool, Date, Number, Task or Text, found Type1 = Type2 ~formula"
//! ```
//!
//! # Related Modules
//!
//! - [`relational`](super::relational) - Higher precedence relational operations
//! - [`logical`](super::logical) - Lower precedence logical operations
//! - [`expression`](crate::expression) - Top-level expression parsing
//! - [`evaluate`](crate::evaluate) - Core evaluation traits and type promotion

use crate::{
    ContextLike,
    evaluate_and_promote,
    ExpressionLike,
    expressions::{Relational, parse_relational},
    Literal,
    Primary,
    Value,
    Writer,
};
use nom::{
    IResult, Parser, branch::alt, bytes::complete::tag, character::complete::multispace0,
    combinator::map,
};
use std::fmt;
use anyhow::{anyhow, Result};

/// An equality expression node in the abstract syntax tree.
///
/// Represents an equality comparison (`=`, `!=`) or a lower-precedence
/// expression that has been flattened in the AST. This enum is part of
/// the AIMX expression hierarchy and implements the [`ExpressionLike`] trait.
///
/// # AST Flattening
///
/// The `Primary` variant represents an optimization where expressions that
/// don't contain equality operators are flattened to reduce AST depth and
/// improve evaluation performance. This flattening occurs during parsing
/// when an expression doesn't contain any equality operators.
///
/// # Variants
///
/// ## `Equal(Relational, Relational)`
/// Represents an equality comparison using the `=` or `==` operator.
/// The operands are [`Relational`] expressions, which have higher precedence.
///
/// ## `NotEqual(Relational, Relational)`
/// Represents an inequality comparison using the `!=` operator.
/// The operands are [`Relational`] expressions, which have higher precedence.
///
/// ## `Primary(Primary)`
/// A flattened primary expression for optimization. This variant is used
/// when the expression doesn't contain any equality operators.
///
/// # Examples
///
/// ```rust
/// use aimx::expressions::{
///     equality::Equality,
///     relational::Relational,
///     primary::Primary,
/// };
/// use aimx::{Literal, ExpressionLike, Context};
///
/// // This demonstrates how equality expressions can be constructed
/// // In practice, these would be parsed from text expressions
///
/// // Create an equality expression conceptually like: 5 = 5
/// // Create an inequality expression conceptually like: 5 != 10
/// ```
///
/// # See Also
///
/// - [`parse_equality`] - Function to parse equality expressions
/// - [`ExpressionLike`] - Trait for expression evaluation
/// - [`Relational`] - Higher precedence expression type
/// - [`Primary`] - Flattened primary expression type
#[derive(Debug, Clone, PartialEq)]
pub enum Equality {
    Equal(Relational, Relational),
    NotEqual(Relational, Relational),
    /// Primary flattened AST optimization
    Primary(Box<Primary>),
}

/// Internal operator type for equality parsing.
///
/// This enum represents the equality operators during the parsing phase.
/// It's used internally by the parser to distinguish between equality
/// and inequality operations before constructing the final AST.
#[derive(Debug, Clone, Copy, PartialEq)]
enum EqualityOp {
    /// Equality operator (`=`, `==`)
    Equal,
    /// Inequality operator (`!=`)
    NotEqual,
}

/// Parse an equality operator `=`/`==` or `!=` and the following relational expression.
///
/// This internal helper function parses an equality operator followed by
/// a relational expression. It handles optional whitespace and operator aliases.
///
/// # Grammar
///
/// ```text
/// equality_operator := S? ('=' | "!=" | '==') S? relational
/// ```
///
/// Where `S` represents optional whitespace.
///
/// # Returns
///
/// Returns an `IResult` containing:
/// - The remaining input
/// - A tuple of `(EqualityOp, Relational)` representing the operator and right operand
fn equality_operator(input: &str) -> IResult<&str, (EqualityOp, Relational)> {
    let (input, _) = multispace0.parse(input)?;
    let (input, equality_op) = alt((
        map(tag("!="), |_| EqualityOp::NotEqual),
        map(tag("=="), |_| EqualityOp::Equal),
        map(tag("="), |_| EqualityOp::Equal),
    ))
    .parse(input)?;
    let (input, _) = multispace0.parse(input)?;
    let (input, relational) = parse_relational(input)?;
    Ok((input, (equality_op, relational)))
}

/// Parse an equality expression from a string slice.
///
/// This function is the main entry point for parsing equality expressions.
/// It handles the complete equality grammar rule, including optional whitespace
/// and operator aliases. The parser follows the AIMX precedence rules, where
/// equality operators have lower precedence than relational operators.
///
/// # Grammar
///
/// The function implements this grammar rule:
/// ```text
/// equality := relational (S? ('=' | "!=" | '==') S? relational)?
/// ```
///
/// Where `S` represents optional whitespace.
///
/// # Parsing Strategy
///
/// 1. First attempts to parse a relational expression
/// 2. If an equality operator is found, parses the second relational expression
/// 3. If no equality operator is found, flattens the expression to [`Primary`]
/// 4. Returns the parsed [`Equality`] expression and remaining input
///
/// # Operator Support
///
/// The parser accepts these equality operators:
/// - `=` (equality) - also accepts `==` as an alias
/// - `!=` (inequality)
///
/// # AST Flattening
///
/// When no equality operator is found, the parser flattens the expression
/// to optimize evaluation performance. This means expressions like `5` or
/// `x > y` are represented as [`Equality::Primary`] rather than creating
/// unnecessary AST nodes.
///
/// # Arguments
///
/// * `input` - The input string slice to parse
///
/// # Returns
///
/// Returns an [`IResult`] containing:
/// - The remaining unparsed input (if any)
/// - The parsed [`Equality`] expression
///
/// # Examples
///
/// ## Basic Equality
///
/// ```rust
/// use aimx::expressions::equality::{parse_equality, Equality};
///
/// let (remaining, expr) = parse_equality("5 = 5").unwrap();
/// assert_eq!(remaining, "");
/// assert!(matches!(expr, Equality::Equal(_, _)));
/// ```
///
/// ## Inequality with Whitespace
///
/// ```rust
/// use aimx::expressions::equality::{parse_equality, Equality};
///
/// let (remaining, expr) = parse_equality("5 != 10").unwrap();
/// assert_eq!(remaining, "");
/// assert!(matches!(expr, Equality::NotEqual(_, _)));
/// ```
///
/// ## Operator Aliases
///
/// ```rust
/// use aimx::expressions::equality::{parse_equality, Equality};
///
/// // Both '=' and '==' are accepted
/// let (_, expr1) = parse_equality("5 = 5").unwrap();
/// let (_, expr2) = parse_equality("5 == 5").unwrap();
/// assert!(matches!(expr1, Equality::Equal(_, _)));
/// assert!(matches!(expr2, Equality::Equal(_, _)));
/// ```
///
/// ## Complex Expressions
///
/// ```rust
/// use aimx::expressions::equality::{parse_equality, Equality};
///
/// // Equality with relational expressions
/// let (remaining, expr) = parse_equality("x > 0 = y < 10").unwrap();
/// assert_eq!(remaining, "");
/// assert!(matches!(expr, Equality::Equal(_, _)));
///
/// // Equality with arithmetic expressions
/// let (remaining, expr) = parse_equality("2 + 3 = 5").unwrap();
/// assert_eq!(remaining, "");
/// assert!(matches!(expr, Equality::Equal(_, _)));
/// ```
///
/// ## Flattened Expressions
///
/// ```rust
/// use aimx::expressions::equality::{parse_equality, Equality};
///
/// // Expressions without equality operators are flattened
/// let (remaining, expr) = parse_equality("5").unwrap();
/// assert_eq!(remaining, "");
/// assert!(matches!(expr, Equality::Primary(_)));
///
/// let (remaining, expr) = parse_equality("x > y").unwrap();
/// assert_eq!(remaining, "");
/// assert!(matches!(expr, Equality::Primary(_)));
/// ```
///
/// ## Chaining Behavior
///
/// ```rust
/// use aimx::expressions::equality::{parse_equality, Equality};
///
/// // Equality operations are not chained
/// let (remaining, expr) = parse_equality("1 = 1 = 1").unwrap();
/// assert_eq!(remaining, "= 1"); // Only first equality is parsed
/// assert!(matches!(expr, Equality::Equal(_, _)));
/// ```
///
/// # Error Handling
///
/// The function returns [`IResult`] which can contain parsing errors.
/// Common errors include:
/// - Invalid operator syntax
/// - Malformed relational expressions
/// - Unexpected end of input
///
/// # See Also
///
/// - [`Equality`] - The expression type returned by this function
/// - [`parse_relational`] - Function for parsing relational expressions
/// - [`ExpressionLike`] - Trait for expression evaluation
pub fn parse_equality(input: &str) -> IResult<&str, Equality> {
    let (input, first) = parse_relational(input)?;
    if let Ok((input, (equality_op, second))) = equality_operator(input) {
        let equality = match equality_op {
            EqualityOp::Equal => Equality::Equal(first, second),
            EqualityOp::NotEqual => Equality::NotEqual(first, second),
        };
        Ok((input, equality))
    } else {
        let equality = match first {
            Relational::Primary(primary) => Equality::Primary(primary),
            _ => Equality::Primary(Box::new(Primary::Relational(first))),
        };
        Ok((input, equality))
    }
}

impl ExpressionLike for Equality {
    /// Evaluate this equality expression within the given context.
    ///
    /// This method implements the core evaluation logic for equality expressions.
    /// It handles both equality (`=`) and inequality (`!=`) comparisons, using
    /// type promotion to ensure both operands have compatible types.
    ///
    /// # Evaluation Strategy
    ///
    /// 1. **Equality Comparison** (`Equality::Equal`):
    ///    - Evaluates both operands using [`evaluate_and_promote`]
    ///    - Promotes the right operand to match the left operand's type
    ///    - Compares values of the same type using `==` operator
    ///    - Returns `true` if equal, `false` otherwise
    ///
    /// 2. **Inequality Comparison** (`Equality::NotEqual`):
    ///    - Evaluates both operands using [`evaluate_and_promote`]
    ///    - Promotes the right operand to match the left operand's type
    ///    - Compares values of the same type using `!=` operator
    ///    - Returns `true` if not equal, `false` otherwise
    ///
    /// 3. **Flattened Expression** (`Equality::Primary`):
    ///    - Delegates evaluation to the underlying primary expression
    ///
    /// # Type Support
    ///
    /// Equality operations support these value types:
    /// - `Bool` - Boolean equality comparison
    /// - `Date` - DateTime equality comparison
    /// - `Number` - Numeric equality comparison
    /// - `Text` - String equality comparison
    /// - `Task` - Task status equality comparison
    ///
    /// # Error Handling
    ///
    /// Returns an error if:
    /// - Type promotion fails (incompatible types)
    /// - Either operand evaluation fails
    /// - Comparison of unsupported types is attempted
    ///
    /// Error messages include type information and the original formula:
    /// ```text
    /// "Expected Bool, Date, Number, Task or Text, found Type1 = Type2 ~formula"
    /// ```
    ///
    /// # Arguments
    ///
    /// * `context` - The evaluation context providing variable values and function implementations
    ///
    /// # Returns
    ///
    /// Returns a `Result<Value>` containing:
    /// - `Value::Literal(Literal::Bool(true))` if comparison evaluates to true
    /// - `Value::Literal(Literal::Bool(false))` if comparison evaluates to false
    /// - An error if evaluation fails
    ///
    /// # Examples
    ///
    /// ```rust
    /// use aimx::expressions::equality::{Equality, parse_equality};
    /// use aimx::{ExpressionLike, Context, Literal, Value};
    ///
    /// let mut context = Context::new();
    ///
    /// // Evaluate equality: 5 = 5
    /// let expr = parse_equality("5 = 5").unwrap().1;
    /// let result = expr.evaluate(&mut context).unwrap();
    /// assert_eq!(result, Value::Literal(Literal::Bool(true)));
    ///
    /// // Evaluate inequality: 5 != 10
    /// let expr = parse_equality("5 != 10").unwrap().1;
    /// let result = expr.evaluate(&mut context).unwrap();
    /// assert_eq!(result, Value::Literal(Literal::Bool(true)));
    ///
    /// // Evaluate with type promotion: 5 = "5"
    /// let expr = parse_equality("5 = \"5\"").unwrap().1;
    /// let result = expr.evaluate(&mut context).unwrap();
    /// assert_eq!(result, Value::Literal(Literal::Bool(true)));
    /// ```
    fn evaluate(&self, context: &mut dyn ContextLike) -> Result<Value> {
        match self {
            Equality::Equal(left, right) => {
                let (left_val, right_val) = evaluate_and_promote(context, left, right)?;
                // For equality, we can compare values of the same type
                let result = match (&left_val, &right_val) {
                    (Value::Literal(Literal::Bool(l)), Value::Literal(Literal::Bool(r))) => l == r,
                    (Value::Literal(Literal::Date(l)), Value::Literal(Literal::Date(r))) => l == r,
                    (Value::Literal(Literal::Number(l)), Value::Literal(Literal::Number(r))) => l == r,
                    (Value::Literal(Literal::Text(l)), Value::Literal(Literal::Text(r))) => l == r,
                    (Value::Literal(Literal::Task(_, l)), Value::Literal(Literal::Task(_, r))) => l == r,
                    _ => return Err(anyhow!(
                        "Expected Bool, Date, Number, Task or Text, found {} = {}~{}",
                        left_val.type_as_string(),
                        right_val.type_as_string(),
                        self.to_formula(),
                    )),
                };
                Ok(Value::Literal(Literal::Bool(result)))
            }
            Equality::NotEqual(left, right) => {
                let (left_val, right_val) = evaluate_and_promote(context, left, right)?;
                // For inequality, we can compare values of the same type
                let result = match (&left_val, &right_val) {
                    (Value::Literal(Literal::Bool(l)), Value::Literal(Literal::Bool(r))) => l != r,
                    (Value::Literal(Literal::Date(l)), Value::Literal(Literal::Date(r))) => l != r,
                    (Value::Literal(Literal::Number(l)), Value::Literal(Literal::Number(r))) => l != r,
                    (Value::Literal(Literal::Text(l)), Value::Literal(Literal::Text(r))) => l != r,
                    (Value::Literal(Literal::Task(_, l)), Value::Literal(Literal::Task(_, r))) => l != r,
                    _ => return Err(anyhow!(
                        "Expected Bool, Date, Number, Task or Text, found {} != {}~{}",
                        left_val.type_as_string(),
                        right_val.type_as_string(),
                        self.to_formula(),
                    )), // Different types are not equal
                };
                Ok(Value::Literal(Literal::Bool(result)))
            }
            Equality::Primary(primary) => primary.evaluate(context),
        }
    }

    /// Write this equality 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,
    /// operator spacing, and other formatting concerns.
    ///
    /// # Serialization Strategy
    ///
    /// - **Equality Comparison** (`Equality::Equal`):
    ///   - Writes left operand
    ///   - Writes `" = "` operator with spaces
    ///   - Writes right operand
    ///
    /// - **Inequality Comparison** (`Equality::NotEqual`):
    ///   - Writes left operand
    ///   - Writes `" != "` operator with spaces
    ///   - Writes right operand
    ///
    /// - **Flattened Expression** (`Equality::Primary`):
    ///   - Delegates writing to the underlying primary expression
    ///
    /// # Arguments
    ///
    /// * `writer` - The writer to serialize the expression to
    ///
    /// # Examples
    ///
    /// ```rust
    /// use aimx::expressions::equality::{Equality, parse_equality};
    /// use aimx::{Writer, PrintMode, Prefix};
    ///
    /// // This demonstrates the general pattern for writing equality expressions
    /// // In practice, these would be used internally by the expression evaluator
    ///
    /// // Writing an equality expression like "5 = 5"
    /// // Writing an inequality expression like "5 != 10"
    /// ```
    fn write(&self, writer: &mut Writer) {
        match self {
            Equality::Equal(left, right) => {
                writer.write_binary_op(left, " = ", right);
            }
            Equality::NotEqual(left, right) => {
                writer.write_binary_op(left, " != ", right);
            }
            Equality::Primary(primary) => primary.write(writer),
        }
    }
    
    /// Convert this equality 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.
    ///
    fn to_sanitized(&self) -> String {
        let mut writer = Writer::sanitizer();
        self.write(&mut writer);
        writer.finish()
    }
    
    /// Convert this equality 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.
    ///
    fn to_formula(&self) -> String {
        let mut writer = Writer::formulizer();
        self.write(&mut writer);
        writer.finish()
    }
}

impl fmt::Display for Equality {
    /// Format this equality expression as a string.
    ///
    /// This implementation delegates to the [`write`](ExpressionLike::write) method
    /// using a string-based writer with default formatting. The output is suitable
    /// for display purposes and debugging.
    ///
    /// # Format
    ///
    /// The formatting follows these conventions:
    /// - Operators are surrounded by spaces: `5 = 5`, `5 != 10`
    /// - Complex expressions are properly parenthesized
    /// - Literals are formatted according to their type
    /// - Variables and references are displayed as-is
    ///
    /// # Examples
    ///
    /// ```rust
    /// use aimx::expressions::equality::{Equality, parse_equality};
    ///
    /// let expr = parse_equality("5 = 5").unwrap().1;
    /// assert_eq!(expr.to_string(), "5 = 5");
    ///
    /// let expr = parse_equality("x > 0 = y < 10").unwrap().1;
    /// assert_eq!(expr.to_string(), "x > 0 = y < 10");
    ///
    /// let expr = parse_equality("5").unwrap().1;
    /// assert_eq!(expr.to_string(), "5");
    /// ```
    ///
    /// # See Also
    ///
    /// - [`ExpressionLike::write`] - The underlying serialization method
    /// - [`ExpressionLike::to_formula`] - For round-trippable formula representation
    /// - [`ExpressionLike::to_sanitized`] - For sanitized output
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let mut writer = Writer::stringizer();
        self.write(&mut writer);
        write!(f, "{}", writer.finish())
    }
}