aimx/aim/

rule.rs

//! AIM rule representation and parsing.
//!
//! A `Rule` models a single AIM entry: identifier, typedef, expression, and value.
//! Identifiers classify rules:
//! - UPPERCASE → modifier
//! - lowercase → assignment
//! - other/mixed → general evaluation.

use crate::{
    aim::{ContextLike, Typedef, Writer, WriterLike, parse_typedef},
    expressions::{
        Expression, ExpressionLike, parse_arc_identifier, parse_branch, parse_closure, parse_expression, parse_retry, statically_evaluate
    },
    values::{Errata, Instance, Node, Value, parse_eval, parse_format, parse_instance, parse_node, parse_value},
};
use anyhow::{Result, anyhow};
use bitflags::bitflags;
use nom::{
    Finish, IResult, Parser, 
    character::complete::{char, multispace0}, 
    sequence::{delimited},
    error::{Error, ErrorKind}
};
use std::{
    fmt,
    sync::Arc,
};

// ----- FLAGS -----

bitflags! {
    /// Internal rule state flags derived from identifier and evaluation.
    #[derive(Debug, Clone, PartialEq)]
    struct Flags: usize {
        /// Rule identifier is all uppercase (modifier rule)
        const IS_MODIFIER   = 0b1;
        /// Rule identifier is all lowercase (assignment rule)
        const IS_ASSIGNMENT = 0b10;
        /// Expression has been statically evaluated to constant value
        const IS_STATIC     = 0b100;
    }
}

/// Check if a string contains only uppercase characters.
pub fn is_uppercase(s: &str) -> bool {
    s.chars().all(|c| !c.is_alphabetic() || c.is_uppercase())
}

/// Check if a string contains only lowercase characters.
pub fn is_lowercase(s: &str) -> bool {
    s.chars().all(|c| !c.is_alphabetic() || c.is_lowercase())
}

/// Test if an identifier should be considered a modifier rule.
pub fn test_for_modifier(identifier: &str) -> bool {
    if is_uppercase(identifier) {
        true
    } else {
        false
    }
}

/// Test if an identifier should be considered an assignment rule.
pub fn test_for_assignment(identifier: &str) -> bool {
    if is_lowercase(identifier) {
        true
    } else {
        false
    }
}

/// Initialize rule flags based on an identifier.
fn init_flags(identifier: &str) -> Flags {
    let mut flags = Flags::empty();
    if test_for_modifier(&identifier) {
        flags.insert(Flags::IS_MODIFIER);
    }
    if test_for_assignment(&identifier) {
        flags.insert(Flags::IS_ASSIGNMENT);
    }
    flags
}

// ----- RULE -----

/// Single AIM rule: identifier, typedef, expression, and value.
///
/// Constructors perform identifier-based classification and optional
/// static folding of constant expressions into `value`.
#[derive(Debug, Clone, PartialEq)]
pub struct Rule {
    /// Rule identifier
    identifier: Arc<str>,
    /// Rule type definition
    typedef: Typedef,
    /// Rule expression
    expression: Expression,
    /// Rule value
    value: Arc<Value>,
    /// Internal flags
    flags: Flags,
}

impl Rule {
    /// Create a new Rule with the given components
    ///
    /// # Parameters
    /// - `identifier`: The rule's unique identifier
    /// - `typedef`: The type definition for the rule
    /// - `expression`: The expression that computes the rule's value
    /// - `value`: The initial value of the rule
    ///
    /// # Returns
    /// A new Rule instance with appropriate flags set based on the identifier
    ///
    /// # Notes
    /// - Automatically performs static evaluation of expressions when possible
    /// - Sets flags based on identifier format (modifier/assignment)
    pub fn new(identifier: Arc<str>, typedef: Typedef, expression: Expression, value: Arc<Value>) -> Self {
        let mut flags = init_flags(&identifier);
        if expression.is_empty() || expression.is_branch() || expression.is_retry() {
            Self {
                identifier,
                typedef,
                expression,
                value,
                flags,
            }
        } else {
            let (static_exp, static_val) = match statically_evaluate(&expression) {
                Ok(value) => {
                    flags.insert(Flags::IS_STATIC);
                    (Expression::Empty, value)
                }
                _ => (expression, Value::empty()),
            };
            Self {
                identifier,
                typedef,
                expression: static_exp,
                value: static_val,
                flags,
            }
        }
    }

    pub fn convert(identifier: Arc<str>, typedef: Arc<str>, formula: Arc<str>, value: Arc<str>) -> Self {
        Self::new(
            identifier,
            Typedef::convert(&typedef),
            Expression::convert(&formula),
            Value::convert(value)
        )
    }

    /// Create a new Rule by parsing operands from a string
    ///
    /// This constructor parses the expression/value portion of a rule definition
    /// based on the rule's type definition and assignment status.
    ///
    /// # Parameters
    /// - `input`: The string containing the rule's operands
    /// - `identifier`: The rule's identifier
    /// - `typedef`: The rule's type definition
    /// - `is_assignment`: Whether this is an assignment rule
    ///
    /// # Returns
    /// A new Rule instance with parsed expression and value
    ///
    /// # Errors
    /// Returns error expressions for incomplete or malformed input
    pub fn parse(&self, input: &str) -> Self {
        let identifier = self.identifier.clone();
        let typedef = self.typedef.clone();
        match parse_rule_operands(input, &self.typedef) {
            Ok((_, (expression, value))) => Self::new(identifier, typedef, expression, value),
            Err(nom::Err::Incomplete(_)) => {
                let expression = Errata::new_expression(
                    Arc::from("Incomplete Expression"),
                    Arc::from(input),
                );
                Self::new(identifier, typedef, expression, Value::empty())
            }
            Err(nom::Err::Error(e)) | Err(nom::Err::Failure(e)) => {
                let expression = Errata::new_expression_location(
                    Arc::from(format!("Syntax Error ({})", e)),
                    Arc::from(input),
                    Arc::from(e.input),
                );
                Self::new(identifier, typedef, expression, Value::empty())
            }
        }
    }

    /// Check if the rule is completely empty (no expression and no value)
    pub fn is_empty(&self) -> bool {
        if self.expression.is_empty() && self.value.is_empty() {
            true
        } else {
            false
        }
    }

    /// Check if the rule contains any errors
    pub fn is_error(&self) -> bool {
        self.value.is_error() | self.expression.is_error()
    }

    /// Check if the rule has a non-empty expression
    pub fn has_expression(&self) -> bool {
        match &self.expression {
            Expression::Empty | Expression::Errata { .. } => false,
            _ => true,
        }
    }

    /// Get the rule's identifier
    pub fn identifier(&self) -> Arc<str> {
        self.identifier.clone()
    }

    /// Get the uppercase form of the identifier.
    ///
    /// Non-alphabetic characters (such as `_` or digits) are preserved; only
    /// alphabetic characters are converted to uppercase.
    pub fn ucid(&self) -> Arc<str> {
        Arc::from(self.identifier.to_uppercase())
    }

    /// Get the lowercase form of the identifier.
    ///
    /// Non-alphabetic characters (such as `_` or digits) are preserved; only
    /// alphabetic characters are converted to lowercase.
    pub fn lcid(&self) -> Arc<str> {
        Arc::from(self.identifier.to_lowercase())
    }

    /// Set a new identifier for the rule
    ///
    /// Updates the identifier and automatically adjusts flags based on the new identifier format
    pub fn set_identifier(&mut self, identifier: Arc<str>) -> bool {
        // Updating the identifier potentially changes a lot of flags
        if self.identifier != identifier {
            // Update flags
            if test_for_modifier(&identifier) {
                self.flags.insert(Flags::IS_MODIFIER);
            } else {
                self.flags.remove(Flags::IS_MODIFIER);
            }
            if test_for_assignment(&identifier) {
                self.flags.insert(Flags::IS_ASSIGNMENT);
            } else {
                self.flags.remove(Flags::IS_ASSIGNMENT);
            }
            self.identifier = identifier;
            true
        } else {
            false
        }
    }

    /// Check if this is a modifier rule (all uppercase identifier)
    pub fn is_modifier(&self) -> bool {
        self.flags.contains(Flags::IS_MODIFIER)
    }

    /// Check if this is an assignment rule (identifier starts with underscore)
    pub fn is_assignment(&self) -> bool {
        self.flags.contains(Flags::IS_ASSIGNMENT)
    }

    /// Get the rule's type definition
    pub fn typedef(&self) -> &Typedef {
        &self.typedef
    }

    /// Set a new type definition for the rule
    ///
    /// Resets the value to empty and marks the rule as touched
    /// 
    /// # Returns
    /// `true` if the rule changed, else `false` 
    pub fn set_typedef(&mut self, typedef: Typedef) -> bool {
        if self.typedef != typedef {
            match self.value.clone().to_type(&typedef) {
                Ok(value) => self.value = value,
                _ => self.value = Value::empty(),
            }
            self.typedef = typedef;
            true
        } else {
            false
        }
    }

    /// Get the rule's expression
    pub fn expression(&self) -> &Expression {
        &self.expression
    }

    /// Set a new expression for the rule
    ///
    /// Marks the rule as touched if the expression differs from the current one
    /// 
    /// # Returns
    /// `true` if the rule changed, else `false` 
    pub fn set_expression(&mut self, expression: Expression) -> bool {
        if self.expression.to_formula() != expression.to_formula() {
            self.expression = expression;
            true
        } else {
            false
        }
    }

    /// Get the rule's current value
    pub fn value(&self) -> Arc<Value> {
        self.value.clone()
    }

    /// Set the rule's value
    ///
    /// # Parameters
    /// The value to set. Must match `typedef` unless empty or error.
    /// 
    /// This function does not set special typedef values.
    ///
    /// # Returns
    /// `Ok(())` if the value matches the rule's type, `Err` otherwise
    pub fn set_value(&mut self, value: Arc<Value>) -> Result<()> {
        if !self.typedef.is_special() && (value.is_empty() || value.is_error() || value.is_of_type(&self.typedef)) {
            self.value = value;
            Ok(())
        } else {
            Err(anyhow!(
                "Type mismatch, expecting {} found {}",
                self.typedef.as_str(),
                value.type_as_string()
            ))
        }
    }

    pub fn rename_node(&self, identifier: Arc<str>) -> Result<Self> {
        // Update the node's reference if it's a node-typed rule
        if self.is_node() {
            if let Some(old_node) = self.get_node() {
                // Rename the reference with the updated identifier
                let old_reference = old_node.reference()?;
                let new_reference = Arc::new(old_reference.rename_child(identifier.clone()));
                // Create a new unloaded node
                let new_node = Node::init_new(new_reference, old_node.inference());
                // Create the new rule value
                let value = Arc::new(Value::Node(new_node));
                // Create a new rule
                Ok(Rule::new(identifier, self.typedef.clone(), Expression::Empty, value))
            } else {
                Err(anyhow!("Node missing from Rule {}", self.identifier))
            }
        } else {
            Err(anyhow!("Type mismatch, expecting Node found {}", self.typedef.as_str()))
        }
    }
    /// Check if this is a format rule
    pub fn is_format(&self) -> bool {
        self.typedef.is_format() && self.value.is_format()
    }

    /// Check if this is an evaluation rule
    pub fn is_eval(&self) -> bool {
        self.typedef.is_eval() && self.value.is_eval()
    }

    /// Mark an evaluation rule as passing
    ///
    /// Only affects rules with Eval type definitions
    /// 
    /// # Returns
    /// `true` if the rule changed, else `false` 
    pub fn set_pass(&mut self) -> Result<()> {
        let value = self.value.to_pass()?;
        self.set_value(Arc::new(value))
    }

    /// Mark an evaluation rule as failing
    ///
    /// Only affects rules with Eval type definitions
    /// 
    /// # Returns
    /// `true` if the rule changed, else `false` 
    pub fn set_fail(&mut self) -> Result<()> {
        let value = self.value.to_fail()?;
        self.set_value(Arc::new(value))
    }

    /// Check if this is a node rule
    pub fn is_node(&self) -> bool {
        self.typedef.is_node() && self.value.is_node()
    }

    /// Get the node from this rule if it is a node rule
    ///
    /// # Returns
    /// `Some(Node)` if this is a node rule with a node value, `None` otherwise
    pub fn get_node(&self) -> Option<Node> {
        self.value.get_node()
    }

    pub fn get_instance(&self) -> Option<Instance> {
        self.value.get_instance()
    }

    /// Write the rule's complete definition to a writer
    ///
    /// Outputs the rule in AIM format: `identifier: typedef = expression $value`
    pub fn print(&self, writer: &mut Writer) {
        writer.write_str(&self.identifier);
        writer.write_str(": ");
        self.typedef.print(writer);
        writer.write_str(" = ");
        if self.expression.is_empty() {
            if self.value.is_constant() {
                writer.write_char('$');
            }
            self.value.print(writer);
        } else {
            self.expression.print(writer);
            if self.value.is_constant() {
                writer.write_str(" $");
                self.value.print(writer);
            }
        }
    }

}

/// Parse a rule from a single AIM line.

pub fn parse_rule(input: &str) -> Result<Rule> {
    match parse_rule_elements(input).finish() {
        Ok((_, rule)) => Ok(rule),
        Err(e) => Err(anyhow!("Parse error: {}", e)),
    }
}

/// Parse the raw elements of a rule line.

fn parse_rule_elements(input: &str) -> IResult<&str, Rule> {
    let (input, (_, identifier, _, typedef, _)) = (
        multispace0,
        parse_arc_identifier,
        delimited(multispace0, char(':'), multispace0),
        parse_typedef,
        delimited(multispace0, char('='), multispace0),
    ).parse(input)?;
    let (input, (expression, value)) = parse_rule_operands(input, &typedef)?;
    
    Ok((input, Rule::new(identifier, typedef, expression, value)))
}

/// Parse the expression and value operands of a rule.
fn parse_rule_operands<'a>(
    input: &'a str,
    typedef: &Typedef,
) -> IResult<&'a str, (Expression, Arc<Value>)> {
    // Parse expression `$` value
    let input = input.trim(); // S?

    // The parsing strategy depends on the typedef:
    let (input, value) = if input.is_empty() {
        // - Empty input results in `Expression::Empty`
        if typedef.is_format() || typedef.is_instance() {
            // Format and instance should never be empty
            return Err(nom::Err::Error(Error::new(input, ErrorKind::Fail)));
        } else if typedef.is_node() {
            // Node types should create a default node when empty
            let node = Node::default();
            (input, Arc::new(Value::Node(node)))
        } else {
            (input, Value::empty())
        }
    } else if input.starts_with('$') {
        // - Constant values are from statically evaluated expressions
        let (input, _) = char('$')(input)?;
        let (input, value) = parse_value(input)?;
        (input, value)
    } else if typedef.is_closure() {
        // - Closure types are parsed as args => expression
        let (input, closure) = parse_closure(input)?;
        (input, Arc::new(Value::Closure(Arc::new(closure))))
    } else if typedef.is_eval() {
        // - Eval types are parsed as ratio, score, count
        let (input, eval) = parse_eval(input)?;
        (input, Arc::new(Value::Eval(eval)))
    } else if typedef.is_format() {
        // - Format types are parsed as "Instruction" <format> "Example", "Example", "Example"...
        let (input, format) = parse_format(input)?;
        (input, Arc::new(Value::Format(format)))
    } else if typedef.is_instance() {
        // - Instance types are parsed as source, target
        let (input, instance) = parse_instance(input)?;
        (input, Arc::new(Value::Instance(instance)))
    } else if typedef.is_node() {
        // - Node types are parsed as pattern, model
        let (input, node) = parse_node(input)?;
        (input, Arc::new(Value::Node(node)))
    } else {
        // - Expression types are parsed as normal
        let (input, expression) = if typedef.is_branch() {
            let (input, branch) = parse_branch(input)?;
            (input, Expression::Branch(branch))
        } else if typedef.is_retry() {
            let (input, retry) = parse_retry(input)?;
            (input, Expression::Retry(retry))
        } else {
            // Parse expression
            parse_expression(input)?
        };
        let (input, _) = multispace0(input)?; // S?
        let (input, value) = if input.starts_with('$') {
            let (input, _) = char('$')(input)?;
            let (input, value) = parse_value(input)?;
            (input, value)
        } else {
            (input, Value::empty())
        };
        return Ok((input, (expression, value)));
    };
    Ok((input, (Expression::Empty, value)))
}

impl ExpressionLike for Rule {
    /// Evaluate the rule's expression and return a [`Value`], handling errors
    /// gracefully, or if empty, return the rule's value.
    ///
    /// - If `expression` is non-empty, this evaluates the expression.
    /// - If `expression` is empty, this returns a clone of the stored `value`.
    ///
    /// This method evaluates the rule expression in the given context.
    ///
    /// - If the expression is empty, returns the stored value.
    /// - If the expression is non-empty, delegates to the underlying
    ///   [`ExpressionLike::evaluate`] implementation.
    ///
    /// # Arguments
    ///
    /// * `context` - The evaluation context providing variable values and function implementations
    ///
    /// # Returns
    ///
    /// Returns a [`Value`] representing the result of evaluation. If evaluation
    /// succeeds, returns the computed value. If evaluation fails, returns an
    /// [`Errata`] value containing error information.
    ///
    /// # See Also
    ///
    /// - [`ExpressionLike::evaluate`] - The underlying evaluation method that returns [`Result`]
    /// - [`Value`] - The result type returned by evaluation
    fn evaluate(&self, context: &mut dyn ContextLike) -> Result<Arc<Value>> {
        if self.expression.is_empty() {
            Ok(self.value.clone())
        } else {
            self.expression.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 Rule {
    fn write(&self, writer: &mut Writer) {
        self.print(writer);
    }
}

impl fmt::Display for Rule {
    /// Display the rule's content (expression or value) for user-facing output
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let mut writer = Writer::formulizer();
        if self.value.is_empty() {
            self.expression.print(&mut writer);
        } else {
            self.value.print(&mut writer);
        }
        write!(f, "{}", writer.finish())
    }
}