aimx/expressions/

postfix.rs

//! Postfix expression parsing and evaluation.
//!
//! Supports AIMX postfix operators applied after primary expressions with
//! left-to-right associativity: function calls `()`, indexing `[]`, method
//! access `.`, inference calls on references, the empty placeholder `_`, and
//! criticalization `!!`.
//!
//! Key entry points:
//! - [`parse_postfix`] parses a postfix expression into [`Postfix`].
//! - [`Postfix`] implements [`ExpressionLike`] for evaluation.
use crate::{
    aim::{ContextLike, WriterLike, Writer},
    expressions::{
        Expression, ExpressionLike, Primary, Reference, parse_argument_list, parse_expression,
        parse_arc_identifier, parse_primary,
    },
    literals::Literal,
    values::{CriticalError, Value},
};
use anyhow::{Result, anyhow};
use nom::{
    Err as NomErr, IResult, Parser,
    branch::alt,
    bytes::complete::tag,
    character::complete::{char, multispace0},
    combinator::{map, opt},
    error::Error,
    multi::many0,
    sequence::delimited,
};
use std::{
    fmt, sync::Arc
};

/// Postfix expression AST for AIMX.
///
/// Captures postfix operations applied after primary expressions, including
/// function calls, indexing, method calls, inference calls, criticalization,
/// and flattened primaries for shallow trees.
///
/// Used by [`parse_postfix`] and [`ExpressionLike`] evaluation.
#[derive(Debug, Clone, PartialEq)]
pub enum Postfix {
    /// The empty placeholder `_`
    Empty,
    /// Function call with function name and argument expression
    Function(Arc<str>, Box<Expression>),
    /// Array indexing operation with base and index expressions
    Index(Box<Postfix>, Box<Expression>),
    /// Method call on an object with method name and arguments
    Method(Box<Postfix>, Arc<str>, Box<Expression>),
    /// Inference call on a reference and arguments
    Inference(Arc<Reference>, Box<Expression>),
    /// Criticalization on a postfix expression
    Critical(Box<Postfix>),
    /// Primary flattened AST optimization
    Primary(Box<Primary>),
}

impl Postfix {
    /// Returns `true` if this is [`Postfix::Empty`].
    pub fn is_empty(&self) -> bool {
        match self {
            Postfix::Empty => true,
            _ => false,
        }
    }

    pub fn print(&self, writer: &mut Writer) {
        match self {
            // Check for Empty '_'
            Postfix::Empty => {
                writer.write_char('_');
            }
            Postfix::Function(identifier, expression) => {
                writer.write_str(&identifier);
                writer.write_char('(');
                expression.print(writer);
                writer.write_char(')');
            }
            Postfix::Index(postfix, expression) => {
                postfix.print(writer);
                writer.write_char('[');
                expression.print(writer);
                writer.write_char(']');
            }
            Postfix::Method(postfix, identifier, expression) => {
                postfix.print(writer);
                writer.write_char('.');
                writer.write_str(&identifier);
                writer.write_char('(');
                expression.print(writer);
                writer.write_char(')');
            }
            Postfix::Inference(reference, expression) => {
                reference.print(writer);
                writer.write_char('(');
                expression.print(writer);
                writer.write_char(')');
            }
            Postfix::Critical(postfix) => {
                postfix.print(writer);
                writer.write_str("!!");
            }
            Postfix::Primary(primary) => primary.print(writer),
        }
    }
}

/// Internal representation of postfix operations during parsing.
enum PostfixOp {
    /// Array indexing operation
    Index(Expression),
    /// Method call with method name and arguments
    Method(Arc<str>, Expression),
}

/// Parse `.` accessor with surrounding whitespace.
pub fn parse_accessor(input: &str) -> IResult<&str, &str> {
    delimited(multispace0, tag("."), multispace0).parse(input)
}

/// Parse `[expr]` index suffix into [`PostfixOp::Index`].
fn index_postfix(input: &str) -> IResult<&str, PostfixOp> {
    let (input, expression) = delimited(char('['), parse_expression, char(']')).parse(input)?;
    Ok((input, PostfixOp::Index(expression)))
}

/// Parse `(`argument-list`)` into an [`Expression`] or [`Expression::Empty`].
fn parse_argument_postfix(input: &str) -> IResult<&str, Expression> {
    delimited(
        char('('),
        alt((
            map(parse_argument_list, |expr| expr),
            map(multispace0, |_| Expression::Empty),
        )),
        char(')'),
    )
    .parse(input)
}

/// Parse identifier `(`args`)` or `_` into [`Postfix::Function`] or [`Postfix::Empty`].
fn parse_function(input: &str) -> IResult<&str, Postfix> {
    let (input, name) = parse_arc_identifier(input)?;
    let (input, _) = multispace0(input)?;
    if &*name == "_" {
        return Ok((input, Postfix::Empty));
    }
    let (input, args) = parse_argument_postfix(input)?;
    let function = Postfix::Function(name, Box::new(args));
    Ok((input, function))
}

/// Parse a method call with dot notation.
///
/// This function parses method calls using dot notation, handling the
/// accessor, method name, and argument list.
///
/// # Arguments
///
/// * `input` - A string slice containing the method call to parse
///
/// # Returns
///
/// * `IResult<&str, PostfixOp>` - A nom result with remaining input and parsed method operation
fn parse_method(input: &str) -> IResult<&str, PostfixOp> {
    map(
        (
            parse_accessor,
            parse_arc_identifier,
            multispace0,
            parse_argument_postfix,
        ),
        |(_, name, _, args)| PostfixOp::Method(name, args),
    ).parse(input)
}

fn parse_critical(input: &str, postfix: Postfix) -> IResult<&str, Postfix> {
    let (input, _) = multispace0(input)?;
    let (input, opt_critical) = opt(tag("!!")).parse(input)?;
    let result = if opt_critical.is_some() {
        Postfix::Critical(Box::new(postfix))
    } else {
        postfix
    };
    Ok((input, result))
}

/// Parse chained postfix forms into [`Postfix`].
pub fn parse_postfix(input: &str) -> IResult<&str, Postfix> {
    let (input, first) = if let Ok((input, function)) = parse_function(input) {
        (input, function)
    } else {
        let (input, primary) = parse_primary(input)?;
        if input.starts_with('(') {
            let (input, args) = parse_argument_postfix(input)?;
            match primary {
                Primary::Reference(reference) => {
                    let postfix = Postfix::Inference(reference, Box::new(args));
                    return parse_critical(input, postfix);
                }
                _ => {
                    return Err(NomErr::Failure(Error::new(
                        input,
                        nom::error::ErrorKind::Fail,
                    )));
                }
            }
        }
        (input, Postfix::Primary(Box::new(primary)))
    };

    let (input, rest) = many0(delimited(
        multispace0,
        alt((index_postfix, parse_method)),
        multispace0,
    ))
    .parse(input)?;

    // Build the result by folding from left to right
    let result = rest.into_iter().fold(first, |acc, op| match op {
        PostfixOp::Index(expression) => Postfix::Index(Box::new(acc), Box::new(expression)),
        PostfixOp::Method(name, args) => Postfix::Method(Box::new(acc), name, Box::new(args)),
    });
    return parse_critical(input, result);
}

impl ExpressionLike for Postfix {
    /// Evaluate postfix expression in `context`.
    ///
    /// Function/method/inference calls are delegated via [`ContextLike`].
    /// Indexing supports arrays and collections; `Critical` turns [`Value::Errata`]
    /// into a [`CriticalError`].
    fn evaluate(&self, context: &mut dyn ContextLike) -> Result<Arc<Value>> {
        match self {
            Postfix::Empty => Ok(Value::empty()),
            Postfix::Function(name, expression) => {
                // This is a function call like sum(1, 2, 3)
                let arg = expression.evaluate(context)?;
                if arg.is_error() {
                    return Ok(arg);
                }
                context.function_call(name.clone(), arg)
            }
            Postfix::Index(primary, expression) => {
                let primary_val = primary.evaluate(context)?;
                if primary_val.is_error() {
                    return Ok(primary_val);
                }
                let index_val = expression.evaluate(context)?;
                if index_val.is_error() {
                    return Ok(index_val);
                }
                let found = index_val.type_as_string();
                // Handle array or collection indexing
                match (&*primary_val, &*index_val) {
                    // Array indexing by numeric index
                    (Value::Array(array), Value::Literal(Literal::Number(index))) => {
                        let index = *index as usize;
                        if index < array.len() {
                            Ok(array[index].clone())
                        } else {
                            Err(anyhow!(
                                "Index out of bounds: {} >= {}~{}",
                                index,
                                array.len(),
                                self.to_formula()
                            ))
                        }
                    }
                    (Value::Array(_), _) => Err(anyhow!(
                        "Array index must be a number ~{}",
                        self.to_formula()
                    )),

                    // Collection lookup by string key with lazy evaluation
                    (Value::Collection(pool), Value::Literal(Literal::Text(text))) => {
                        if let Some(expr) = pool.get(text.as_ref()) {
                            expr.evaluate(context)
                        } else {
                            Ok(Value::empty())
                        }
                    }

                    // Allow coercion of index to text when indexing a collection
                    (Value::Collection(pool), _) => {
                        let as_text = index_val.as_text()?;
                        match &*as_text {
                            Value::Literal(Literal::Text(text)) => {
                                if let Some(expr) = pool.get(text) {
                                    expr.evaluate(context)
                                } else {
                                    Ok(Value::empty())
                                }
                            }
                            _ => Ok(Value::empty()),
                        }
                    }

                    _ => Err(anyhow!(
                        "Expected Array or Collection for index, found {}~{}",
                        found,
                        self.to_formula()
                    )),
                }
            }
            Postfix::Method(primary, name, expression) => {
                // This is a method call like array.sum()
                let value = primary.evaluate(context)?;
                if value.is_error() {
                    return Ok(value);
                }
                let arg = expression.evaluate(context)?;
                if arg.is_error() {
                    return Ok(arg);
                }
                context.method_call(name.clone(), value, arg)
            }
            Postfix::Inference(reference, expression) => {
                // This is an inference call like std.extract(document, prompt)
                let arg = expression.evaluate(context)?;
                context.inference_call(reference.clone(), arg)
            }
            Postfix::Critical(postfix) => match postfix.evaluate(context) {
                Ok(value) => {
                    if let Value::Errata(errata) = &*value {
                        Err(CriticalError::new(errata.reason()).into())
                    } else {
                        Ok(value)
                    }
                }
                Err(e) => Err(CriticalError::new(Arc::from(e.to_string())).into()),
            },
            Postfix::Primary(primary) => primary.evaluate(context),
        }
    }

    /// Return the formula-string representation (round-trippable by the parser).
    fn to_formula(&self) -> String {
        let mut writer = Writer::formulizer();
        self.print(&mut writer);
        writer.finish()
    }
}

impl WriterLike for Postfix {
    fn write(&self, writer: &mut Writer) {
        self.print(writer);
    }
}

impl fmt::Display for Postfix {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.to_stringized())
    }
}