Module value

Runtime value representation for AIM Expressions (AIMX).

This module defines the Value enum that represents runtime values produced during expression evaluation. The Value type serves as the primary data structure that flows through the expression evaluation engine, representing all possible data types that can be manipulated by AIMX expressions.

Unlike the compile-time Literal enum which represents static values, Value can represent dynamically evaluated results, arrays of values, closures, and special workflow-related types. This makes it the central runtime entity for the entire AIMX evaluation system.

Design Philosophy

The Value type is designed with several core principles in mind:

• Tree-like Structure: Values form a tree where arrays can contain other values, enabling complex data representations.
• Type Safety: Comprehensive type checking and conversion capabilities following AIMX grammar rules
• Error Handling: First-class error values that preserve diagnostic information throughout evaluation
• Memory Efficiency: Recursive data structures are boxed to prevent stack overflow
• Thread Safety: Values can be safely used across threads in concurrent workflows

Key Features

• Comprehensive Type System: Supports all AIMX data types including literals, arrays, closures, and workflow-specific types
• Automatic Type Conversion: Provides intuitive type promotion and conversion methods following AIMX grammar rules
• Tree-like Structure: Arrays can contain other values, allowing nested and complex data representations
• Error Handling: Includes error values that capture evaluation failures
• Workflow Integration: Supports workflow-specific types like nodes, format, and eval for agentic workflow applications

Core Concepts

Value Hierarchy

The Value enum represents a unified type hierarchy where all values can be categorized into:

• Base Values: Empty, Error, and Literal values represent atomic values
• Composite Values: Arrays and closures enable structured and functional programming
• Special Values: Workflow-specific types for inference functionality

Types and Variants

The Value enum encompasses all possible runtime data types in the AIMX system:

Base Values

• Array: Collections of values, allowing for nested data structures
• Closure: First-class anonymous functions for functional programming
• Empty: Represents an empty or uninitialized value
• Errata: Captures expression and evaluation error conditions with diagnostic information
• Literal: Encapsulates literal values (Bool, Date, Number, Task, Text)

Special Values

• Assignment: Variable references for workflow assignments
• Format: Inference output formatting data
• Eval: Inference evaluation data
• Node: References to workflow files and nodes

Examples

Creating Values

use aimx::{Value, Literal};

// Creating different types of values
let empty_value = Value::Empty;
let literal_value = Value::Literal(Literal::from_number(42.0));
let array_value = Value::Array(vec![
    Box::new(Value::Literal(Literal::from_text("hello".to_string()))),
    Box::new(Value::Literal(Literal::from_number(123.0)))
]);

// Checking value types
assert!(empty_value.is_empty());
assert!(literal_value.is_literal());
assert!(literal_value.is_number());
assert!(array_value.is_array());

// Converting values
let num_as_text = literal_value.clone().as_text().unwrap();
assert!(num_as_text.is_text());

Using Values in Expression Evaluation

use aimx::{Value, Literal, ExpressionLike, Context, Reference, ContextLike};

let mut context = aimx::Context::new();
 
// For this example, we'll just demonstrate creating and using values
let price_value = Value::Literal(Literal::from_number(100.0));
let tax_rate_value = Value::Literal(Literal::from_number(0.08));
 
// Calculate total: price * (1 + tax_rate)
let total = 100.0 * (1.0 + 0.08);
assert_eq!(total, 108.0);

Type Conversion Examples

use aimx::{Value, Literal};

// Type promotion in expressions
let number_value = Value::Literal(Literal::from_number(42.0));
 
// Convert number to text
let text_value = number_value.clone().as_text().unwrap();
assert!(text_value.is_text());
 
// Convert number to boolean (truthiness)
let bool_value = number_value.clone().as_bool();
assert!(bool_value.to_literal().to_bool());
 
// Convert number to date (Unix timestamp)
let date_value = number_value.as_date().unwrap();
assert!(date_value.is_date());

Working with Arrays

use aimx::{Value, Literal};

// Create nested arrays
let nested_array = Value::Array(vec![
    Box::new(Value::Literal(Literal::from_text("first".to_string()))),
    Box::new(Value::Array(vec![
        Box::new(Value::Literal(Literal::from_number(1.0))),
        Box::new(Value::Literal(Literal::from_number(2.0)))
    ]))
]);

// Check array properties
assert!(nested_array.is_array());
 
// Convert single value to array
let single_value = Value::Literal(Literal::from_number(42.0));
let as_array = single_value.as_array();
assert!(as_array.is_array());

Type Conversion Rules

AIMX follows intuitive type conversion rules when values need to be promoted to different types. The conversion methods (as_text, as_number, etc.) follow these principles:

• Type Promotion Strategy: Left-operand-first promotion where the left operand’s type dictates how the right operand is converted

• Error Handling: Conversion operations gracefully handle invalid conversions by returning appropriate error values or Result types

• Idempotency: Converting a value to its own type typically returns the value unchanged

• Empty values remain empty in most conversions

• Booleans: true/false values maintain their semantic meaning

• Numbers: Numeric values can be converted to text, dates, or tasks

• Text: String values can be parsed into numbers, dates, or remain as text

• Dates: Date values can be converted to timestamps or formatted text

• Tasks: Task values preserve their status and description semantics

• Arrays: Conversions are applied element-wise to array contents

Implementation Details

The Value enum forms the foundation of the AIMX runtime system. It supports:

• AIMX Grammar Compliance: All conversion rules match the AIMX specification
• Memory Efficiency: Uses Box<Value> for recursive data structures to avoid stack overflow
• Thread Safety: Can be safely used across threads in concurrent scenarios
• Serialization: Provides formatting methods for different display contexts

See Also

• Literal - Compile-time fixed value representations
• ExpressionLike - Trait for expression evaluation
• ContextLike - Evaluation context interface
• Value parsing - Function to parse value literals from text

Enums

Value

Runtime value representation during expression evaluation.

Functions

parse_value

Parse a value from input text.