aimx/

function_registry.rs

//! Function registry and calling interface.
//!
//! This module provides the function registry system that manages
//! standalone functions and methods available in expressions.
//! It also includes utilities for converting between [`Value`] types
//! and native Rust types for function implementations.
//!
//! The function registry is a thread-safe singleton that uses [`OnceLock`] and [`RwLock`]
//! to ensure one-time initialization with all built-in functions registered while
//! allowing multiple concurrent readers.
//!
//! # Usage
//!
//! Functions are typically registered using the macros provided in [`crate::macros`]
//! and are automatically available through the global registry:
//!
//! ```rust
//! use aimx::{aimx_parse, ExpressionLike, Context};
//!
//! let mut context = Context::new();
//! let expression = aimx_parse("sqrt(16) + abs(-5)");
//! let result = expression.evaluate(&mut context).unwrap();
//! assert_eq!(result.to_string(), "9");
//! ```
//!
//! Custom functions can be registered with the registry:
//!
//! ```rust
//! use aimx::{function_registry::FunctionRegistry, define_direct_function};
//!
//! // Get a write lock on the registry
//! let mut registry = FunctionRegistry::write_lock().unwrap();
//! 
//! // Register a custom function
//! define_direct_function!(
//!     double,
//!     args: [f64],
//!     |x: f64| x * 2.0
//! )(&mut *registry);
//!
//! // Drop the lock to allow other threads to access the registry
//! drop(registry);
//! ```
//!
//! Functions can be called as standalone functions or as methods on values:
//!
//! ```aimx
//! // Standalone function call
//! sqrt(16)
//!
//! // Method call on array
//! (1, 2, 3).sum()
//! ```

use std::collections::HashMap;
use std::sync::OnceLock;
use std::sync::RwLock;
use anyhow::{anyhow, Result};
use crate::{
    ContextLike,
    Value,
    Literal,
    functions,
};
use jiff::civil::DateTime;

/// Registry for managing function handlers.
///
/// The function registry maintains a collection of named function handlers
/// that can be called during expression evaluation. It supports both
/// standalone functions and methods called on values.
///
/// This registry is a thread-safe singleton that ensures one-time initialization
/// with all built-in functions registered.
pub struct FunctionRegistry {
    handlers: HashMap<String, Box<dyn FunctionHandler>>,
}

/// Trait for function handlers.
///
/// This trait defines the interface that all function handlers must implement.
/// Function handlers are responsible for executing the actual function logic
/// and returning the result as a [`Value`].
///
/// This trait is automatically implemented when using the function registration
/// macros in [`crate::macros`].
pub trait FunctionHandler: Send + Sync {
    /// Call the function with the provided arguments.
    ///
    /// # Arguments
    ///
    /// * `context` - The evaluation context for closures
    /// * `args` - A slice of [`Value`] arguments passed to the function
    ///
    /// # Returns
    ///
    /// Returns a `Result<Value>` containing the function result or an error
    /// if the function execution fails.
    ///
    /// # Note
    ///
    /// For method calls, the first argument is typically the value the method
    /// is being called on, followed by any additional arguments.
    fn call(&self, context: &mut dyn ContextLike, args: &[Value]) -> Result<Value>;
}

impl FunctionRegistry {
    /// Get the global singleton instance of the function registry.
    ///
    /// This method uses [`OnceLock`] to ensure thread-safe one-time initialization
    /// of the function registry with all built-in functions registered.
    /// Uses [`RwLock`] to allow multiple concurrent readers while ensuring
    /// exclusive access during writes.
    ///
    /// # Returns
    ///
    /// Returns a reference to the RwLock-protected singleton function registry.
    ///
    /// # Example
    ///
    /// ```
    /// use aimx::function_registry::FunctionRegistry;
    ///
    /// let registry = FunctionRegistry::get_instance();
    /// // Typically you'd use read_lock() or write_lock() instead of accessing directly
    /// ```
    pub fn get_instance() -> &'static RwLock<Self> {
        static INSTANCE: OnceLock<RwLock<FunctionRegistry>> = OnceLock::new();
        
        INSTANCE.get_or_init(|| {
            let mut registry = Self::new();
            functions::register_all_functions(&mut registry);
            RwLock::new(registry)
        })
    }

    /// Get a read lock on the function registry for function calls.
    ///
    /// This is a convenience method that returns a read guard, allowing
    /// multiple concurrent function calls without blocking each other.
    ///
    /// # Returns
    ///
    /// Returns a `Result` containing the read guard or an error if the lock is poisoned.
    ///
    /// # Example
    ///
    /// ```
    /// use aimx::function_registry::FunctionRegistry;
    ///
    /// let registry = FunctionRegistry::read_lock().unwrap();
    /// // Use registry for function calls
    /// ```
    pub fn read_lock() -> Result<std::sync::RwLockReadGuard<'static, Self>> {
        Self::get_instance().read().map_err(|_| anyhow!("Function registry lock is poisoned"))
    }

    /// Get a write lock on the function registry for registration.
    ///
    /// This is a convenience method that returns a write guard, providing
    /// exclusive access for registering new functions.
    ///
    /// # Returns
    ///
    /// Returns a `Result` containing the write guard or an error if the lock is poisoned.
    ///
    /// # Example
    ///
    /// ```
    /// use aimx::{function_registry::FunctionRegistry, define_direct_function};
    ///
    /// let mut registry = FunctionRegistry::write_lock().unwrap();
    /// define_direct_function!(
    ///     custom_func,
    ///     args: [f64],
    ///     |x: f64| x * 2.0
    /// )(&mut *registry);
    /// // Drop the lock to allow other threads to access the registry
    /// ```
    pub fn write_lock() -> Result<std::sync::RwLockWriteGuard<'static, Self>> {
        Self::get_instance().write().map_err(|_| anyhow!("Function registry lock is poisoned"))
    }

    /// Create a new, empty function registry.
    ///
    /// This is primarily used internally during initialization.
    fn new() -> Self {
        Self {
            handlers: HashMap::new(),
        }
    }

    /// Register a function handler with the given name.
    ///
    /// # Arguments
    ///
    /// * `name` - The name to register the function under
    /// * `handler` - The function handler implementation
    ///
    /// # Example
    ///
    /// ```
    /// use aimx::function_registry::{FunctionRegistry, FunctionHandler};
    /// use aimx::{ContextLike, Value, Literal};
    /// use anyhow::Result;
    ///
    /// struct CustomHandler;
    /// 
    /// impl FunctionHandler for CustomHandler {
    ///     fn call(&self, context: &mut dyn ContextLike, args: &[Value]) -> Result<Value> {
    ///         Ok(Value::from(42.0))
    ///     }
    /// }
    /// 
    /// // In practice, you would typically register functions through the write_lock() method
    /// // This example shows the trait implementation for documentation purposes
    /// ```
    pub fn register<F>(&mut self, name: String, handler: F)
    where
        F: FunctionHandler + 'static,
    {
         self.handlers.insert(name, Box::new(handler));
    }

    /// Call a standalone function with the given name and argument.
    ///
    /// This method handles flattening array arguments into individual arguments
    /// before passing them to the function handler.
    ///
    /// # Arguments
    ///
    /// * `context` - The evaluation context for closures
    /// * `name` - The name of the function to call
    /// * `arg` - The argument(s) to pass to the function (can be Empty, Literal, or Array)
    ///
    /// # Returns
    ///
    /// Returns a `Result<Value>` containing the function result or an error
    /// if the function is not found or execution fails.
    ///
    /// # Example
    ///
    /// ```rust
    /// # use aimx::{function_registry::FunctionRegistry, Context, Value, Literal};
    /// # let mut context = Context::new();
    /// # let registry = FunctionRegistry::read_lock().unwrap();
    /// // Call a function with a single argument
    /// let result = registry.function_call(&mut context, "abs", Value::from(-5.0));
    ///
    /// // Call a function with multiple arguments as an array
    /// let args = Value::Array(vec![
    ///     Box::new(Value::from(2.0)),
    ///     Box::new(Value::from(3.0))
    /// ]);
    /// let result = registry.function_call(&mut context, "pow", args);
    /// # assert!(result.is_ok());
    /// ```
    pub fn function_call(&self, context: &mut dyn ContextLike, name: &str, arg: Value) -> Result<Value> {
        let mut args:Vec<Value> = Vec::new();
        match arg {
            Value::Literal(_) => args.push(arg),
            Value::Array(array) => {
                for box_value in array.into_iter() {
                    let value = *box_value;
                    args.push(value);
                }
            }
            _ => {}
        };
        self.handlers
            .get(name)
            .ok_or_else(|| anyhow!("Function '{}' not found~{}", name, name))?
            .call(context, &args)
    }

    /// Call a method on a value with the given name and argument.
    ///
    /// This method passes the target value as the first argument to the
    /// function handler, followed by any additional arguments.
    ///
    /// # Arguments
    ///
    /// * `context` - The evaluation context for closures
    /// * `name` - The name of the method to call
    /// * `value` - The value on which to call the method
    /// * `arg` - The argument(s) to pass to the method (can be Empty, Literal, or Array)
    ///
    /// # Returns
    ///
    /// Returns a `Result<Value>` containing the method result or an error
    /// if the method is not found or execution fails.
    ///
    /// # Example
    ///
    /// ```rust
    /// # use aimx::{function_registry::FunctionRegistry, Context, Value, Literal};
    /// # let mut context = Context::new();
    /// # let registry = FunctionRegistry::read_lock().unwrap();
    /// // Call a method on an array value
    /// let array_value = Value::Array(vec![
    ///     Box::new(Value::from(1.0)),
    ///     Box::new(Value::from(2.0)),
    ///     Box::new(Value::from(3.0))
    /// ]);
    /// let result = registry.method_call(&mut context, "sum", array_value, Value::Array(vec![]));
    /// # assert!(result.is_ok());
    /// ```
    pub fn method_call(&self, context: &mut dyn ContextLike, name: &str, value: Value, arg: Value) -> Result<Value> {
        let mut args:Vec<Value> = Vec::new();
        args.push(value);
        match arg {
            Value::Literal(_) => {
                args.push(arg);
            }
            Value::Array(array) => {
                for box_value in array.into_iter() {
                    let value = *box_value;
                    args.push(value);
                }
            }
            _ => {}
        };
        self.handlers
            .get(name)
            .ok_or_else(|| anyhow!("Method '{}' not found~{}", name, name))?
            .call(context, &args)
    }
}

/// Convert a Value to a native Rust type based on the expected type T.
///
/// This utility function simplifies converting [`Value`] instances to
/// native Rust types in function implementations.
///
/// This function is typically used internally by the function registration macros
/// in [`crate::macros`] and is automatically called when functions are invoked.
///
/// # Arguments
///
/// * `value` - The value to convert
///
/// # Returns
///
/// Returns a `Result<T>` containing the converted value or an error
/// if conversion fails.
///
/// # Example
///
/// ```
/// use aimx::{function_registry::convert_value_to_type, Value, Literal};
///
/// let value = Value::from(42.0);
/// let number: f64 = convert_value_to_type(&value).unwrap();
/// assert_eq!(number, 42.0);
/// ```
pub fn convert_value_to_type<T>(value: &Value) -> Result<T> 
where 
    T: ValueConverter
{
    T::from_value(value)
}

/// Convert a native Rust type back to a Value.
///
/// This utility function simplifies converting native Rust types to
/// [`Value`] instances for function return values.
///
/// This function is typically used internally by the function registration macros
/// in [`crate::macros`] and is automatically called when functions return results.
///
/// # Arguments
///
/// * `result` - The value to convert
///
/// # Returns
///
/// Returns a `Result<Value>` containing the converted value.
///
/// # Example
///
/// ```
/// use aimx::function_registry::convert_result_to_value;
///
/// let number = 42.0;
/// let value = convert_result_to_value(number).unwrap();
/// ```
pub fn convert_result_to_value<T>(result: T) -> Result<Value>
where
    T: Into<Value>
{
    Ok(result.into())
}

/// Trait for converting Values to native types.
///
/// This trait enables automatic conversion between [`Value`] instances and
/// native Rust types. It is implemented for common types like `f64`, `String`,
/// `bool`, `DateTime`, and `Vec<T>`.
///
/// This trait is automatically implemented for common types and is typically
/// used internally by the function registration macros in [`crate::macros`].
pub trait ValueConverter: Sized {
    /// Convert a Value to this native type.
    ///
    /// # Arguments
    ///
    /// * `value` - The value to convert
    ///
    /// # Returns
    ///
    /// Returns a `Result<Self>` containing the converted value or an error
    /// if conversion fails.
    fn from_value(value: &Value) -> Result<Self>;
}

// Implementations for common types
impl ValueConverter for f64 {
    fn from_value(value: &Value) -> Result<Self> {
        value.to_number()
    }
}

impl ValueConverter for String {
    fn from_value(value: &Value) -> Result<Self> {
        match value {
            Value::Literal(Literal::Text(s)) => Ok(s.clone()),
            Value::Literal(literal) => Ok(literal.to_string()),
            Value::Array(_) => Ok(value.to_string()),
            _ => Ok(String::new()),
        }
    }
}

impl ValueConverter for bool {
    fn from_value(value: &Value) -> Result<Self> {
        match value {
            Value::Literal(literal) => Ok(literal.to_bool()),
            Value::Array(array) => Ok(!array.is_empty()),
            _ => Ok(false),
        }
    }
}

impl ValueConverter for DateTime {
    fn from_value(value: &Value) -> Result<Self> {
        match value {
            Value::Literal(Literal::Date(dt)) => Ok(*dt),
            Value::Literal(literal) => {
                // Try to convert the literal to a date
                literal.clone().as_date().and_then(|date_literal| {
                    match date_literal {
                        Literal::Date(dt) => Ok(dt),
                        _ => Err(anyhow!("Failed to convert to DateTime"))
                    }
                })
            },
            _ => Err(anyhow!("Cannot convert {} to DateTime", value.type_as_string()))
        }
    }
}

impl<T: ValueConverter> ValueConverter for Vec<T> {
    fn from_value(value: &Value) -> Result<Self> {
        match value {
            Value::Array(array) => {
                array.iter().map(|box_value| {
                    let value = box_value.as_ref();
                    T::from_value(&value.clone())
                }).collect()
            },
            _ => {
                // For single values, create a single-element vector
                Ok(vec![T::from_value(value)?])
            }
        }
    }
}

impl From<f64> for Value {
    fn from(value: f64) -> Self {
        Value::Literal(Literal::Number(value))
    }
}

impl From<String> for Value {
    fn from(value: String) -> Self {
        Value::Literal(Literal::Text(value))
    }
}

impl From<bool> for Value {
    fn from(value: bool) -> Self {
        Value::Literal(Literal::Bool(value))
    }
}

impl From<DateTime> for Value {
    fn from(value: DateTime) -> Self {
        Value::Literal(Literal::Date(value))
    }
}

impl From<Vec<f64>> for Value {
    fn from(value: Vec<f64>) -> Self {
        Value::Array(value.into_iter().map(|value|Box::new(Value::Literal(Literal::Number(value)))).collect())
    }
}

impl From<Vec<String>> for Value {
    fn from(value: Vec<String>) -> Self {
        Value::Array(value.into_iter().map(|value|Box::new(Value::Literal(Literal::Text(value)))).collect())
    }
}

impl From<Vec<bool>> for Value {
    fn from(value: Vec<bool>) -> Self {
        Value::Array(value.into_iter().map(|value|Box::new(Value::Literal(Literal::Bool(value)))).collect())
    }
}

impl From<Vec<DateTime>> for Value {
    fn from(value: Vec<DateTime>) -> Self {
        Value::Array(value.into_iter().map(|value|Box::new(Value::Literal(Literal::Date(value)))).collect())
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::Literal;

    #[test]
    fn test_function_registry_singleton() {
        let registry1 = FunctionRegistry::get_instance();
        let registry2 = FunctionRegistry::get_instance();
        assert!(std::ptr::eq(registry1, registry2));
    }

    #[test]
    fn test_read_lock() {
        let registry = FunctionRegistry::read_lock();
        assert!(registry.is_ok());
    }

    #[test]
    fn test_write_lock() {
        let registry = FunctionRegistry::write_lock();
        assert!(registry.is_ok());
    }

    #[test]
    fn test_convert_value_to_type_f64() {
        let value = Value::from(42.5);
        let result: Result<f64> = convert_value_to_type(&value);
        assert!(result.is_ok());
        assert_eq!(result.unwrap(), 42.5);
    }

    #[test]
    fn test_convert_value_to_type_string() {
        let value = Value::from("hello".to_string());
        let result: Result<String> = convert_value_to_type(&value);
        assert!(result.is_ok());
        assert_eq!(result.unwrap(), "hello");
    }

    #[test]
    fn test_convert_value_to_type_bool() {
        let value = Value::from(true);
        let result: Result<bool> = convert_value_to_type(&value);
        assert!(result.is_ok());
        assert_eq!(result.unwrap(), true);
    }

    #[test]
    fn test_convert_result_to_value() {
        let result = convert_result_to_value(42.0);
        assert!(result.is_ok());
        match result.unwrap() {
            Value::Literal(Literal::Number(n)) => assert_eq!(n, 42.0),
            _ => panic!("Expected Number literal"),
        }
    }

    #[test]
    fn test_vec_conversion() {
        let values = vec![Value::from(1.0), Value::from(2.0), Value::from(3.0)];
        let array_value = Value::Array(values.into_iter().map(Box::new).collect());
        
        let result: Result<Vec<f64>> = convert_value_to_type(&array_value);
        assert!(result.is_ok());
        assert_eq!(result.unwrap(), vec![1.0, 2.0, 3.0]);
    }
}