aimx/

typedef.rs

//! Type definitions for the AIM expression grammar.
//!
//! This module provides type definitions and parsing for the type system used
//! in the AIM expression language. It includes basic types like Bool, Date,
//! Number, Task, and Text, as well as array variants and special types like
//! Closure, Eval, Format, and Node.
//!
//! The `Typedef` enum represents the complete type system for AIM expressions,
//! supporting type checking, casting operations, and function signature validation.
//! Type definitions are used throughout the expression evaluation system to ensure
//! type safety and enable automatic type promotion.
//!
//! # Supported Types
//!
//! ## Basic Types
//! - `Any` - Any type (wildcard type that matches any value)
//! - `Bool` - Boolean values (`true`/`false`)
//! - `Date` - Date and time values
//! - `Number` - 64-bit floating point numbers
//! - `Task` - Task primitives with status and text
//! - `Text` - String values
//!
//! ## Array Types
//! - `Any[]` - Array of any values (heterogeneous)
//! - `Bool[]` - Arrays of boolean values
//! - `Date[]` - Arrays of date values
//! - `Number[]` - Arrays of number values
//! - `Task[]` - Arrays of task values
//! - `Text[]` - Arrays of text values
//!
//! ## Special Types
//! - `Closure` - Closure expression type (anonymous functions)
//! - `Eval` - Evaluation results (inference output)
//! - `Format` - Formatting instructions (output formatting)
//! - `Node` - Node references (workflow references)
//!
//! # Type Promotion Rules
//!
//! AIMX uses an intuitive type promotion strategy where the left operand's type
//! generally dictates the conversion for the right operand. This allows for
//! expressive, convenient formulas while preserving type safety.
//!
//! # Examples
//!
//! ```text
//! // Type casting examples
//! (Bool)true        // cast to boolean
//! (Number)"123"     // cast to number
//! (Text[])items     // cast to text array
//!
//! // Function signature examples
//! task.done()       // requires Typedef::Task
//! numbers.sum()     // requires Typedef::NumberArray
//! text.upper()      // requires Typedef::Text
//! ```
//!
//! # Usage
//!
//! Type definitions are primarily used for:
//! - Type casting operations in expressions
//! - Function signature validation
//! - Method dispatch based on receiver type
//! - Type checking during expression evaluation
//!
//! See also: [`parse_typedef`], [`parse_literal_type`], [`Typedef`]

use nom::{
    IResult,
    error::Error,
    Err as NomErr,
    branch::alt,
    bytes::complete::tag,
    combinator::opt,
    Parser,
};
use crate::{
    Writer,
    ContextLike,
    ExpressionLike,
    Value,
};
use std::fmt;
use anyhow::{anyhow, Result};

/// Represents type definitions in the AIM expression grammar.
/// 
/// The `Typedef` enum provides a complete type system for the AIM expression
/// language, including basic types, array types, and special-purpose types.
/// These type definitions are used throughout the expression evaluation system
/// for type checking, casting operations, function signature validation, and
/// method dispatch.
/// 
/// # Type Safety and Promotion
/// 
/// AIMX uses a robust type system with automatic type promotion. The system
/// follows a left-operand-first strategy where the left operand's type determines
/// how the right operand is promoted. This provides expressive power while
/// maintaining type safety.
/// 
/// # Variants
/// 
/// ## Basic Types
/// * `Any` - Wildcard type that matches any value
/// * `Bool` - Boolean values (`true`/`false`)
/// * `Date` - Date and time values
/// * `Number` - 64-bit floating point numbers
/// * `Task` - Task primitives with status and text
/// * `Text` - String values
/// 
/// ## Array Types
/// * `Array` - Array of any values (heterogeneous)
/// * `BoolArray` - Arrays of boolean values
/// * `DateArray` - Arrays of date values
/// * `NumberArray` - Arrays of number values
/// * `TaskArray` - Arrays of task values
/// * `TextArray` - Arrays of text values
/// 
/// ## Special Types
/// * `Closure` - Closure expression type (anonymous functions)
/// * `Eval` - Evaluation result type (inference output)
/// * `Format` - Formatting instruction type (output formatting)
/// * `Node` - Node reference type (workflow references)
/// 
/// # Examples
/// 
/// ```rust
/// use aimx::typedef::Typedef;
/// 
/// // Basic type checking
/// assert!(Typedef::Bool.is_bool());
/// assert!(Typedef::NumberArray.is_array());
/// 
/// // Type conversion
/// let text_type = Typedef::Text;
/// assert_eq!(text_type.as_string(), "Text");
/// 
/// // Array type recognition
/// let number_array = Typedef::NumberArray;
/// assert!(number_array.is_number());
/// assert!(number_array.is_array());
/// ```
/// 
/// See also: [`parse_typedef`], [`parse_literal_type`]
#[derive(Debug, Clone, PartialEq)]
pub enum Typedef {
    /// Any type
    Any,
    /// Generic Array
    Array,
    /// Boolean type
    Bool,
    /// Array of boolean values
    BoolArray,
    /// Date and time type
    Date,
    /// Array of date values
    DateArray,
    /// Number (64-bit float) type
    Number,
    /// Array of number values
    NumberArray,
    /// Task primitive type
    Task,
    /// Array of task values
    TaskArray,
    /// Text/string type
    Text,
    /// Array of text values
    TextArray,

    /// Closure expression type
    Closure,
    /// Evaluation result type
    Eval,
    /// Formatting instruction type
    Format,
    /// Node reference type
    Node,
}

impl Typedef {
    /// Check if this type definition represents the Any type.
    /// 
    /// # Returns
    /// 
    /// * `bool` - True if this is the Any type, false otherwise
    pub fn is_any(&self) -> bool {
        match self {
            Typedef::Any | Typedef::Array => true,
            _ => false,
        }
    }

    /// Check if this type definition represents the Any Array type.
    /// 
    /// # Returns
    /// 
    /// * `bool` - True if this is the Any Array type, false otherwise
    pub fn is_any_array(&self) -> bool {
        match self {
            Typedef::Array => true,
            _ => false,
        }
    }
    
    /// Check if this type definition represents a Bool or BoolArray type.
    /// 
    /// # Returns
    /// 
    /// * `bool` - True if this is a Bool or BoolArray type, false otherwise
    pub fn is_bool(&self) -> bool {
        match self {
            Typedef::Bool | Typedef::BoolArray => true,
            _ => false,
        }
    }
    
    /// Check if this type definition represents a Date or DateArray type.
    /// 
    /// # Returns
    /// 
    /// * `bool` - True if this is a Date or DateArray type, false otherwise
    pub fn is_date(&self) -> bool {
        match self {
            Typedef::Date | Typedef::DateArray => true,
            _ => false,
        }
    }
    
    /// Check if this type definition represents a Number or NumberArray type.
    /// 
    /// # Returns
    /// 
    /// * `bool` - True if this is a Number or NumberArray type, false otherwise
    pub fn is_number(&self) -> bool {
        match self {
            Typedef::Number | Typedef::NumberArray => true,
            _ => false,
        }
    }
    
    /// Check if this type definition represents a Task or TaskArray type.
    /// 
    /// # Returns
    /// 
    /// * `bool` - True if this is a Task or TaskArray type, false otherwise
    pub fn is_task(&self) -> bool {
        match self {
            Typedef::Task | Typedef::TaskArray => true,
            _ => false,
        }
    }
    
    /// Check if this type definition represents a Text or TextArray type.
    /// 
    /// # Returns
    /// 
    /// * `bool` - True if this is a Text or TextArray type, false otherwise
    pub fn is_text(&self) -> bool {
        match self {
            Typedef::Text | Typedef::TextArray => true,
            _ => false,
        }
    }
    
    /// Check if this type definition represents a Literal type.
    /// 
    /// Literal types are the basic value types that can be directly represented
    /// in expressions without requiring complex evaluation.
    /// 
    /// # Returns
    /// 
    /// * `bool` - True if this is a Literal type, false otherwise
    pub fn is_literal(&self) -> bool {
        match self {
            Typedef::Bool
            | Typedef::Number
            | Typedef::Date
            | Typedef::Task
            | Typedef::Text => true,
            _ => false,
        }
    }

    /// Convert this type definition to its corresponding literal type.
    /// 
    /// This method strips array qualifiers and returns the base literal type.
    /// For example, `NumberArray` becomes `Number`, `TextArray` becomes `Text`.
    /// Special types remain unchanged.
    /// 
    /// # Returns
    /// 
    /// * `Typedef` - The corresponding literal type
    /// 
    /// # Examples
    /// 
    /// ```rust
    /// use aimx::typedef::Typedef;
    /// 
    /// assert_eq!(Typedef::NumberArray.as_literal(), Typedef::Number);
    /// assert_eq!(Typedef::Text.as_literal(), Typedef::Text);
    /// assert_eq!(Typedef::Closure.as_literal(), Typedef::Closure);
    /// ```
    pub fn as_literal(&self) -> Self {
       match self {
            Typedef::Any | Typedef::Array => Typedef::Any,
            Typedef::Bool | Typedef::BoolArray => Typedef::Bool,
            Typedef::Number | Typedef::NumberArray => Typedef::Number,
            Typedef::Date | Typedef::DateArray => Typedef::Date,
            Typedef::Task | Typedef::TaskArray => Typedef::Task,
            Typedef::Text | Typedef::TextArray => Typedef::Text,
            Typedef::Closure => Typedef::Closure,
            Typedef::Eval => Typedef::Eval,
            Typedef::Format => Typedef::Format,
            Typedef::Node => Typedef::Node,
        }
    }

    /// Check if this type definition represents an array type.
    /// 
    /// # Returns
    /// 
    /// * `bool` - True if this is an array type, false otherwise
    pub fn is_array(&self) -> bool {
        match self {
            Typedef::Array
            | Typedef::BoolArray
            | Typedef::NumberArray
            | Typedef::DateArray
            | Typedef::TaskArray
            | Typedef::TextArray => true,
            _ => false,
        }
    }

    /// Convert this type definition to its corresponding array type.
    /// 
    /// This method adds array qualifiers to literal types. For example,
    /// `Number` becomes `NumberArray`, `Text` becomes `TextArray`.
    /// Special types remain unchanged.
    /// 
    /// # Returns
    /// 
    /// * `Typedef` - The corresponding array type
    /// 
    /// # Examples
    /// 
    /// ```rust
    /// use aimx::typedef::Typedef;
    /// 
    /// assert_eq!(Typedef::Number.as_array(), Typedef::NumberArray);
    /// assert_eq!(Typedef::TextArray.as_array(), Typedef::TextArray);
    /// assert_eq!(Typedef::Closure.as_array(), Typedef::Closure);
    /// ```
    pub fn as_array(&self) -> Self {
       match self {
            Typedef::Any | Typedef::Array => Typedef::Array,
            Typedef::Bool | Typedef::BoolArray => Typedef::BoolArray,
            Typedef::Number | Typedef::NumberArray => Typedef::NumberArray,
            Typedef::Date | Typedef::DateArray => Typedef::DateArray,
            Typedef::Task | Typedef::TaskArray => Typedef::TaskArray,
            Typedef::Text | Typedef::TextArray => Typedef::TextArray,
            Typedef::Closure => Typedef::Closure,
            Typedef::Eval => Typedef::Eval,
            Typedef::Format => Typedef::Format,
            Typedef::Node => Typedef::Node,
        }
    }

    /// Check if this type definition represents the Format type.
    /// 
    /// # Returns
    /// 
    /// * `bool` - True if this is the Format type, false otherwise
    pub fn is_format(&self) -> bool {
        match self {
            Typedef::Format => true,
            _ => false,
        }
    }
    
    /// Check if this type definition represents the Eval type.
    /// 
    /// # Returns
    /// 
    /// * `bool` - True if this is the Eval type, false otherwise
    pub fn is_eval(&self) -> bool {
        match self {
            Typedef::Eval => true,
            _ => false,
        }
    }
    
    /// Check if this type definition represents a Node type.
    /// 
    /// # Returns
    /// 
    /// * `bool` - True if this is a Node type, false otherwise
    pub fn is_node(&self) -> bool {
        match self {
            Typedef::Node => true,
            _ => false,
        }
    }
    
    /// Check if this type definition represents the Closure type.
    /// 
    /// # Returns
    /// 
    /// * `bool` - True if this is the Closure type, false otherwise
    pub fn is_closure(&self) -> bool {
        match self {
            Typedef::Closure => true,
            _ => false,
        }
    }
    
    /// Check if this type definition represents an special type.
    /// 
    /// Special types are those that don't represent literal values but rather
    /// serve specific purposes in the expression system.
    /// 
    /// # Returns
    /// 
    /// * `bool` - True if this is a Format, Eval, Node or Closure type, false otherwise
    pub fn is_special(&self) -> bool {
        match self {
            Typedef::Closure
            | Typedef::Format
            | Typedef::Eval
            | Typedef::Node => true,
            _ => false,
        }
    }

    /// Get the string representation of this type definition.
    /// 
    /// Returns the canonical string representation used in AIM expressions.
    /// This is the same format that would appear in type casting operations.
    /// 
    /// # Returns
    /// 
    /// * `&'static str` - The string representation of the type
    /// 
    /// # Examples
    /// 
    /// ```rust
    /// use aimx::typedef::Typedef;
    /// 
    /// assert_eq!(Typedef::Bool.as_string(), "Bool");
    /// assert_eq!(Typedef::NumberArray.as_string(), "Number[]");
    /// assert_eq!(Typedef::Closure.as_string(), "Closure");
    /// ```
    pub fn as_string(&self) -> &'static str {
        match self {
            Typedef::Any => "Any",
            Typedef::Array => "Any[]",
            Typedef::Bool => "Bool",
            Typedef::BoolArray => "Bool[]",
            Typedef::Date => "Date",
            Typedef::DateArray => "Date[]",
            Typedef::Number => "Number",
            Typedef::NumberArray => "Number[]",
            Typedef::Task => "Task",
            Typedef::TaskArray => "Task[]",
            Typedef::Text => "Text",
            Typedef::TextArray => "Text[]",

            Typedef::Closure => "Closure",
            Typedef::Eval => "Eval",
            Typedef::Format => "Format",
            Typedef::Node => "Node",
        }
    }
}

/// Parse a type definition from a string according to the AIM expression grammar syntax.
/// 
/// This function parses type names and array markers to create the appropriate
/// Typedef variant. It supports both basic types and array types.
/// 
/// # Supported Type Names
/// - `Any` - Wildcard type that matches any value
/// - `Bool` - Boolean type
/// - `Date` - Date type
/// - `Number` - Number type
/// - `Task` - Task type
/// - `Text` - Text type
/// 
/// # Special Types
/// - `Eval` - Evaluation type
/// - `Format` - Format type
/// - `Node` - Node type
/// 
/// # Arguments
/// 
/// * `input` - A string slice containing the type definition to parse
/// 
/// # Returns
/// 
/// * `IResult<&str, Typedef>` - A nom result with remaining input and parsed type definition
/// 
/// # Examples
/// 
/// ```rust
/// use aimx::typedef::{parse_typedef, Typedef};
/// 
/// assert_eq!(parse_typedef("Bool"), Ok(("", Typedef::Bool)));
/// assert_eq!(parse_typedef("Number[]"), Ok(("", Typedef::NumberArray)));
/// assert_eq!(parse_typedef("Text[]"), Ok(("", Typedef::TextArray)));
/// ```
pub fn parse_typedef(input: &str) -> IResult<&str, Typedef> {

    // Parse type marker
    let (input, type_marker) = alt((
        tag("Any"),
        tag("Bool"),
        tag("Date"),
        tag("Number"),
        tag("Task"),
        tag("Text"),

        tag("Closure"),
        tag("Eval"),
        tag("Format"),
        tag("Node"),
    )).parse(input)?;

    // Parse array marker if present
    let (input, array_marker) = opt(tag("[]")).parse(input)?;
    let is_array = array_marker.is_some();

    let typedef = match (type_marker, is_array) {
        ("Any", false) => Typedef::Any,
        ("Any", true) => Typedef::Array,
        ("Bool", false) => Typedef::Bool,
        ("Bool", true) => Typedef::BoolArray,
        ("Date", false) => Typedef::Date,
        ("Date", true) => Typedef::DateArray,
        ("Number", false) => Typedef::Number,
        ("Number", true) => Typedef::NumberArray,
        ("Task", false) => Typedef::Task,
        ("Task", true) => Typedef::TaskArray,
        ("Text", false) => Typedef::Text,
        ("Text", true) => Typedef::TextArray,

        ("Closure", false) => Typedef::Closure,
        ("Eval", false) => Typedef::Eval,
        ("Format", false) => Typedef::Format,
        ("Node", false) => Typedef::Node,
        _ => return Err(NomErr::Failure(Error::new(input, nom::error::ErrorKind::Fail))),
    };

    Ok((input, typedef))
}

/// Parse a literal type definition from a string.
/// 
/// This function is similar to [`parse_typedef`] but only accepts literal types
/// (Bool, Date, Number, Task, Text) and does not support array types or special types.
/// It's used in contexts where only basic value types are expected.
/// 
/// # Arguments
/// 
/// * `input` - A string slice containing the literal type definition to parse
/// 
/// # Returns
/// 
/// * `IResult<&str, Typedef>` - A nom result with remaining input and parsed literal type
/// 
/// # Examples
/// 
/// ```rust
/// use aimx::typedef::{parse_literal_type, Typedef};
/// 
/// assert_eq!(parse_literal_type("Bool"), Ok(("", Typedef::Bool)));
/// assert_eq!(parse_literal_type("Number"), Ok(("", Typedef::Number)));
/// assert_eq!(parse_literal_type("Text"), Ok(("", Typedef::Text)));
/// ```
pub fn parse_literal_type(input: &str) -> IResult<&str, Typedef> {
    // Parse type marker
    let (input, type_marker) = alt((
        tag("Bool"),
        tag("Date"),
        tag("Number"),
        tag("Task"),
        tag("Text"),
    )).parse(input)?;
    let typedef = match type_marker {
        "Bool" => Typedef::Bool,
        "Date" => Typedef::Date,
        "Number" => Typedef::Number,
        "Task" => Typedef::Task,
        "Text" => Typedef::Text,
        _ => unreachable!(),
    };
    Ok((input, typedef))
}

impl ExpressionLike for Typedef {
    fn evaluate(&self, _context: &mut dyn ContextLike) -> Result<Value> {
        Err(anyhow!("Typedef cannot be evaluated"))
    }
    
    fn write(&self, writer: &mut Writer) {
        writer.write_str(self.as_string());
    }
    fn to_sanitized(&self) -> String {
        let mut writer = Writer::sanitizer();
        writer.write_str(self.as_string());
        writer.finish()
    }
    fn to_formula(&self) -> String {
        let mut writer = Writer::formulizer();
        writer.write_str(self.as_string());
        writer.finish()
    }
}

impl fmt::Display for Typedef {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let mut writer = Writer::stringizer();
        writer.write_str(self.as_string());
        write!(f, "{}", writer.finish())
    }
}