aimx/

value.rs

//! Runtime value representation for AIM Expressions (AIMX).
//!
//! This module defines the [`Value`] enum that represents runtime values produced
//! during expression evaluation. The `Value` type serves as the primary data
//! structure that flows through the expression evaluation engine, representing
//! all possible data types that can be manipulated by AIMX expressions.
//!
//! Unlike the compile-time [`Literal`] enum which represents static values,
//! `Value` can represent dynamically evaluated results, arrays of values,
//! closures, and special workflow-related types. This makes it the central
//! runtime entity for the entire AIMX evaluation system.
//!
//! # Design Philosophy
//!
//! The `Value` type is designed with several core principles in mind:
//! - **Tree-like Structure**: Values form a tree where arrays can contain other values, enabling
//!   complex data representations.
//! - **Type Safety**: Comprehensive type checking and conversion capabilities following AIMX grammar rules
//! - **Error Handling**: First-class error values that preserve diagnostic information throughout evaluation
//! - **Memory Efficiency**: Recursive data structures are boxed to prevent stack overflow
//! - **Thread Safety**: Values can be safely used across threads in concurrent workflows
//!
//! # Key Features
//!
//! - **Comprehensive Type System**: Supports all AIMX data types including literals,
//!   arrays, closures, and workflow-specific types
//! - **Automatic Type Conversion**: Provides intuitive type promotion and conversion
//!   methods following AIMX grammar rules
//! - **Tree-like Structure**: Arrays can contain other values, allowing nested and
//!   complex data representations
//! - **Error Handling**: Includes error values that capture evaluation failures
//! - **Workflow Integration**: Supports workflow-specific types like nodes, format,
//!   and eval for agentic workflow applications
//!
//! # Core Concepts
//!
//! ## Value Hierarchy
//!
//! The `Value` enum represents a unified type hierarchy where all values can be categorized into:
//! - **Base Values**: Empty, Error, and Literal values represent atomic values
//! - **Composite Values**: Arrays and closures enable structured and functional programming
//! - **Special Values**: Workflow-specific types for inference functionality
//!
//! # Types and Variants
//!
//! The `Value` enum encompasses all possible runtime data types in the AIMX system:
//!
//! ## Base Values
//! - **Array**: Collections of values, allowing for nested data structures
//! - **Closure**: First-class anonymous functions for functional programming
//! - **Empty**: Represents an empty or uninitialized value
//! - **Errata**: Captures expression and evaluation error conditions with diagnostic information
//! - **Literal**: Encapsulates literal values (Bool, Date, Number, Task, Text)
//!
//! ## Special Values
//! - **Assignment**: Variable references for workflow assignments
//! - **Format**: Inference output formatting data
//! - **Eval**: Inference evaluation data
//! - **Node**: References to workflow files and nodes
//!
//! # Examples
//!
//! ## Creating Values
//!
//! ```rust
//! use aimx::{Value, Literal};
//!
//! // Creating different types of values
//! let empty_value = Value::Empty;
//! let literal_value = Value::Literal(Literal::from_number(42.0));
//! let array_value = Value::Array(vec![
//!     Box::new(Value::Literal(Literal::from_text("hello".to_string()))),
//!     Box::new(Value::Literal(Literal::from_number(123.0)))
//! ]);
//!
//! // Checking value types
//! assert!(empty_value.is_empty());
//! assert!(literal_value.is_literal());
//! assert!(literal_value.is_number());
//! assert!(array_value.is_array());
//!
//! // Converting values
//! let num_as_text = literal_value.clone().as_text().unwrap();
//! assert!(num_as_text.is_text());
//! ```
//!
//! ## Using Values in Expression Evaluation
//!
//! ```rust
//! use aimx::{Value, Literal, ExpressionLike, Context, Reference, ContextLike};
//!
//! let mut context = aimx::Context::new();
//! 
//! // For this example, we'll just demonstrate creating and using values
//! let price_value = Value::Literal(Literal::from_number(100.0));
//! let tax_rate_value = Value::Literal(Literal::from_number(0.08));
//! 
//! // Calculate total: price * (1 + tax_rate)
//! let total = 100.0 * (1.0 + 0.08);
//! assert_eq!(total, 108.0);
//! ```
//!
//! ## Type Conversion Examples
//!
//! ```rust
//! use aimx::{Value, Literal};
//!
//! // Type promotion in expressions
//! let number_value = Value::Literal(Literal::from_number(42.0));
//! 
//! // Convert number to text
//! let text_value = number_value.clone().as_text().unwrap();
//! assert!(text_value.is_text());
//! 
//! // Convert number to boolean (truthiness)
//! let bool_value = number_value.clone().as_bool();
//! assert!(bool_value.to_literal().to_bool());
//! 
//! // Convert number to date (Unix timestamp)
//! let date_value = number_value.as_date().unwrap();
//! assert!(date_value.is_date());
//! ```
//!
//! ## Working with Arrays
//!
//! ```rust
//! use aimx::{Value, Literal};
//!
//! // Create nested arrays
//! let nested_array = Value::Array(vec![
//!     Box::new(Value::Literal(Literal::from_text("first".to_string()))),
//!     Box::new(Value::Array(vec![
//!         Box::new(Value::Literal(Literal::from_number(1.0))),
//!         Box::new(Value::Literal(Literal::from_number(2.0)))
//!     ]))
//! ]);
//!
//! // Check array properties
//! assert!(nested_array.is_array());
//! 
//! // Convert single value to array
//! let single_value = Value::Literal(Literal::from_number(42.0));
//! let as_array = single_value.as_array();
//! assert!(as_array.is_array());
//! ```
//!
//! # Type Conversion Rules
//!
//! AIMX follows intuitive type conversion rules when values need to be promoted
//! to different types. The conversion methods (`as_text`, `as_number`, etc.) follow
//! these principles:
//!
//! - **Type Promotion Strategy**: Left-operand-first promotion where the left operand's type
//!   dictates how the right operand is converted
//! - **Error Handling**: Conversion operations gracefully handle invalid conversions by returning
//!   appropriate error values or `Result` types
//! - **Idempotency**: Converting a value to its own type typically returns the value unchanged
//!
//! - **Empty values** remain empty in most conversions
//! - **Booleans**: `true`/`false` values maintain their semantic meaning
//! - **Numbers**: Numeric values can be converted to text, dates, or tasks
//! - **Text**: String values can be parsed into numbers, dates, or remain as text
//! - **Dates**: Date values can be converted to timestamps or formatted text
//! - **Tasks**: Task values preserve their status and description semantics
//! - **Arrays**: Conversions are applied element-wise to array contents
//!
//! # Implementation Details
//!
//! The `Value` enum forms the foundation of the AIMX runtime system. It supports:
//! - **AIMX Grammar Compliance**: All conversion rules match the AIMX specification
//! - **Memory Efficiency**: Uses `Box<Value>` for recursive data structures to avoid stack overflow
//! - **Thread Safety**: Can be safely used across threads in concurrent scenarios
//! - **Serialization**: Provides formatting methods for different display contexts
//!
//! # See Also
//!
//! - [`Literal`] - Compile-time fixed value representations
//! - [`ExpressionLike`] - Trait for expression evaluation
//! - [`ContextLike`] - Evaluation context interface
//! - [`Value` parsing](parse_value) - Function to parse value literals from text
use nom::{
    IResult,
    Parser,
    character::complete::{char, multispace0},
    multi::many1,
    sequence::delimited,
};
use crate::{
    ContextLike,
    expressions::Closure,
    Reference,
    ExpressionLike,
    parse_literal,
    Literal,
    Node,
    values::{Errata, Eval, Format},
    Typedef,
    Prefix,
    PrintMode,
    Writer,
};
use std::fmt;
use std::cmp::Ordering;
use anyhow::{anyhow, Result};

/// Runtime value representation during expression evaluation.
///
/// This enum encapsulates all possible runtime values that can result from
/// evaluating expressions in the AIMX language. Values are produced when expressions
/// are evaluated within a context and represent the actual data that flows through
/// the expression evaluation engine.
///
/// The `Value` type forms a tree-like structure where arrays can contain other values,
/// allowing for nested and complex data representations. This is the primary data
/// structure used throughout the evaluation phase of the expression engine.
///
/// # Variants
///
/// - **Empty** - Represents an empty or uninitialized value, typically used as a placeholder
///   or result of operations that return no meaningful data
/// - **Errata(Errata)** - Contains evaluation errors with detailed context information
/// - **Literal(Literal)** - A single literal value (boolean, number, text, date, or task)
/// - **Array(`Vec<Box<Value>>`)** - An array of values, allowing for collections of data
/// - **Closure(Closure)** - A first-class anonymous function for functional programming
/// - **Assignment(Reference)** - A variable reference used for workflow assignments
/// - **Format(Format)** - Inference output formatting data for agentic workflows
/// - **Eval(Eval)** - Inference evaluation data for agentic workflows
/// - **Node(Node)** - A reference to a workflow file or node
///
/// # Type Hierarchy
///
/// The `Value` enum represents the runtime counterpart to the compile-time [`Typedef`] enum.
/// While [`Typedef`] represents type definitions, `Value` represents actual runtime data
/// that conforms to those types.
///
/// # Examples
///
/// ## Creating Values
///
/// ```rust
/// use aimx::{Value, Literal};
///
/// // Creating different value types
/// let empty = Value::Empty;
/// let number = Value::Literal(Literal::from_number(42.0));
/// let text = Value::Literal(Literal::from_text("Hello".to_string()));
/// let array = Value::Array(vec![
///     Box::new(Value::Literal(Literal::from_number(1.0))),
///     Box::new(Value::Literal(Literal::from_number(2.0))),
///     Box::new(Value::Literal(Literal::from_number(3.0))),
/// ]);
///
/// // Type checking
/// assert!(empty.is_empty());
/// assert!(number.is_number());
/// assert!(text.is_text());
/// assert!(array.is_array());
///
/// // Converting between types
/// let text_from_number = number.clone().as_text().unwrap();
/// assert!(text_from_number.is_text());
/// ```
///
/// ## Using Values in Workflow Context
///
/// ```rust
/// use aimx::{Value, Literal, Context, Reference, ContextLike};
///
/// let mut context = aimx::Context::new();
/// 
/// // Use assignment references for inference results
/// let assignment = Value::Assignment(aimx::Reference::new("_result"));
/// 
/// // Use closure for functional programming (simplified example)
/// // In practice, closures are parsed from expressions like "x => x * 2"
/// ```
///
/// ## Type Conversions
///
/// Values can be converted between different types using the `as_*` methods:
///
/// ```rust
/// use aimx::{Value, Literal};
///
/// let value = Value::Literal(Literal::from_number(42.0));
/// let as_text = value.clone().as_text().unwrap();
/// assert!(as_text.is_text());
/// 
/// let as_bool = value.as_bool();
/// assert!(as_bool.is_bool());
/// ```
///
/// # Implementation Notes
///
/// - **Memory Management**: Arrays use `Box<Value>` to avoid infinite recursion and stack overflow
/// - **Error Handling**: The `Errata` variant captures detailed error information for debugging
/// - **Workflow Integration**: Special variants like `Node`, `Format`, and `Eval` support agentic workflows
/// - **Type Safety**: All conversion methods return `Result` types to handle conversion failures gracefully
///
/// # See Also
///
/// - [`Literal`] - Compile-time literal value representation
/// - [`Typedef`] - Type definition system
/// - [`ExpressionLike`] - Trait for expression evaluation
/// - [`ContextLike`] - Evaluation context interface
#[derive(Debug, Clone, PartialEq)]
pub enum Value {
    Empty,
    Errata(Errata),
    Literal(Literal),
    Array(Vec<Box<Value>>),
    Closure(Closure),
    Assignment(Reference),
    Format(Format),
    Eval(Eval),
    Node(Node),
}

impl Value {
    /// Create a Value from a number.
    ///
    /// This is a convenience method for creating number values.
    ///
    /// # Arguments
    ///
    /// * `number` - The numeric value
    ///
    /// # Examples
    ///
    /// ```rust
    /// use aimx::Value;
    ///
    /// let number_value = Value::from_number(42.0);
    /// assert!(number_value.is_number());
    /// ```
    pub fn from_number(number: f64) -> Value {
        Value::Literal(Literal::from_number(number))
    }

    /// Check if this value of the specified type definition.
    ///
    /// This method determines whether this value conforms to the specified type
    /// definition. For arrays, it checks if the first element (if any) matches
    /// the type. For literals, it checks if the literal matches the type.
    ///
    /// # Arguments
    ///
    /// * `typedef` - The type definition to check against
    ///
    /// # Returns
    ///
    /// Returns `true` if this value matches the specified type, `false` otherwise.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use aimx::{Value, Literal, Typedef};
    ///
    /// let number_value = Value::Literal(Literal::from_number(42.0));
    /// assert!(number_value.is_of_type(&Typedef::Number));
    ///
    /// let text_value = Value::Literal(Literal::from_text("Hello".to_string()));
    /// assert!(text_value.is_of_type(&Typedef::Text));
    ///
    /// let array_value = Value::Array(vec![
    ///     Box::new(Value::Literal(Literal::from_number(1.0))),
    ///     Box::new(Value::Literal(Literal::from_number(2.0))),
    /// ]);
    /// assert!(array_value.is_of_type(&Typedef::Number));
    /// ```
    pub fn is_of_type(&self, typedef: &Typedef) -> bool {
        match self {
            Value::Empty => true,
            Value::Errata(_) => false,
            Value::Literal(literal) => typedef.is_literal() && literal.is_type(typedef),
            Value::Array(array) => {
                if typedef.is_any_array() {
                    true
                }
                else if array.len() > 0 {
                    let literal_typedef = typedef.as_literal();
                    array.last().unwrap().as_ref().is_of_type(&literal_typedef)
                } else {
                    false
                }
            }
            Value::Closure(_) => typedef.is_closure(),
            Value::Assignment(_) => true,
            Value::Format(_) => typedef.is_format(),
            Value::Eval(_) => typedef.is_eval(),
            Value::Node(_) => typedef.is_node(),
        }
    }

    /// Check if this value matches the actual type definition, considering nested arrays.
    ///
    /// This method provides a more precise type checking than `is_of_type` by properly
    /// handling nested array structures and ensuring the actual type matches the definition.
    ///
    /// # Arguments
    ///
    /// * `typedef` - The type definition to check against
    ///
    /// # Returns
    ///
    /// Returns `true` if this value's actual type matches the specified type definition,
    /// `false` otherwise.
    pub fn is_actual_type(&self, typedef: &Typedef) -> bool {
        match self {
            Value::Empty => true,
            Value::Errata(_) => false,
            Value::Literal(literal) => typedef.is_literal() && literal.is_type(typedef),
            Value::Array(array) => {
                if typedef.is_any_array() {
                    true
                } else if typedef.is_literal() {
                    false
                } else if array.len() > 0 {
                    let last = array.last().unwrap().as_ref();
                    if last.is_array() {
                         last.is_actual_type(typedef)
                    } else {
                        let literal_typedef = typedef.as_literal();
                        last.is_actual_type(&literal_typedef)
                    }
                    
                } else {
                    false
                }
            }
            Value::Closure(_) => typedef.is_closure(),
            Value::Assignment(_) => false,
            Value::Format(_) => typedef.is_format(),
            Value::Eval(_) => typedef.is_eval(),
            Value::Node(_) => typedef.is_node(),
        }
    }

    /// Get the type of this value.
    ///
    /// # Returns
    ///
    /// Returns a `Result<Typedef>` containing the type of this value,
    /// or an error if this is an Empty value.
    pub fn get_type(&self) -> Result<Typedef> {
        match self {
            Value::Empty => Err(anyhow!("Expecting type, found Empty")),
            Value::Errata(_) => Err(anyhow!("Expecting type, found Error")),
            Value::Literal(literal) => literal.get_type(),
            Value::Array(array) => {
                if array.len() > 0 {
                    let typedef = array.last().unwrap().as_ref().get_type()?;
                    Ok(typedef.as_array())
                } else {
                    Ok(Typedef::Array)
                }
            }
            Value::Closure(_) => Ok(Typedef::Closure),
            Value::Assignment(_) => Ok(Typedef::Any),
            Value::Format(_) => Ok(Typedef::Format),
            Value::Eval(_) => Ok(Typedef::Eval),
            Value::Node(_) => Ok(Typedef::Node),
        }
    }

    /// Convert this value to match the type of another value.
    ///
    /// This method performs type conversion according to the AIMX grammar's
    /// type promotion rules, converting this value to match the type
    /// of the provided reference value.
    ///
    /// Type conversion follows these rules:
    /// - If the reference value is a `Bool`, converts this value to boolean
    /// - If the reference value is a `Date`, converts this value to date
    /// - If the reference value is a `Number`, converts this value to number
    /// - If the reference value is a `Task`, converts this value to task
    /// - If the reference value is `Text`, converts this value to text
    ///
    /// # Arguments
    ///
    /// * `value` - The reference value whose type determines the conversion
    ///
    /// # Returns
    ///
    /// Returns a `Result<Value>` containing the converted value or an error
    /// if conversion is not possible (e.g., trying to convert Empty to a specific type).
    ///
    /// # Examples
    ///
    /// ```rust
    /// use aimx::{Value, Literal};
    ///
    /// let number_value = Value::Literal(Literal::from_number(42.0));
    /// let text_reference = Value::Literal(Literal::from_text("example".to_string()));
    ///
    /// // Convert number to text
    /// let converted = number_value.clone().as_type(&text_reference).unwrap();
    /// assert!(converted.is_text());
    ///
    /// let bool_reference = Value::Literal(Literal::from_bool(true));
    /// // Convert number to boolean
    /// let converted = number_value.as_type(&bool_reference).unwrap();
    /// assert!(converted.is_bool());
    /// ```
    pub fn as_type(self, value: &Value) -> Result<Value> {
        let literal = value.to_literal();
        match literal {
            Literal::Empty => Err(anyhow!("Expecting type as {}, found Empty", literal.type_as_string())),
            Literal::Bool(_) => Ok(self.as_bool()),
            Literal::Date(_) => self.as_date(),
            Literal::Number(_) => self.as_number(),
            Literal::Task(..) => self.as_task(),
            Literal::Text(_) => self.as_text(),
        }
    }

    /// Convert this value to a specific type definition.
    ///
    /// This method performs type conversion according to the AIMX grammar's
    /// type promotion rules, converting this value to match the specified
    /// type definition.
    ///
    /// # Arguments
    ///
    /// * `typedef` - The type definition to convert to
    ///
    /// # Returns
    ///
    /// Returns a `Result<Value>` containing the converted value or an error
    /// if conversion is not possible.
    ///
    /// # Type Conversion Rules
    ///
    /// The conversion follows these rules:
    /// - **Any**: Returns the value unchanged
    /// - **Array**: Converts non-arrays to single-element arrays
    /// - **Literal types**: Converts values to the specified literal type
    /// - **Array types**: Converts arrays to the specified element type
    /// - **Closure**: Only allows conversion if already a closure
    ///
    /// # Examples
    ///
    /// ```rust
    /// use aimx::{Value, Literal, Typedef};
    ///
    /// let number_value = Value::Literal(Literal::from_number(42.0));
    /// 
    /// // Convert to text
    /// let text_value = number_value.clone().to_type(&Typedef::Text).unwrap();
    /// assert!(text_value.is_text());
    /// 
    /// // Convert to array
    /// let array_value = number_value.to_type(&Typedef::NumberArray).unwrap();
    /// assert!(array_value.is_array());
    /// ```
    pub fn to_type(self, typedef: &Typedef) -> Result<Value> {
        // Downgrade to array
        if self.is_array() && typedef.is_literal() {
            let literal = self.to_literal().clone().to_type(typedef)?;
            Ok(Value::Literal(literal))
        } else {
            match typedef {
                // Literally any value
                Typedef::Any => Ok(self),
                // Upgrade array
                Typedef::Array => {
                    if self.is_array() {
                        Ok(self)
                    } else {
                        Ok(self.as_array())
                    }
                }
                Typedef::Bool => {
                    if self.is_literal() {
                        Ok(self.as_bool())
                    }
                    else {
                        Ok(self.as_literal().as_bool())
                    }
                }
                Typedef::BoolArray => {
                    if self.is_array() {
                        Ok(self.as_bool())
                    } else {
                        Ok(self.as_bool().as_array())
                    }
                }
                Typedef::Date => self.as_date(),
                Typedef::DateArray => {
                    if self.is_array() {
                        self.as_date()
                    } else {
                        let value = self.as_date()?;
                        Ok(value.as_array())
                    }
                }
                Typedef::Number  => self.as_number(),
                Typedef::NumberArray => {
                    if self.is_array() {
                        self.as_number()
                    } else {
                        let value = self.as_number()?;
                        Ok(value.as_array())
                    }
                }
                Typedef::Task => self.as_task(),
                Typedef::TaskArray => {
                    if self.is_array() {
                        self.as_task()
                    } else {
                        let value = self.as_task()?;
                        Ok(value.as_array())
                    }
                }
                Typedef::Text => self.as_text(),
                Typedef::TextArray => {
                    if self.is_array() {
                        self.as_text()
                    } else {
                        let value = self.as_text()?;
                        Ok(value.as_array())
                    }
                }
                Typedef::Closure => if self.is_closure() {
                        Ok(self)
                    } else {
                        Err(anyhow!("Expecting Closure, found {}", self.type_as_string()))
                    }
                Typedef::Eval | Typedef::Format | Typedef::Node =>
                    Err(anyhow!("Invalid type conversion from {} to {}", self.type_as_string(), typedef.as_string()))
            }
        }
    }

    /// Check if this value is empty.
    ///
    /// Returns `true` if this value is the `Empty` variant, `false` otherwise.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use aimx::Value;
    ///
    /// let empty_value = Value::Empty;
    /// let non_empty_value = Value::Literal(aimx::Literal::from_number(42.0));
    ///
    /// assert!(empty_value.is_empty());
    /// assert!(!non_empty_value.is_empty());
    /// ```
    pub fn is_empty(&self) -> bool {
        match self {
            Value::Empty | Value::Literal(Literal::Empty) => true,
            _ => false,
        }
    }

    /// Check if this value contains an error.
    ///
    /// Returns `true` if this value represents an error condition,
    /// `false` otherwise.
    pub fn has_error(&self) -> bool {
        match self {
            Value::Errata(_) => true,
            _ => false,
        }
    }

    /// Check if this value contains an error (alias for has_error).
    ///
    /// Returns `true` if this value represents an error condition,
    /// `false` otherwise.
    pub fn has_errata(&self) -> bool {
        self.has_error()
    }

    /// Check if this value is a literal.
    ///
    /// Returns `true` if this value is the `Literal` variant, `false` otherwise.
    /// This includes all scalar types: booleans, numbers, text, dates, and tasks.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use aimx::{Value, Literal};
    ///
    /// let literal_value = Value::Literal(Literal::from_number(42.0));
    /// let array_value = Value::Array(vec![]);
    /// let empty_value = Value::Empty;
    ///
    /// assert!(literal_value.is_literal());
    /// assert!(!array_value.is_literal());
    /// assert!(!empty_value.is_literal());
    /// ```
    pub fn is_literal(&self) -> bool {
        match self {
            Value::Literal(_) => true,
            _ => false,
        }
    }


    /// Check if this value is constant (immutable).
    ///
    /// Returns `true` if this value represents a constant value that
    /// cannot be modified during evaluation, `false` otherwise.
    pub fn is_constant(&self) -> bool {
        match self {
            Value::Literal(_)
            | Value::Array(_) => true,
            _ => false,
        }
    }

    /// Get a reference to the literal representation of this value.
    ///
    /// Returns a reference to a [`Literal`] representing this value's type and content:
    /// - For literal values, returns a reference to the embedded literal
    /// - For arrays, returns the literal representation of the last element or `Literal::Empty` for empty arrays
    /// - For all other value types, returns `Literal::Empty`
    ///
    /// This method is useful for type checking and introspection, as it provides
    /// access to the underlying literal type without consuming the value.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use aimx::{Value, Literal};
    ///
    /// let literal_value = Value::Literal(Literal::from_number(42.0));
    /// assert!(literal_value.to_literal().is_number());
    ///
    /// let array_value = Value::Array(vec![
    ///     Box::new(Value::Literal(Literal::from_text("first".to_string()))),
    ///     Box::new(Value::Literal(Literal::from_text("last".to_string()))),
    /// ]);
    /// assert!(array_value.to_literal().is_text());
    ///
    /// let empty_value = Value::Empty;
    /// assert!(empty_value.to_literal().is_empty());
    /// ```
    pub fn to_literal(&self) -> &Literal {
        match self {
            Value::Literal(literal) => literal,
            Value::Array(array) => {
                if array.len() > 0 {
                    array.last().unwrap().as_ref().to_literal()
                } else {
                    &Literal::Empty
                }
            }
            _ => &Literal::Empty,
        }
    }

    /// Convert this value to its literal representation.
    ///
    /// This method consumes the value and returns the underlying literal representation:
    /// - For literal values, returns the literal itself
    /// - For arrays, returns the last element or `Value::Empty` for empty arrays
    /// - For all other value types, returns `Value::Empty`
    ///
    /// # Examples
    ///
    /// ```rust
    /// use aimx::{Value, Literal};
    ///
    /// let literal_value = Value::Literal(Literal::from_number(42.0));
    /// let literal = literal_value.as_literal();
    /// assert!(literal.is_literal());
    ///
    /// let array_value = Value::Array(vec![
    ///     Box::new(Value::Literal(Literal::from_text("first".to_string()))),
    ///     Box::new(Value::Literal(Literal::from_text("last".to_string()))),
    /// ]);
    /// let literal = array_value.as_literal();
    /// assert!(literal.is_literal());
    ///
    /// let empty_value = Value::Empty;
    /// let literal = empty_value.as_literal();
    /// assert!(literal.is_empty());
    /// ```
    pub fn as_literal(self) -> Value {
        match self {
            Value::Literal(_) => self,
            Value::Array(mut array) => {
                if &array.len() > &0 {
                    match array.pop() {
                        Some(value) => *value,
                        None => Value::Empty,
                    }
                } else {
                    Value::Empty
                }
            }
            _ => Value::Empty,
        }
    }

    /// Check if this value is an array.
    ///
    /// Returns `true` if this value is the `Array` variant, `false` otherwise.
    ///
    /// # Examples
    ///
    /// ```
    /// use aimx::{Value, Literal};
    ///
    /// let array_value = Value::Array(vec![]);
    /// let literal_value = Value::Literal(Literal::from_number(42.0));
    /// let empty_value = Value::Empty;
    ///
    /// assert!(array_value.is_array());
    /// assert!(!literal_value.is_array());
    /// assert!(!empty_value.is_array());
    /// ```
    pub fn is_array(&self) -> bool {
        match self {
            Value::Array(_) => true,
            _ => false,
        }
    }


    /// Convert this value to an array representation.
    ///
    /// If the value is already an array or empty, returns it unchanged.
    /// If the value is a literal, wraps it in a single-element array.
    /// Otherwise, returns an empty value.
    pub fn as_array(self) -> Value {
        // Early return if no conversion is needed
        if self.is_empty() || self.is_array() {
            self
        } else if self.is_literal() {
            let mut array: Vec<Box<Value>> = Vec::new();
            array.push(Box::new(self));
            Value::Array(array)
        } else {
            Value::Empty
        }
    }

    /// Check if this value represents a boolean.
    ///
    /// Returns `true` if this value is a literal boolean, `false` otherwise.
    ///
    /// # Examples
    ///
    /// See [`Value::as_bool`] for examples of boolean conversion behavior.
    pub fn is_bool(&self) -> bool {
        match self {
            Value::Literal(Literal::Bool(_)) => true,
            _ => false,
        }
    }

    /// Convert this value to a boolean representation.
    ///
    /// Performs type conversion to boolean according to the AIMX grammar's
    /// truthiness rules:
    /// - Empty values: Always false
    /// - Numbers: 0 is false, non-zero is true
    /// - Text: Empty string is false, non-empty is true
    /// - Dates: Always true (they exist)
    /// - Arrays: Empty array is false, non-empty is true
    /// - Tasks: Status determines value, no status is false
    ///
    /// # Examples
    ///
    /// ```
    /// use aimx::{Value, Literal};
    ///
    /// let number_zero = Value::Literal(Literal::from_number(0.0));
    /// let as_bool = number_zero.as_bool();
    /// // Zero converts to false
    /// assert!(!as_bool.to_literal().to_bool());
    ///
    /// let number_non_zero = Value::Literal(Literal::from_number(42.0));
    /// let as_bool = number_non_zero.as_bool();
    /// // Non-zero converts to true
    /// assert!(as_bool.to_literal().to_bool());
    ///
    /// let empty_text = Value::Literal(Literal::from_text("".to_string()));
    /// let as_bool = empty_text.as_bool();
    /// // Empty string converts to false
    /// assert!(!as_bool.to_literal().to_bool());
    /// ```
    pub fn as_bool(self) -> Value {
        // Early return if no conversion is needed
        match &self {
            Value::Empty => return self,
            Value::Literal(literal) if literal.is_bool() => return self,
            _ => {}
        }
        // Now do the conversion for cases that need it
        match self {
            Value::Literal(literal) => Value::Literal(literal.as_bool()),
            Value::Array(array) => {
                let bool_array: Vec<Box<Value>> = array
                    .into_iter()
                    .map(|box_value| {
                        let value: Value = *box_value; 
                        if value.is_bool() {
                            Box::new(value)
                        } else {
                            let value = value.as_bool();
                            Box::new(value)
                        }
                    })
                    .collect();
                Value::Array(bool_array)
            }
            _ => Value::Empty,
        }
    }

    /// Check if this value represents a date.
    ///
    /// Returns `true` if this value is a literal date, `false` otherwise.
    ///
    /// # Examples
    ///
    /// ```
    /// use aimx::{Value, Literal};
    ///
    /// let date_value = Value::Literal(Literal::Date(jiff::civil::DateTime::new(2023, 1, 1, 0, 0, 0, 0).unwrap()));
    /// let number_value = Value::Literal(Literal::from_number(42.0));
    ///
    /// assert!(date_value.is_date());
    /// assert!(!number_value.is_date());
    /// ```
    pub fn is_date(&self) -> bool {
        match self {
            Value::Literal(Literal::Date(_)) => true,
            _ => false,
        }
    }

    /// Convert this value to a date representation.
    ///
    /// Attempts to convert the value to a date according to the AIMX grammar's
    /// conversion rules:
    /// - Empty values: Remain empty (no conversion needed)
    /// - Dates: No conversion needed
    /// - Text: Parsed as date if possible (e.g., "2023-01-01")
    /// - Number: Interpreted as Unix timestamp
    /// - Boolean: true becomes Unix epoch + 1 second, false becomes Unix epoch
    /// - Task: Text component parsed as date if possible
    ///
    /// # Returns
    ///
    /// Returns a `Result<Value>` containing the converted date value or an error
    /// if conversion is not possible.
    ///
    /// # Examples
    ///
    /// ```
    /// use aimx::{Value, Literal};
    ///
    /// let text_date = Value::Literal(Literal::from_text("2023-01-01".to_string()));
    /// let as_date = text_date.as_date().unwrap();
    /// assert!(as_date.is_date());
    ///
    /// let number_timestamp = Value::Literal(Literal::from_number(1672531200.0)); // 2023-01-01 UTC
    /// let as_date = number_timestamp.as_date().unwrap();
    /// assert!(as_date.is_date());
    /// ```
    pub fn as_date(self) -> Result<Value> {
        // Early return if no conversion is needed
        match &self {
            Value::Empty => return Ok(self),
            Value::Literal(literal) if literal.is_date() => return Ok(self),
            _ => {}
        }
        // Now do the conversion for cases that need it
        Ok(match self {
            Value::Literal(literal) => Value::Literal(literal.as_date()?),
            Value::Array(array) => {
                let date_array: Result<Vec<Box<Value>>, anyhow::Error> = array
                    .into_iter()
                    .map(|box_value| {
                        let value: Value = *box_value; 
                        if value.is_date() {
                            Ok(Box::new(value))
                        } else {
                            let converted_value = value.as_date()?;
                            Ok(Box::new(converted_value))
                        }
                    })
                    .collect();
                Value::Array(date_array?)
            }
            _ => return Err(anyhow!("Cannot convert {} to Date", self.type_as_string())),
        })
    }

    /// Check if this value represents a number.
    ///
    /// Returns `true` if this value is a literal number, `false` otherwise.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use aimx::{Value, Literal};
    ///
    /// let number_value = Value::Literal(Literal::from_number(42.0));
    /// let text_value = Value::Literal(Literal::from_text("hello".to_string()));
    ///
    /// assert!(number_value.is_number());
    /// assert!(!text_value.is_number());
    /// ```
    pub fn is_number(&self) -> bool {
        match self {
            Value::Literal(Literal::Number(_)) => true,
            _ => false,
        }
    }

    /// Convert this value to a number representation.
    ///
    /// Attempts to convert the value to a number according to the AIMX grammar's
    /// conversion rules:
    /// - Empty values: Remain empty (no conversion needed)
    /// - Numbers: No conversion needed
    /// - Text: Parsed as number if it represents a valid numeric literal (e.g., "42", "3.14")
    /// - Boolean: false becomes 0, true becomes 1
    /// - Date: Converted to Unix timestamp
    /// - Task: Status determines value (true=1, false=-1, none=0)
    ///
    /// # Returns
    ///
    /// Returns a `Result<Value>` containing the converted number value or an error
    /// if conversion is not possible.
    ///
    /// # Examples
    ///
    /// ```
    /// use aimx::{Value, Literal};
    ///
    /// let text_number = Value::Literal(Literal::from_text("42".to_string()));
    /// let as_number = text_number.as_number().unwrap();
    /// assert!(as_number.is_number());
    ///
    /// let bool_true = Value::Literal(Literal::from_bool(true));
    /// let as_number = bool_true.as_number().unwrap();
    /// // true converts to 1
    /// assert_eq!(as_number.to_literal().to_number().unwrap(), 1.0);
    /// ```
    pub fn as_number(self) -> Result<Value> {
        // Early return if no conversion is needed
        match &self {
            Value::Empty => return Ok(self),
            Value::Literal(literal) if literal.is_number() => return Ok(self),
            _ => {}
        }
        // Now do the conversion for cases that need it
        Ok(match self {
            Value::Literal(literal) => Value::Literal(literal.as_number()?),
            Value::Array(array) => {
                let number_array: Result<Vec<Box<Value>>, anyhow::Error> = array
                    .into_iter()
                    .map(|box_value| {
                        let value: Value = *box_value; 
                        if value.is_number() {
                            Ok(Box::new(value))
                        } else {
                            let converted_value = value.as_number()?;
                            Ok(Box::new(converted_value))
                        }
                    })
                    .collect();
                Value::Array(number_array?)
            }
            _ => return Err(anyhow!("Cannot convert {} to Number", self.type_as_string())),
        })
    }

    /// Extract a numeric value from this value.
    ///
    /// This is a convenience method for when you specifically need a `f64` number.
    /// It's particularly useful for arithmetic operations and mathematical functions.
    ///
    /// # Returns
    ///
    /// Returns a `Result<f64>` containing the numeric value or an error if:
    /// - The value is empty
    /// - The value is an array with no elements
    /// - The underlying literal cannot be converted to a number
    ///
    /// # Examples
    ///
    /// ```
    /// use aimx::{Value, Literal};
    ///
    /// let number_value = Value::Literal(Literal::from_number(42.5));
    /// let num = number_value.to_number().unwrap();
    /// assert_eq!(num, 42.5);
    ///
    /// let array_value = Value::Array(vec![
    ///     Box::new(Value::Literal(Literal::from_number(10.0))),
    ///     Box::new(Value::Literal(Literal::from_number(20.0))),
    /// ]);
    /// let num = array_value.to_number().unwrap();
    /// // For arrays, gets the last element's number
    /// assert_eq!(num, 20.0);
    /// ```
    pub fn to_number(&self) -> Result<f64> {
        match self {
            Value::Literal(literal) => literal.to_number(),
            Value::Array(array) => {
                if array.len() > 0 {
                    array.last().unwrap().as_ref().to_number()
                } else {
                    Err(anyhow!("Cannot convert empty Array to Number"))
                }
            }
            _ => Err(anyhow!("Cannot convert {} to Number", self.type_as_string())),
        }
    }

    /// Check if this value represents a task.
    ///
    /// Returns `true` if this value is a literal task, `false` otherwise.
    ///
    /// # Examples
    ///
    /// ```
    /// use aimx::{Value, Literal};
    ///
    /// let task_value = Value::Literal(Literal::from_task(Some(true), "Completed task".to_string()));
    /// let text_value = Value::Literal(Literal::from_text("Just text".to_string()));
    ///
    /// assert!(task_value.is_task());
    /// assert!(!text_value.is_task());
    /// ```
    pub fn is_task(&self) -> bool {
        match self {
            Value::Literal(Literal::Task(..)) => true,
            _ => false,
        }
    }

    /// Convert this value to a task representation.
    ///
    /// Attempts to convert the value to a task according to the AIMX grammar's
    /// conversion rules:
    /// - Empty values: Remain empty (no conversion needed)
    /// - Tasks: No conversion needed
    /// - Boolean: Status becomes the boolean value, text becomes "true"/"false"
    /// - Date: No status, text becomes date string
    /// - Number: Status based on sign (positive=true, negative=false, zero=none), text becomes number string
    /// - Text: No status, text remains the same
    ///
    /// # Returns
    ///
    /// Returns a `Result<Value>` containing the converted task value or an error
    /// if conversion is not possible.
    ///
    /// # Examples
    ///
    /// ```
    /// use aimx::{Value, Literal};
    ///
    /// let bool_true = Value::Literal(Literal::from_bool(true));
    /// let as_task = bool_true.as_task().unwrap();
    /// assert!(as_task.is_task());
    ///
    /// let text_value = Value::Literal(Literal::from_text("Pending task".to_string()));
    /// let as_task = text_value.as_task().unwrap();
    /// // Text converts to task with no status
    /// assert_eq!(as_task.to_literal().to_string(), "[ ] Pending task");
    /// ```
    pub fn as_task(self) -> Result<Value> {
        // Early return if no conversion is needed
        match &self {
            Value::Empty => return Ok(self),
            Value::Literal(literal) if literal.is_task() => return Ok(self),
            _ => {}
        }
        // Now do the conversion for cases that need it
        Ok(match self {
            Value::Literal(literal) => Value::Literal(literal.as_task()?),
            Value::Array(array) => {
                let task_array: Result<Vec<Box<Value>>, anyhow::Error> = array
                    .into_iter()
                    .map(|box_value| {
                        let value: Value = *box_value; 
                        if value.is_task() {
                            Ok(Box::new(value))
                        } else {
                            let converted_value = value.as_task()?;
                            Ok(Box::new(converted_value))
                        }
                    })
                    .collect();
                Value::Array(task_array?)
            }
            _ => return Err(anyhow!("Cannot convert {} to Task", self.type_as_string())),
        })
    }

    /// Check if this value represents text.
    ///
    /// Returns `true` if this value is a literal text, `false` otherwise.
    ///
    /// # Examples
    ///
    /// ```
    /// use aimx::{Value, Literal};
    ///
    /// let text_value = Value::Literal(Literal::from_text("Hello".to_string()));
    /// let number_value = Value::Literal(Literal::from_number(42.0));
    ///
    /// assert!(text_value.is_text());
    /// assert!(!number_value.is_text());
    /// ```
    pub fn is_text(&self) -> bool {
        match self {
            Value::Literal(Literal::Text(_)) => true,
            _ => false,
        }
    }

    /// Convert this value to a text representation.
    ///
    /// Converts the value to text according to the AIMX grammar's conversion rules:
    /// - Empty values: Remain empty (no conversion needed)
    /// - Text: No conversion needed
    /// - Boolean: "true" or "false"
    /// - Date: Formatted as ISO 8601 date string (e.g., "2023-01-01T00:00:00.000")
    /// - Number: Formatted as string (e.g., "42", "3.14")
    /// - Task: Text component of the task (status is preserved in the Value but not in the text conversion)
    ///
    /// # Returns
    ///
    /// Returns a `Result<Value>` containing the converted text value or an error
    /// if conversion is not possible.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use aimx::{Value, Literal};
    ///
    /// let number_value = Value::Literal(Literal::from_number(42.0));
    /// let as_text = number_value.as_text().unwrap();
    /// assert!(as_text.is_text());
    /// assert_eq!(as_text.to_literal().to_string(), "42");
    ///
    /// let bool_true = Value::Literal(Literal::from_bool(true));
    /// let as_text = bool_true.as_text().unwrap();
    /// assert_eq!(as_text.to_literal().to_string(), "true");
    /// ```
    pub fn as_text(self) -> Result<Value> {
        // Early return if no conversion is needed
        match &self {
            Value::Empty => return Ok(self),
            Value::Literal(literal) if literal.is_text() => return Ok(self),
            _ => {}
        }
        // Now do the conversion for cases that need it
        Ok(match self {
            Value::Literal(literal) => Value::Literal(literal.as_text()?),
            Value::Array(array) => {
                let text_array: Result<Vec<Box<Value>>, anyhow::Error> = array
                    .into_iter()
                    .map(|box_value| {
                        let value: Value = *box_value; 
                        if value.is_text() {
                            Ok(Box::new(value))
                        } else {
                            let converted_value = value.as_text()?;
                            Ok(Box::new(converted_value))
                        }
                    })
                    .collect();
                Value::Array(text_array?)
            }
            _ => return Err(anyhow!("Cannot convert {} to Text", self.type_as_string())),
        })
    }

    /// Check if this value represents a closure.
    ///
    /// Returns `true` if this value is a closure, `false` otherwise.
    pub fn is_closure(&self) -> bool {
        match self {
            Value::Closure(_) => true,
            _ => false,
        }
    }

    /// Invoke this value as a closure.
    ///
    /// If this value is a closure, invokes it with the given context.
    /// Otherwise, returns an error.
    ///
    /// # Arguments
    ///
    /// * `context` - The evaluation context to use for invocation
    ///
    /// # Returns
    ///
    /// Returns a `Result<Value>` containing the result of closure invocation
    /// or an error if this value is not a closure.
    pub fn invoke(&self, context: &mut dyn ContextLike) -> Result<Value> {
        match self {
            Value::Closure(closure) => closure.invoke(context),
            _ => Err(anyhow!("Expecting Closure, found {}", self.type_as_string()))
        }
    }

    /// Check if this value represents a format.
    ///
    /// Returns `true` if this value is a format, `false` otherwise.
    pub fn is_format(&self) -> bool {
        match self {
            Value::Format(_) => true,
            _ => false,
        }
    }

    /// Check if this value represents an eval.
    ///
    /// Returns `true` if this value is an eval, `false` otherwise.
    pub fn is_eval(&self) -> bool {
        match self {
            Value::Eval(_) => true,
            _ => false,
        }
    }

    /// Check if this value represents a node.
    ///
    /// Returns `true` if this value is a node, `false` otherwise.
    pub fn is_node(&self) -> bool {
        match self {
            Value::Node(_) => true,
            _ => false,
        }
    }

    /// Get a string representation of this value's type. Used to provide type information
    /// in error messages.
    ///
    /// Returns a string indicating the type of this value based on its underlying literal
    /// representation. Possible return values are: "Empty", "Error", "Bool", "Date", "Number",
    /// "Task", "Text", "Closure", "Node".
    ///
    /// # Examples
    ///
    /// ```rust
    /// use aimx::{Value, Literal};
    ///
    /// let number_value = Value::Literal(Literal::from_number(42.0));
    /// assert_eq!(number_value.type_as_string(), "Number");
    ///
    /// let text_value = Value::Literal(Literal::from_text("Hello".to_string()));
    /// assert_eq!(text_value.type_as_string(), "Text");
    ///
    /// let array_value = Value::Array(vec![
    ///     Box::new(Value::Literal(Literal::from_number(1.0))),
    /// ]);
    /// // For arrays, gets the type of the last element
    /// assert_eq!(array_value.type_as_string(), "Number");
    /// ```
    pub fn type_as_string(&self) -> &'static str {
        match self {
            Value::Empty => "Empty",
            Value::Errata(_) => "Error",
            Value::Literal(literal) => literal.type_as_string(),
            Value::Array(array) => {
                if array.len() > 0 {
                    array.last().unwrap().as_ref().type_as_string()
                } else {
                    "Empty"
                }
            }
            Value::Closure(_) => "Closure",
            Value::Assignment(_) => "Assignment",
            Value::Format(_) => "Format",
            Value::Eval(_) => "Eval",
            Value::Node(_) => "Node",
        }
    }

    /// Convert value to string with specified prefix, for pretty printing.
    ///
    /// This method formats the value for display with the specified prefix style.
    /// It's primarily used for generating human-readable output with appropriate
    /// indentation and formatting.
    ///
    /// # Arguments
    ///
    /// * `prefix` - The prefix style to use for formatting (None, Unordered, Ordered)
    ///
    /// # Returns
    ///
    /// Returns a formatted string representation of the value.
    ///
    /// # Examples
    ///
    /// ```
    /// use aimx::{Value, Literal, writer::Prefix};
    ///
    /// let array_value = Value::Array(vec![
    ///     Box::new(Value::Literal(Literal::from_text("first".to_string()))),
    ///     Box::new(Value::Literal(Literal::from_text("second".to_string()))),
    /// ]);
    ///
    /// let formatted = array_value.to_pretty(Prefix::Unordered);
    /// // Would produce formatted output with bullet points
    /// ```
    pub fn to_pretty(&self, prefix: Prefix) -> String {
        let mut writer = Writer::new(PrintMode::None, prefix);
        writer.print_value(&prefix, self);
        writer.finish()
    }

    // Helper function to get type order for consistent sorting
    fn type_order(&self) -> u8 {
        match self {
            Value::Empty => 0,
            Value::Errata(_) => 1,
            Value::Node(_) => 2,
            Value::Eval(_) => 3,
            Value::Format(_) => 4,
            Value::Assignment(_) => 5,
            Value::Closure(_) => 6,
            Value::Literal(_) => 7,
            Value::Array(_) => 8,
        }
    }
}

impl PartialOrd for Value {
    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
        // Define a consistent ordering by type first, then value
        // Type ordering: Empty < Bool < Number < Date < Task < Text
        let self_type_order = self.type_order();
        let other_type_order = other.type_order();
        if self_type_order > other_type_order {
            Some(Ordering::Greater)
        } else if self_type_order < other_type_order {
            Some(Ordering::Less)
        } else {
            match (self, other) {
                // Start by assuming the types match
                (Value::Empty, Value::Empty) => Some(Ordering::Equal),
                (Value::Literal(a), Value::Literal(b)) => a.partial_cmp(b),
                (Value::Array(a), Value::Array(b)) => {
                    // Compare arrays element by element
                    let len_a = a.len();
                    let len_b = b.len();
                    let min_len = std::cmp::min(len_a, len_b);
                    
                    for i in 0..min_len {
                        match a[i].partial_cmp(&b[i]) {
                            Some(Ordering::Equal) => continue,
                            other => return other,
                        }
                    }
                    
                    // If all compared elements are equal, compare by length
                    len_a.partial_cmp(&len_b)
                }
                _ => Some(Ordering::Equal),
            }
        }
    }
}

impl Eq for Value {}

impl Ord for Value {
    fn cmp(&self, other: &Self) -> Ordering {
        self.partial_cmp(other).unwrap()
    }
}

/// Parse a comma-separated array element.
///
/// This helper function parses a single element in a comma-separated list,
/// handling both literal values and nested arrays. It expects to find a comma
/// followed by optional whitespace, then either a literal value or another array.
///
/// This function is used internally by the array parsing logic to handle
/// the elements after the first one in a comma-separated list.
///
/// # Arguments
///
/// * `input` - The input string to parse
///
/// # Returns
///
/// Returns an `IResult` containing the remaining input and the parsed value.
fn parse_comma(input: &str) -> IResult<&str, Value> {
    let (input, _) = multispace0.parse(input)?;
    let (input, _) = char(',').parse(input)?;
    let (input, _) = multispace0.parse(input)?;
    let (input, value) = if input.starts_with('(') {
        parse_value_array(input)
    } else {
        let (remain, literal) = parse_literal(input)?;
        Ok((remain, Value::Literal(literal)))
    }?;
    Ok((input, value))
}

/// Parse a parenthesis-enclosed value array.
///
/// This function parses arrays that are enclosed in parentheses, such as `(1, 2, 3)`.
/// It handles both empty arrays `()` and arrays with values. For singleton literals
/// inside parentheses, it creates a single-element array.
///
/// # Arguments
///
/// * `input` - The input string to parse
///
/// # Returns
///
/// Returns an `IResult` containing the remaining input and the parsed array value.
fn parse_value_array(input: &str) -> IResult<&str, Value> {
  let (input, value) = delimited(
    char('('),
    parse_value,
    char(')'),
  ).parse(input)?;
  let value = match value {
    Value::Empty => Value::Array(Vec::new()),
    Value::Literal(_) => Value::Array(vec![Box::new(value)]),
    _ => value,
  };
  Ok((input, value))
}

/// Parse a value from input text.
///
/// This is the main entry point for parsing values in the AIMX expression language.
/// It can parse three types of values:
/// 1. Empty values (whitespace-only input)
/// 2. Literal values (numbers, booleans, text, dates, tasks)
/// 3. Arrays (parenthesis-enclosed comma-separated lists)
///
/// The parser handles whitespace automatically and can parse nested arrays.
///
/// # Arguments
///
/// * `input` - The input string to parse
///
/// # Returns
///
/// Returns an `IResult` containing the remaining input and the parsed value.
///
/// # Examples
///
/// ```rust
/// use aimx::value::parse_value;
///
/// // Parse a number
/// let result = parse_value("42");
/// assert!(result.is_ok());
///
/// // Parse an array
/// let result = parse_value("(1, 2, 3)");
/// assert!(result.is_ok());
///
/// // Parse nested arrays
/// let result = parse_value("((1, 2), (3, 4))");
/// assert!(result.is_ok());
/// ```
pub fn parse_value(input: &str) -> IResult<&str, Value> {
    let input = input.trim();
    // Value is empty
    if input.is_empty() {
        return Ok((input, Value::Empty));
    }
    // Parenthesis enclosed array
    let (input, first) = if input.starts_with('(') {
        parse_value_array(input)
    } else {
        match parse_literal(input) {
            Ok((remain, literal)) => Ok((remain, Value::Literal(literal))),
            _ => Ok((input, Value::Empty)),
        }
    }?;
    if let Ok((input, value_list)) = many1(parse_comma).parse(input) {
        let mut array = vec![Box::new(first)];
        for conditional in value_list {
            array.push(Box::new(conditional));
        }
        let (input, _) = multispace0(input)?;
        Ok((input, Value::Array(array)))
    } else {
        let (input, _) = multispace0(input)?;
        Ok((input, first))
    }
}

impl ExpressionLike for Value {
    fn evaluate(&self, _context: &mut dyn ContextLike) -> Result<Value> {
        Ok(self.clone())
    }

    /// Write this value to the provided writer using the appropriate formatting.
    ///
    /// This implementation delegates to the writer's `print_value` method,
    /// which handles the formatting based on the writer's mode (string, sanitized, formula).
    ///
    /// # Arguments
    ///
    /// * `writer` - The writer to write to
    fn write(&self, writer: &mut Writer) {
        let prefix = writer.prefix();
        writer.print_value(&prefix, self);
    }
    
    /// Convert this value to a sanitized string representation.
    ///
    /// This method produces a string with special characters escaped
    /// to make it safe for various contexts. Useful for generating
    /// JSON-compatible or safely quoted output.
    ///
    /// # Returns
    ///
    /// A sanitized string representation of this value.
    fn to_sanitized(&self) -> String {
        let mut writer = Writer::sanitizer();
        let prefix = writer.prefix();
        writer.print_value(&prefix, self);
        writer.finish()
    }
    
    /// Convert this value to a formula string representation.
    ///
    /// This method produces a string with proper quoting and escaping
    /// for use in formulas. Useful for generating round-trippable
    /// representations that can be parsed back into values.
    ///
    /// # Returns
    ///
    /// A formula string representation of this value.
    fn to_formula(&self) -> String {
        let mut writer = Writer::formulizer();
        let prefix = writer.prefix();
        writer.print_value(&prefix, self);
        writer.finish()
    }
}

impl fmt::Display for Value {
    /// Format this value for display using the default string representation.
    ///
    /// This implementation uses the stringizer writer mode to produce a
    /// human-readable representation of the value. For arrays, this will
    /// include proper formatting with newlines and indentation where appropriate.
    ///
    /// # Arguments
    ///
    /// * `f` - The formatter to write to
    ///
    /// # Returns
    ///
    /// A `fmt::Result` indicating success or failure of the formatting operation.
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let mut writer = Writer::stringizer();
        let prefix = writer.prefix();
        writer.print_value(&prefix, self);
        write!(f, "{}", writer.finish())
    }
}