aimx/expressions/

procedure.rs

//! # Procedure expression parsing and evaluation.
//!
//! This module provides parsing and evaluation support for procedure expressions in the AIMX language.
//! Procedures represent sequences of conditional expressions separated by semicolons (`;`)
//! and typically form the body of closure expressions.
//!
//! ## Syntax
//!
//! Procedures support two forms:
//! - Single expression: `expression`
//! - Multiple expressions: `expression; expression; ...`
//!
//! When multiple expressions are present, they are evaluated sequentially and the result
//! of the last expression is returned as the procedure's result.
//!
//! ## Examples
//!
//! ```text
//! // Simple procedure - single expression
//! x + 1
//!
//! // Multi-expression procedure - evaluates each expression but returns the last one
//! x * 2; x + 3; x - 1
//!
//! // Used in closures with the map function
//! (5).map(x => x * 2; x + 1)  // Returns 11 (5*2=10, then 10+1=11)
//! ```

use nom::{
    IResult,
    Parser,
    character::complete::{char, multispace0},
    multi::many1,
};
use crate::{
    ContextLike,
    ExpressionLike,
    expressions::{parse_conditional, Conditional},
    Primary,
    Value,
    Writer
};
use std::fmt;
use anyhow::Result;

/// Represents a procedure (sequence of expressions) in the AIMX language.
///
/// Procedures are sequences of conditional expressions that can be evaluated sequentially.
/// They are typically used as the body of closure expressions.
///
/// # Variants
///
/// - `Array(Vec<Box<Conditional>>)`: A sequence of conditional expressions separated by semicolons
/// - `Primary(Box<Primary>)`: An optimized representation when the procedure is a simple primary expression
///
/// # Evaluation Behavior
///
/// When a procedure contains multiple expressions, they are evaluated in order and the result
/// of the last expression is returned. This allows for sequencing operations while maintaining 
/// a functional programming style.
///
/// # Examples
///
/// ```text
/// // Parses to Procedure::Primary(expression)
/// x + 1
///
/// // Parses to Procedure::Array([expression1, expression2, ...])
/// x * 2; x + 3; x - 1
/// ```
#[derive(Debug, Clone, PartialEq)]
pub enum Procedure {
    Array(Vec<Box<Conditional>>),
    /// Primary flattened AST optimization - used when the procedure is a simple primary expression
    Primary(Box<Primary>),
}

/// Helper function to parse conditional expressions in a procedure array.
fn conditional_array(input: &str) -> IResult<&str, Conditional> {
    let (input, _) = multispace0.parse(input)?;
    let (input, _) = char(';').parse(input)?;
    let (input, _) = multispace0.parse(input)?;
    let (input, conditional) = parse_conditional(input)?;
    Ok((input, conditional))
}

/// Parses a procedure expression from the input string.
///
/// This is the main entry point for parsing procedures. It attempts to parse
/// a sequence of conditional expressions separated by semicolons, falling back
/// to a single primary expression if no semicolons are found.
///
/// # Arguments
///
/// * `input` - The input string to parse
///
/// # Returns
///
/// Returns `IResult<&str, Procedure>` containing the remaining unparsed input
/// and the parsed procedure.
///
/// # Examples
///
/// ```rust
/// # use aimx::expressions::procedure::parse_procedure;
/// let result = parse_procedure("x + 1");
/// assert!(result.is_ok()); // Returns Procedure::Primary
/// 
/// let result = parse_procedure("x * 2; x + 3; x - 1");
/// assert!(result.is_ok()); // Returns Procedure::Array with 3 expressions
/// ```
pub fn parse_procedure(input: &str) -> IResult<&str, Procedure> {
    let (input, conditional) = parse_conditional(input)?;
    if let Ok((input, conditional_list)) = many1(conditional_array).parse(input) {
        let mut array = vec![Box::new(conditional)];
        for conditional in conditional_list {
            array.push(Box::new(conditional));
        }
        let (input, _) = multispace0(input)?;
        Ok((input, Procedure::Array(array)))
    } else {
        let procedure = match conditional {
            Conditional::Primary(primary) => Procedure::Primary(primary),
            _ => Procedure::Primary(Box::new(Primary::Conditional(conditional))),
        };
        let (input, _) = multispace0(input)?;
        Ok((input, procedure))
    }
}

impl ExpressionLike for Procedure {
    /// Evaluates the procedure expression.
    ///
    /// For procedure arrays, this evaluates each conditional expression in sequence
    /// and returns the result of the last expression. For primary procedures,
    /// this evaluates the single expression directly.
    ///
    /// # Arguments
    ///
    /// * `context` - The evaluation context
    ///
    /// # Returns
    ///
    /// Returns `Result<Value>` containing the result of evaluating the procedure.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use aimx::{Context, ExpressionLike};
    /// # use aimx::expressions::{conditional::Conditional, procedure::Procedure, primary::Primary};
    /// # use anyhow::Result;
    /// # fn example() -> Result<()> {
    /// let mut context = Context::new();
    /// let procedure = Procedure::Primary(Box::new(Primary::Literal(aimx::Literal::Number(42.0))));
    /// let result = procedure.evaluate(&mut context)?;
    /// // result should be Value::Literal(Literal::Number(42.0))
    /// # Ok(())
    /// # }
    /// ```
    fn evaluate(&self, context: &mut dyn ContextLike) -> Result<Value> {
        match self {
            Procedure::Array(array) => {
                let mut last = Value::Empty;
                for conditional in array {
                    last = conditional.evaluate(context)?;
                }
                Ok(last)
            },
            Procedure::Primary(primary) => primary.evaluate(context),
        }
    }

    /// Writes the procedure expression to a writer.
    ///
    /// This method formats the procedure according to its variant and writes it
    /// to the provided writer. The output matches the AIMX syntax for procedures.
    ///
    /// # Arguments
    ///
    /// * `writer` - The writer to write the formatted procedure to
    fn write(&self, writer: &mut Writer) {
        match self {
            Procedure::Array(conditionals) => {
                if let Some((first, rest)) = conditionals.split_first() {
                    first.write(writer);
                    for conditional in rest {
                        writer.write_str("; ");
                        conditional.write(writer);
                    }
                }
            },
            Procedure::Primary(primary) => primary.write(writer),
        }
    }
    
    /// Returns a sanitized string representation of the procedure.
    ///
    /// Sanitized output is suitable for display to users and may include
    /// formatting that makes the expression easier to read.
    ///
    /// # Returns
    ///
    /// Returns a `String` containing the sanitized procedure representation.
    fn to_sanitized(&self) -> String {
        let mut writer = Writer::sanitizer();
        self.write(&mut writer);
        writer.finish()
    }
    
    /// Returns a formula string representation of the procedure.
    ///
    /// Formula output is suitable for use as input to the parser and matches
    /// the exact AIMX syntax.
    ///
    /// # Returns
    ///
    /// Returns a `String` containing the formula representation.
    fn to_formula(&self) -> String {
        let mut writer = Writer::formulizer();
        self.write(&mut writer);
        writer.finish()
    }
}

impl fmt::Display for Procedure {
    /// Formats the procedure for display.
    ///
    /// This implementation uses the `Writable` trait to format the procedure
    /// as a string suitable for user display.
    ///
    /// # Arguments
    ///
    /// * `f` - The formatter to write to
    ///
    /// # Returns
    ///
    /// Returns `fmt::Result` indicating success or failure.
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let mut writer = Writer::stringizer();
        self.write(&mut writer);
        write!(f, "{}", writer.finish())
    }
}