aimx/functions/

mod.rs

//! Built-in function library for AIM expressions.
//!
//! This module provides a comprehensive collection of built-in functions organized by category
//! to extend the capabilities of AIM expressions. Functions can be called directly as
//! `function_name(args)` or as methods on values like `array.sum()`.
//!
//! # Overview
//!
//! The function library is designed to provide spreadsheet-like functionality with the power
//! of a programming language. Functions are organized into logical categories and can be
//! composed together to create complex expressions.
//!
//! # Function Categories
//!
//! The function library is organized into the following categories:
//!
//! ## Business Functions
//! Financial calculations, growth analysis, and business metrics.
//! - `round_to(number, decimals)` - Round with decimal control
//! - `percent_of(number, total)` - Calculate percentage of total
//! - `increase(number, percent)` - Increase by percentage
//! - `decrease(number, percent)` - Decrease by percentage
//! - `gross_margin(cost, price)` - Calculate gross margin
//! - `markup(cost, percent)` - Apply markup to cost
//! - `growth(from, to)` - Calculate period-over-period growth
//! - `runway(funding, expenses)` - Calculate runway based on funding and expenses
//! - `monthly_payment(principal, rate, years)` - Calculate monthly loan payment
//! - `break_even(fixed_costs, price, variable_cost)` - Calculate break-even point
//! - `roi(investment, return_amount)` - Calculate Return on Investment
//! - `split_amount(percentages, total)` - Split amount across percentages
//! - `tax_inclusive(amount, tax_rate)` - Calculate tax-inclusive amount
//! - `tax_exclusive(amount, tax_rate)` - Calculate tax-exclusive amount
//! 
//! ## Collection Functions
//! Array manipulation, filtering, and transformation functions.
//! - `len(array)` - Length of array or string
//! - `count(array)` - Count of array elements
//! - `find(array, closure)` - Returns the first element that satisfies a predicate
//! - `find_index(array, closure)` - Returns the index of the first element that satisfies a predicate
//! - `flatten(array)` - Flatten nested arrays
//! - `unique(array)` - Get unique elements from single array
//! - `reverse(array)` - Reverse array
//! - `take(array, count)` - Get first n elements
//! - `take_right(array, count)` - Get last n elements
//! - `skip(array, count)` - Skip first n elements
//! - `skip_right(array, count)` - Skip last n elements
//! - `chunk(array, size)` - Chunk array into groups of n
//! - `group_by(array, closure)` - Group elements by key from closure
//! - `partition(array, closure)` - Partition array into two based on predicate
//! - `sort_by(array, closure)` - Sort array by closure
//! - `all_unique(array)` - Check if all elements are unique
//! - `take_while(array, closure)` - Take elements while predicate is true
//! - `skip_while(array, closure)` - Skip elements while predicate is true
//! - `zip(array1, array2)` - Zip two arrays together into pairs
//! - `unzip(pairs)` - Unzip array of pairs into two arrays
//!
//! ## Date Functions
//! Date parsing, formatting, and calculation functions.
//! - `as_date(text, format)` - Parse text as date
//! - `format_date(date, format)` - Format date as text
//! - `days_between(date1, date2)` - Calculate days between dates
//! - `add_days(date, days)` - Add days to date
//! - `workdays(date1, date2)` - Calculate workdays between dates
//! - Date methods:
//!   - `date.year()` - Year component
//!   - `date.month()` - Month component
//!   - `date.day()` - Day component
//!   - `date.hour()` - Hour component
//!   - `date.minute()` - Minute component
//!   - `date.second()` - Second component
//! 
//! ## Functional Programming Support
//! Higher-order functions for functional programming patterns.
//! - `map(array, closure)` - Apply closure to each element of array
//! - `select(array, closure)` - Like map but also provides the index to the closure
//! - `filter(array, closure)` - Filter array elements using predicate closure
//! - `reduce(array, initial, closure)` - Reduce array to single value using accumulator closure
//! - `scan(array, initial, closure)` - Like reduce but keeps intermediate results
//! - `some(array, closure)` - Returns true if any element satisfies the predicate
//! - `every(array, closure)` - Returns true if all elements satisfy the predicate
//! - `none(array, closure)` - Returns true if no elements satisfy the predicate
//! - `exactly_one(array, closure)` - Returns true if exactly one element satisfies the predicate
//!
//! ## Mathematical Functions
//! Basic arithmetic, trigonometric, logarithmic, and advanced mathematical operations.
//! - `abs(x)` - Absolute value
//! - `sign(x)` - Sign of number
//! - `floor(x)` - Floor function
//! - `ceil(x)` - Ceiling function
//! - `round(x)` - Round to nearest integer
//! - `trunc(x)` - Truncate decimal places
//! - `sqrt(x)` - Square root
//! - `pow(base, exp)` - Power function
//! - `exp(x)` - e^x
//! - `ln(x)` - Natural logarithm
//! - `log10(x)` - Base 10 logarithm
//! - `log2(x)` - Base 2 logarithm
//! - `sin(x)` - Sine function
//! - `cos(x)` - Cosine function
//! - `tan(x)` - Tangent function
//! - `asin(x)` - Arc sine
//! - `acos(x)` - Arc cosine
//! - `atan(x)` - Arc tangent
//! - `atan2(y, x)` - Arc tangent with two arguments
//! - `sinh(x)` - Hyperbolic sine
//! - `cosh(x)` - Hyperbolic cosine
//! - `tanh(x)` - Hyperbolic tangent
//! - `random()` - Random number between 0 and 1
//! - `clamp(x, min, max)` - Constrain to range
//! - `lerp(a, b, t)` - Linear interpolation
//! - `gcd(a, b)` - Greatest common divisor
//! - `lcm(a, b)` - Least common multiple
//! - `is_nan(x)` - Check if NaN
//! - `is_finite(x)` - Check if finite
//! - `PI()` - Mathematical constant π
//! - `E()` - Mathematical constant e
//! - `NaN()` - Not-a-number value
//!
//! ## Number Functions
//! Number formatting and conversion utilities.
//! - `ordinal(number)` - Convert number to ordinal (1st, 2nd, etc.)
//! - `format_currency(number, symbol)` - Format as currency
//! - `format_number(number, decimals)` - Format with specified decimals
//!
//! ## Set Functions
//! Set operations on arrays.
//! - `union(array1, array2)` - Returns the union of two arrays (unique elements from both)
//! - `intersection(array1, array2)` - Returns the intersection of two arrays (elements common to both)
//! - `difference(array1, array2)` - Returns elements in first array that are not in second array
//! - `exclusive(array1, array2)` - Elements in either array but not both
//! - `is_subset(array1, array2)` - Check if first array is subset of second array
//! - `set_equals(array1, array2)` - Check if arrays are equal as sets (ignoring order)
//! - `overlaps(array1, array2)` - Check if arrays have any common elements
//!
//! ## Statistical Functions
//! Descriptive statistics, trend analysis, and data processing.
//! - `min(array)` - Minimum value in array
//! - `max(array)` - Maximum value in array
//! - `sum(array)` - Sum of array values
//! - `average(array)` - Average of array values
//! - `avg(array)` - Average of array values
//! - `median(array)` - Median value
//! - `mode(array)` - Mode value
//! - `range(array)` - Range of values
//! - `stdev(array)` - Standard deviation
//! - `variance(array)` - Variance
//! - `percentile(array, percentage)` - Percentile value
//! - `quartile(array, quartile)` - Quartile value (1, 2, or 3)
//! - `growth_rate(from, to)` - Growth rate calculation
//! - `slope(x_values, y_values)` - Linear regression slope
//! - `correlation(x_values, y_values)` - Pearson correlation coefficient
//! - `moving_average(array, period)` - Moving average
//! - `cumulative_sum(array)` - Cumulative sum array
//! - `rank(array, value)` - Rank of value in array
//! - `percentile_rank(array, value)` - Percentile rank of value
//! - `outliers(array)` - Array of outlier values
//! - `frequency(array, bins)` - Frequency distribution
//! - `unique_count(array)` - Count of unique values
//! - Various count functions:
//!   - `count_if_gt(array, threshold)` - Count values > threshold
//!   - `count_if_ge(array, threshold)` - Count values >= threshold
//!   - `count_if_lt(array, threshold)` - Count values < threshold
//!   - `count_if_le(array, threshold)` - Count values <= threshold
//!   - `count_if(array, value)` - Count values equal to value
//!   - `count_if_ne(array, value)` - Count values not equal to value
//! - `confidence(alpha, stdev, size)` - Confidence interval
//! - `margin_of_error(array, alpha)` - Margin of error
//!
//! ## Task Functions
//! Task creation and management for agentic workflows.
//! - `task(text)` - Create a new pending task with the text expression
//! - `perform(tasks, attempts, closure)` - Perform pending tasks one by one with retry attempts
//! - `follow(plan, closure)` - Like perform, but with entire plan (tasks).
//! - Task methods:
//!   - `task.done()` - Mark task as completed
//!   - `task.pending()` - Mark task as pending
//!   - `task.failed()` - Mark task as failed
//!
//! ## Text Functions
//! String manipulation, formatting, and analysis functions.
//! - `concat(array)` - Concatenate array of strings
//! - `join_with(array, sep)` - Join array with separator
//! - `split(text, delim)` - Split text into array
//! - `substring(text, start, len)` - Extract substring
//! - `upper(text)` - Convert to uppercase
//! - `lower(text)` - Convert to lowercase
//! - `proper(text)` - Convert to proper case
//! - `trim(text)` - Trim whitespace
//! - `contains(text, sub)` - Check if contains substring
//! - `replace(text, old, new)` - Replace first occurrence
//! - `replace_all(text, old, new)` - Replace all occurrences
//! - `starts_with(text, prefix)` - Check if starts with prefix
//! - `ends_with(text, suffix)` - Check if ends with suffix
//! - `if_empty(text, default)` - Return default if empty
//! - `pluralize(text, count, suffix)` - Pluralize text
//! - `truncate(text, len, suffix)` - Truncate text
//! - `mask_sensitive(text, start, end)` - Mask sensitive data
//!
//! ## Miscellaneous Functions
//! Debugging and development utilities.
//! - `debug(value)` - Print value to stderr and return unchanged (useful for debugging expressions)
//!
//! ## Evaluation Functions
//! Evaluation tracking and performance monitoring for agentic workflows.
//! - `pass(eval)` - Record successful evaluation attempt
//! - `fail(eval)` - Record failed evaluation attempt
//! - `score(eval)` - Calculate success rate as percentage
//!
//! # Usage Examples
//!
//! Functions are used in AIMX expressions with standard function call syntax:
//!
//! ```aimx
//! // Mathematical functions: sqrt(16) + abs(-5) = 9
//! // Text functions: 'hello'.upper() + ' ' + 'WORLD'.lower() = "HELLO world"
//! // Array functions: (1, 5, 3).max() = 5
//! // Function composition: sqrt(pow(2, 3) + max((1, 5, 3))) = 4
//! ```

mod business;
mod collection;
mod date;
mod eval;
mod functional;
mod math;
mod misc;
mod number;
mod set;
mod statistical;
mod task;
mod text;

use crate::function_registry::FunctionRegistry;

/// Register all available functions with the function registry.
///
/// This function registers all functions from all categories with the provided
/// function registry, making them available for use in AIM expressions.
///
/// # Arguments
///
/// * `registry` - The function registry to populate with functions
///
/// In practice, these functions are automatically registered and made available for use in AIMX expressions.
pub fn register_all_functions(registry: &mut FunctionRegistry) {
    business::register_functions(registry);
    collection::register_functions(registry);
    date::register_functions(registry);
    eval::register_functions(registry);
    functional::register_functions(registry);
    math::register_functions(registry);
    misc::register_functions(registry);
    number::register_functions(registry);
    set::register_functions(registry);
    statistical::register_functions(registry);
    task::register_functions(registry);
    text::register_functions(registry);
    // Update list when you add new modules
}