aimx/expressions/

reference.rs

//! Variable reference parsing for the AIMX language.
//!
//! This module provides the core functionality for parsing variable references in AIMX
//! expressions. References are used to access values from the evaluation context and
//! can represent simple identifiers or chained property accessors.
//!
//! # Reference Types
//!
//! - **Simple Identifiers**: Single variable names like `variable` or `$inference`
//! - **Chained Accessors**: Dot-separated references like `object.property` or `object.property.method`
//! - **Inference Calls**: References prefixed with `$` that are used for AI inference
//!
//! # Examples
//!
//! ```rust
//! use aimx::expressions::reference::{Reference, parse_reference};
//!
//! // Parse simple identifier
//! let (_, reference) = parse_reference("variable").unwrap();
//! assert_eq!(reference.to_string(), "variable");
//!
//! // Parse chained property access
//! let (_, reference) = parse_reference("object.property").unwrap();
//! assert_eq!(reference.to_string(), "object.property");
//!
//! // Parse inference call (note the $ is stripped during parsing)
//! let (_, reference) = parse_reference("$workflow.inference").unwrap();
//! assert_eq!(reference.to_string(), "workflow.inference");
//! ```

use nom::{
    IResult, Parser,
    error::Error,
    Err as NomErr,
    branch::alt,
    bytes::complete::tag,
    character::complete::{alpha1, alphanumeric1, multispace0},
    combinator::{map, opt, recognize},
    multi::{many0_count},
    sequence::{pair},
};
use crate::{
    ContextLike,
    ExpressionLike,
    expressions::parse_accessor,
    Value,
    Writer,
};
use std::{
    fmt,
    fs,
    path::{Path, PathBuf},
};
use anyhow::{anyhow, Result};

/// Represents a variable reference in an AIMX expression.
///
/// The `Reference` enum defines the structure of variable references used throughout
/// the AIMX language. References can be simple identifiers or chained property accessors.
/// They are used to access values from the evaluation context.
///
/// # Variants
///
/// - `One(String)` - A single identifier reference (e.g., `variable`)
/// - `Two(String, String)` - A two-part chained reference (e.g., `object.property`)
/// - `Three(String, String, String)` - A three-part chained reference (e.g., `object.property.method`)
///
/// # Examples
///
/// ```rust
/// use aimx::expressions::reference::Reference;
///
/// // Create references programmatically
/// let simple = Reference::One("variable".to_string());
/// let chained = Reference::Two("object".to_string(), "property".to_string());
/// let nested = Reference::Three("parent".to_string(), "child".to_string(), "method".to_string());
///
/// // References implement Display for easy formatting
/// assert_eq!(simple.to_string(), "variable");
/// assert_eq!(chained.to_string(), "object.property");
/// assert_eq!(nested.to_string(), "parent.child.method");
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub enum Reference {
    /// A single identifier reference
    One(String),
    /// A two-part chained property reference
    Two(String, String),
    /// A three-part chained property reference
    Three(String, String, String),
}

impl Reference {
    pub fn new(identifier: &str) -> Self {
        Reference::One(identifier.to_string())
    }

    pub fn append(&self, identifier: &str) -> Result<Reference> {
        match self {
            Reference::One(scope_one)
                => Ok(Reference::Two(scope_one.clone(), identifier.to_string())),
            Reference::Two(scope_one , scope_two)
                => Ok(Reference::Three(scope_one.clone(), scope_two.clone(), identifier.to_string())),
            Reference::Three(..) => Err(anyhow!("Cannot append {} to {} scope~{}", identifier, self, identifier)),
        }
    }

    pub fn normalize(&self, reference: &Reference) -> Result<Reference> {
        match self {
            Reference::One(scope_one) => {
                match reference {
                    Reference::One(reference_one)
                        => Ok(Reference::Two(scope_one.clone(), reference_one.clone())),
                    Reference::Two(reference_one, reference_two)
                        => Ok(Reference::Three(scope_one.clone(), reference_one.clone(), reference_two.clone())),
                    Reference::Three(..) => Err(anyhow!("Cannot normalize {} within {} scope~{}", reference, self, reference))
,
                }
            }
            Reference::Two(scope_one , scope_two) => {
                match reference {
                    Reference::One(reference_one)
                        => Ok(Reference::Three(scope_one.clone(), scope_two.clone(), reference_one.clone())),
                    _ => Err(anyhow!("Cannot normalize {} within {} scope~{}", reference, self, reference)),
                }
            }
            Reference::Three(..) => Err(anyhow!("Cannot normalize {} within {} scope~{}", reference, self, reference)),
        }
    }

    pub fn to_path(&self, workspace: &Path) -> PathBuf {        
        match self {
            Reference::One(one) => {
                // Single identifier: workspace/{one}.aim
                workspace.join(format!("{}.aim", one))
            }
            Reference::Two(one, two) => {
                // Two-part reference: workspace/{one}/{two}.aim
                workspace.join(one).join(format!("{}.aim", two))
            }
            Reference::Three(one, two, three) => {
                // Three-part reference: workspace/{one}/{two}/{three}.aim
                workspace.join(one).join(two).join(format!("{}.aim", three))
            }
        }
    }

    pub fn create_path(&self, workspace: &Path) -> Result<PathBuf> {        
        match self {
            Reference::One(one) => {
                if !workspace.exists() {
                    fs::create_dir_all(&workspace)?;
                }
                // Single identifier: workspace/{one}.aim
                Ok(workspace.join(format!("{}.aim", one)))
            }
            Reference::Two(one, two) => {
                let new_dir = workspace.join(one);
                if !new_dir.exists() {
                    fs::create_dir_all(&new_dir)?;
                }
                // Two-part reference: workspace/{one}/{two}.aim
                Ok(new_dir.join(format!("{}.aim", two)))
            }
            Reference::Three(one, two, three) => {
                let new_dir = workspace.join(one).join(two);
                if !new_dir.exists() {
                    fs::create_dir_all(&new_dir)?;
                }
                // Three-part reference: workspace/{one}/{two}/{three}.aim
                Ok(new_dir.join(format!("{}.aim", three)))
            }
        }
    }
}

impl PartialEq<String> for Reference {
    fn eq(&self, other: &String) -> bool {
        match self {
            Reference::One(s) => s == other,
            _ => false
        }
    }
}

impl PartialEq<Reference> for String {
    fn eq(&self, other: &Reference) -> bool {
        match other {
            Reference::One(s) => other == s,
            _ => false
        }
    }
}

/// Parse an identifier according to JSON language specification.
/// 
/// Identifiers in AIM follow standard JSON naming conventions: they must start
/// with a letter, dollar sign or underscore, followed by any combination of
/// letters, digits, and underscores.
/// 
/// Leading underscore identifiers represent an alignable reference for inference
/// output.
/// 
/// # Arguments
/// 
/// * `input` - A string slice to parse for an identifier
/// 
/// # Returns
/// 
/// * `IResult<&str, String>` - A nom result with remaining input and parsed identifier
/// 
/// # Examples
/// 
/// ```rust
/// use aimx::expressions::reference::parse_identifier;
/// 
/// assert_eq!(parse_identifier("foo"), Ok(("", "foo".to_string())));
/// assert_eq!(parse_identifier("_bar123"), Ok(("", "_bar123".to_string())));
/// assert_eq!(parse_identifier("my_function"), Ok(("", "my_function".to_string())));
/// ```
pub fn parse_identifier(input: &str) -> IResult<&str, String> {
    map(
        recognize(pair(
            alt((alpha1, tag("_"))),
            many0_count(alt((alphanumeric1, tag("_")))),
        )),
        |s: &str| s.to_string(),
    )
    .parse(input)
}

/// Parse a reference chain: identifier (accessor identifier)*
///
/// This function parses variable references that can consist of one to three
/// chained identifiers separated by accessors (dots). The parser handles
/// inference calls (prefixed with `$`) and respects AIMX's syntax rules
/// for method calls and function references.
///
/// # Syntax Rules
///
/// - **Simple references**: `variable`, `_assignment`, `$inference`
/// - **Chained references**: `object.property`, `object.property.method`
/// - **Inference calls**: `$tool.summarize`, `$workflow.process`
/// - **Method calls**: When followed by `(`, chained references are truncated
///   to support method syntax like `object.property.method()`
///
/// # Arguments
///
/// * `input` - The input string to parse
///
/// # Returns
///
/// Returns a `IResult<&str, Reference>` containing the remaining unparsed input
/// and the parsed `Reference`.
///
/// # Examples
///
/// ```rust
/// use aimx::expressions::reference::{parse_reference, Reference};
///
/// // Parse simple references
/// assert_eq!(parse_reference("variable").unwrap().1, Reference::One("variable".to_string()));
/// assert_eq!(parse_reference("_assignment").unwrap().1, Reference::One("_assignment".to_string()));
/// assert_eq!(parse_reference("$inference").unwrap().1, Reference::One("inference".to_string()));
///
/// // Parse chained references
/// let (_, reference) = parse_reference("object.property").unwrap();
/// assert_eq!(reference, Reference::Two("object".to_string(), "property".to_string()));
///
/// let (_, reference) = parse_reference("parent.child.grandchild").unwrap();
/// assert_eq!(reference, Reference::Three("parent".to_string(), "child".to_string(), "grandchild".to_string()));
///
/// // Parse inference calls
/// let (_, reference) = parse_reference("$tool.summarize").unwrap();
/// assert_eq!(reference, Reference::Two("tool".to_string(), "summarize".to_string()));
/// ```
///
/// # Error Cases
///
/// The parser will fail for:
/// - Empty identifiers (`_` followed by accessor)
/// - Identifiers starting with `_` followed by parentheses
/// - References that would exceed three parts
pub fn parse_reference(input: &str) -> IResult<&str, Reference> {
    // Check for leading dollar
    let (input, dollar) = opt(tag("$")).parse(input)?;
    let function = dollar.is_none();
    // Parse the one identifier
    let (input, one) = parse_identifier(input)?;
    let (input, _) = opt(multispace0).parse(input)?;
    // Empty or Function
    if function && (&one == "_" || input.starts_with('(')) {
        return Err(NomErr::Failure(Error::new(input, nom::error::ErrorKind::Fail)));
    }
    if let Ok((remainder, _)) = parse_accessor(input) {
        let (remainder, two) = parse_identifier(remainder)?;
        let (remainder, _) = opt(multispace0).parse(remainder)?;
        // Method
        if function && remainder.starts_with('(') {
            // roll back input
            let reference = Reference::One(one.clone());
            return Ok((input, reference));
        }
        let input = remainder;

        if let Ok((remainder, _)) = parse_accessor(input) {
            let (remainder, three) = parse_identifier(remainder)?;
            let (remainder, _) = opt(multispace0).parse(remainder)?;
            if function && remainder.starts_with('(') {
                // roll back input
                let reference =
                    Reference::Two(one.clone(), two.clone());
                return Ok((input, reference));
            }
            
            let reference = Reference::Three(one.clone(), two.clone(), three.clone());
            Ok((remainder, reference))
        } else {
            let reference = Reference::Two(one.clone(), two.clone());
            Ok((input, reference))
        }
    } else {
        let reference = Reference::One(one.clone());
        Ok((input, reference))
    }
}


impl ExpressionLike for Reference {
    /// Evaluate this reference by looking up its value in the context.
    ///
    /// # Arguments
    ///
    /// * `context` - The evaluation context to lookup the reference in
    ///
    /// # Returns
    ///
    /// Returns a `Result<Value>` containing the value of the referenced variable
    /// or an error if the reference cannot be resolved.
    fn evaluate(&self, context: &mut dyn ContextLike) -> Result<Value> {
        context.get_referenced(self)
    }

    fn write(&self, writer: &mut Writer) {
        writer.write_reference(self);
    }
    fn to_sanitized(&self) -> String {
        let mut writer = Writer::sanitizer();
        writer.write_reference(self);
        writer.finish()
    }
    fn to_formula(&self) -> String {
        let mut writer = Writer::formulizer();
        writer.write_reference(self);
        writer.finish()
    }
}

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