aimx/values/

errata.rs

//! Expression and evaluation error representation.
//!
//! This module defines the `Errata` enum that represents errors encountered during
//! expression parsing and evaluation in the AIMX expression engine. `Errata` captures 
//! error information at different levels of detail, from simple error messages to 
//! full diagnostic information including the problematic formula and location.
//!
//! The `Errata` type is used throughout the AIMX expression engine to provide
//! detailed error information that helps users understand what went wrong and
//! where the error occurred in their expressions.
//!
//! # Examples
//!
//! Creating different levels of error information:
//!
//! ```
//! use aimx::values::Errata;
//!
//! // Basic error with just a reason
//! let basic_error = Errata::One { reason: "Syntax Error".to_string() };
//! 
//! // Error with formula context
//! let formula_error = Errata::Two {
//!     reason: "Division by zero".to_string(),
//!     formula: "10 / 0".to_string(),
//! };
//! 
//! // Full diagnostic error
//! let diagnostic_error = Errata::Three {
//!     reason: "Unexpected token".to_string(),
//!     formula: "1 + * 2".to_string(),
//!     location: "* 2".to_string(),
//! };
//! ```

use crate::{
    ContextLike,
    Expression,
    ExpressionLike,
    Value,
    Writer,
};
use std::fmt;
use anyhow::Result;

/// Represents expression and evaluation errors with varying levels of detail.
///
/// The `Errata` enum captures error information at different diagnostic levels:
/// - `One`: Basic error reason only
/// - `Two`: Error reason and the problematic formula or expression
/// - `Three`: Full diagnostic information including reason, formula, and location
///
/// This enum is used throughout the AIMX expression engine to provide
/// detailed error information that helps users understand what went wrong
/// and where the error occurred in their expressions.
///
/// # Examples
///
/// Creating different levels of error information:
///
/// ```rust
/// use aimx::values::Errata;
///
/// // Basic error with just a reason
/// let basic_error = Errata::One { reason: "Syntax Error".to_string() };
/// 
/// // Error with formula context
/// let formula_error = Errata::Two {
///     reason: "Division by zero".to_string(),
///     formula: "10 / 0".to_string(),
/// };
/// 
/// // Full diagnostic error
/// let diagnostic_error = Errata::Three {
///     reason: "Unexpected token".to_string(),
///     formula: "1 + * 2".to_string(),
///     location: "* 2".to_string(),
/// };
/// ```
///
/// # Display Format
///
/// When displayed, `Errata` produces formatted output showing:
/// - The error reason
/// - The problematic formula or expression
/// - Location indicators (arrows pointing to the problematic area)
///
/// Example output for a diagnostic error:
/// ```text
/// Unexpected token
/// 1 + * 2
///    ^
/// ```
#[derive(Debug, Clone, PartialEq)]
pub enum Errata {
    /// Basic error with only a reason
    One{reason: String},
    /// Error with reason and formula context
    Two{reason: String, formula: String},
    /// Full diagnostic error with reason, formula, and location
    Three{reason: String, formula: String, location: String},
}

impl Errata {
    /// Creates a new `Value::Errata` with only a reason.
    ///
    /// This is the simplest form of error representation, containing only
    /// the error message without additional context.
    ///
    /// # Arguments
    ///
    /// * `reason` - The error message or description
    ///
    /// # Returns
    ///
    /// Returns a `Value::Errata` containing the basic error information.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use aimx::{Value, values::Errata};
    ///
    /// let error_value = Errata::new_reason("Syntax Error".to_string());
    /// assert!(matches!(error_value, Value::Errata(_)));
    /// ```
    pub fn new_reason(reason: String) -> Value {
        Value::Errata(Errata::One{reason})
    }

    /// Creates a new `Value::Errata` with a reason and formula context.
    ///
    /// This provides more context by including the problematic formula
    /// along with the error message.
    ///
    /// # Arguments
    ///
    /// * `reason` - The error message or description
    /// * `formula` - The problematic formula or expression
    ///
    /// # Returns
    ///
    /// Returns a `Value::Errata` containing the error with formula context.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use aimx::{Value, values::Errata};
    ///
    /// let error_value = Errata::new_reason_formula(
    ///     "Division by zero".to_string(),
    ///     "10 / 0".to_string()
    /// );
    /// assert!(matches!(error_value, Value::Errata(_)));
    /// ```
    pub fn new_reason_formula(reason: String, formula: String) -> Value {
        Value::Errata(Errata::Two{reason, formula})
    }

    /// Creates a new `Value::Errata` with full diagnostic information.
    ///
    /// This provides the most detailed error information including the reason,
    /// the problematic formula, and the specific location within the formula.
    ///
    /// # Arguments
    ///
    /// * `reason` - The error message or description
    /// * `formula` - The problematic formula or expression
    /// * `location` - The specific location within the formula where the error occurred
    ///
    /// # Returns
    ///
    /// Returns a `Value::Errata` containing full diagnostic error information.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use aimx::{Value, values::Errata};
    ///
    /// let error_value = Errata::new_reason_formula_location(
    ///     "Unexpected token".to_string(),
    ///     "1 + * 2".to_string(),
    ///     "* 2".to_string()
    /// );
    /// assert!(matches!(error_value, Value::Errata(_)));
    /// ```
    pub fn new_reason_formula_location(reason: String, formula: String, location: String) -> Value {
        Value::Errata(Errata::Three{reason, formula, location})
    }

    /// Creates a new `Expression::Errata` with a reason and expression context.
    ///
    /// This is similar to `new_reason_formula` but creates an `Expression` variant
    /// instead of a `Value` variant.
    ///
    /// # Arguments
    ///
    /// * `reason` - The error message or description
    /// * `expression` - The problematic expression
    ///
    /// # Returns
    ///
    /// Returns an `Expression::Errata` containing the error with expression context.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use aimx::{Expression, values::Errata};
    ///
    /// let error_expression = Errata::new_reason_expression(
    ///     "Undefined variable".to_string(),
    ///     "undefined_var".to_string()
    /// );
    /// assert!(matches!(error_expression, Expression::Errata(_)));
    /// ```
    pub fn new_reason_expression(reason: String, expression: String) -> Expression {
        Expression::Errata(Errata::Two{reason, formula: expression})
    }

    /// Creates a new `Expression::Errata` with full diagnostic information.
    ///
    /// This provides the most detailed error information for expression errors,
    /// including the reason, the problematic expression, and the specific location.
    ///
    /// # Arguments
    ///
    /// * `reason` - The error message or description
    /// * `expression` - The problematic expression
    /// * `location` - The specific location within the expression where the error occurred
    ///
    /// # Returns
    ///
    /// Returns an `Expression::Errata` containing full diagnostic error information.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use aimx::{Expression, values::Errata};
    ///
    /// let error_expression = Errata::new_reason_expression_location(
    ///     "Syntax error".to_string(),
    ///     "1 + ".to_string(),
    ///     "+ ".to_string()
    /// );
    /// assert!(matches!(error_expression, Expression::Errata(_)));
    /// ```
    pub fn new_reason_expression_location(reason: String, expression: String, location: String) -> Expression {
        Expression::Errata(Errata::Three{reason, formula: expression, location})
    }

    /// Returns the error reason string.
    ///
    /// This method extracts the error message from any `Errata` variant.
    ///
    /// # Returns
    ///
    /// Returns a string slice containing the error reason.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use aimx::values::Errata;
    ///
    /// let errata = Errata::One { reason: "Syntax Error".to_string() };
    /// assert_eq!(errata.reason(), "Syntax Error");
    /// ```
    pub fn reason(&self) -> &str {
        match self {
            Errata::Three{reason, formula: _, location: _} => reason,
            Errata::Two{reason, formula: _} => reason,
            Errata::One{reason} => reason,
        }
    } 

    /// Returns the problematic formula or expression.
    ///
    /// For `Errata::Two` and `Errata::Three` variants, returns the formula
    /// that caused the error. For `Errata::One`, returns an empty string.
    ///
    /// # Returns
    ///
    /// Returns a string slice containing the problematic formula.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use aimx::values::Errata;
    ///
    /// let errata = Errata::Two {
    ///     reason: "Division by zero".to_string(),
    ///     formula: "10 / 0".to_string(),
    /// };
    /// assert_eq!(errata.formula(), "10 / 0");
    /// ```
    pub fn formula(&self) -> &str {
        match self {
            Errata::Three{reason: _, formula, location: _} => formula,
            Errata::Two{reason: _, formula} => formula,
            Errata::One{reason: _} => &"",
        }
    }

    /// Returns the specific location within the formula where the error occurred.
    ///
    /// Only `Errata::Three` variants contain location information.
    /// For other variants, returns an empty string.
    ///
    /// # Returns
    ///
    /// Returns a string slice containing the error location.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use aimx::values::Errata;
    ///
    /// let errata = Errata::Three {
    ///     reason: "Unexpected token".to_string(),
    ///     formula: "1 + * 2".to_string(),
    ///     location: "* 2".to_string(),
    /// };
    /// assert_eq!(errata.location(), "* 2");
    /// ```
    pub fn location(&self) -> &str {
        match self {
            Errata::Three{reason: _, formula: _, location} => location,
            _ => &"",
        }
    }
}

impl ExpressionLike for Errata {
    /// Evaluates the error expression, returning the error as a value.
    ///
    /// Since `Errata` represents error information rather than an evaluatable
    /// expression, this method simply returns the error wrapped in a `Value::Errata`.
    ///
    /// # Arguments
    ///
    /// * `_context` - The evaluation context (unused for errors)
    ///
    /// # Returns
    ///
    /// Returns `Ok(Value::Errata(self.clone()))` containing the error information.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use aimx::{values::Errata, ExpressionLike, Context};
    ///
    /// let errata = Errata::One { reason: "Test error".to_string() };
    /// let mut context = Context::new();
    /// let result = errata.evaluate(&mut context).unwrap();
    /// assert!(matches!(result, aimx::Value::Errata(_)));
    /// ```
    fn evaluate(&self, _context: &mut dyn ContextLike) -> Result<Value> {
        Ok(Value::Errata(self.clone()))
    }

    /// Writes the error information to the provided writer.
    ///
    /// This method delegates to the writer's `print_errata` method to format
    /// the error information according to the writer's mode (string, sanitized, formula).
    ///
    /// # Arguments
    ///
    /// * `writer` - The writer to write the error information to
    ///
    /// # Examples
    ///
    /// ```rust
    /// use aimx::{values::Errata, ExpressionLike, Writer};
    ///
    /// let errata = Errata::Two {
    ///     reason: "Division by zero".to_string(),
    ///     formula: "10 / 0".to_string(),
    /// };
    /// let mut writer = Writer::stringizer();
    /// errata.write(&mut writer);
    /// let output = writer.finish();
    /// assert!(output.contains("Division by zero"));
    /// assert!(output.contains("10 / 0"));
    /// ```
    fn write(&self, writer: &mut Writer) {
        let (reason, formula, location) = match self {
            Errata::Three{reason, formula, location}
                => (reason, formula, location),
            Errata::Two{reason, formula}
                => (reason, formula, &"".to_owned()),
            Errata::One{reason}
                => (reason, &"".to_owned(), &"".to_owned()),
        };
        writer.print_errata(reason, formula, location);
    }
    
    /// Converts the error to a sanitized string representation.
    ///
    /// This method produces a string with special characters escaped,
    /// making it safe for JSON-compatible or safely quoted output.
    ///
    /// # Returns
    ///
    /// Returns a sanitized string representation of the error.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use aimx::{values::Errata, ExpressionLike};
    ///
    /// let errata = Errata::One { reason: "Error <message>".to_string() };
    /// let sanitized = errata.to_sanitized();
    /// assert!(sanitized.contains("Error <message>"));
    /// ```
    fn to_sanitized(&self) -> String {
        let mut writer = Writer::sanitizer();
        self.write(&mut writer);
        writer.finish()
    }
    
    /// Converts the error to a formula string representation.
    ///
    /// This method produces a string with proper quoting and escaping
    /// for use in formulas. For `Errata`, this typically returns just
    /// the original formula or expression that caused the error.
    ///
    /// # Returns
    ///
    /// Returns a formula string representation of the error.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use aimx::{values::Errata, ExpressionLike};
    ///
    /// let errata = Errata::Two {
    ///     reason: "Division by zero".to_string(),
    ///     formula: "10 / 0".to_string(),
    /// };
    /// let formula = errata.to_formula();
    /// assert_eq!(formula, "10 / 0");
    /// ```
    fn to_formula(&self) -> String {
        let mut writer = Writer::formulizer();
        self.write(&mut writer);
        writer.finish()
    }
}

impl fmt::Display for Errata {
    /// Formats the error for display using the default string representation.
    ///
    /// This implementation uses the stringizer writer mode to produce a
    /// human-readable representation of the error, including the reason,
    /// formula, and location indicators.
    ///
    /// # Arguments
    ///
    /// * `f` - The formatter to write to
    ///
    /// # Returns
    ///
    /// A `fmt::Result` indicating success or failure of the formatting operation.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use aimx::values::Errata;
    ///
    /// let errata = Errata::Three {
    ///     reason: "Unexpected token".to_string(),
    ///     formula: "1 + * 2".to_string(),
    ///     location: "* 2".to_string(),
    /// };
    /// let display_string = format!("{}", errata);
    /// assert!(display_string.contains("Unexpected token"));
    /// assert!(display_string.contains("1 + * 2"));
    /// assert!(display_string.contains("^"));
    /// ```
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let mut writer = Writer::stringizer();
        self.write(&mut writer);
        write!(f, "{}", writer.finish())
    }
}