Enum Value

pub enum Value {
    Empty,
    Errata(Errata),
    Literal(Literal),
    Array(Vec<Box<Value>>),
    Closure(Closure),
    Assignment(Reference),
    Format(Format),
    Eval(Eval),
    Node(Node),
}

Runtime value representation during expression evaluation.

This enum encapsulates all possible runtime values that can result from evaluating expressions in the AIMX language. Values are produced when expressions are evaluated within a context and represent the actual data that flows through the expression evaluation engine.

The Value type forms a tree-like structure where arrays can contain other values, allowing for nested and complex data representations. This is the primary data structure used throughout the evaluation phase of the expression engine.

Variants

• Empty - Represents an empty or uninitialized value, typically used as a placeholder or result of operations that return no meaningful data
• Errata(Errata) - Contains evaluation errors with detailed context information
• Literal(Literal) - A single literal value (boolean, number, text, date, or task)
• Array(Vec<Box<Value>>) - An array of values, allowing for collections of data
• Closure(Closure) - A first-class anonymous function for functional programming
• Assignment(Reference) - A variable reference used for workflow assignments
• Format(Format) - Inference output formatting data for agentic workflows
• Eval(Eval) - Inference evaluation data for agentic workflows
• Node(Node) - A reference to a workflow file or node

Type Hierarchy

The Value enum represents the runtime counterpart to the compile-time Typedef enum. While Typedef represents type definitions, Value represents actual runtime data that conforms to those types.

Examples

Creating Values

use aimx::{Value, Literal};

// Creating different value types
let empty = Value::Empty;
let number = Value::Literal(Literal::from_number(42.0));
let text = Value::Literal(Literal::from_text("Hello".to_string()));
let array = Value::Array(vec![
    Box::new(Value::Literal(Literal::from_number(1.0))),
    Box::new(Value::Literal(Literal::from_number(2.0))),
    Box::new(Value::Literal(Literal::from_number(3.0))),
]);

// Type checking
assert!(empty.is_empty());
assert!(number.is_number());
assert!(text.is_text());
assert!(array.is_array());

// Converting between types
let text_from_number = number.clone().as_text().unwrap();
assert!(text_from_number.is_text());

Using Values in Workflow Context

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

let mut context = aimx::Context::new();
 
// Use assignment references for inference results
let assignment = Value::Assignment(aimx::Reference::new("_result"));
 
// Use closure for functional programming (simplified example)
// In practice, closures are parsed from expressions like "x => x * 2"

Type Conversions

Values can be converted between different types using the as_* methods:

use aimx::{Value, Literal};

let value = Value::Literal(Literal::from_number(42.0));
let as_text = value.clone().as_text().unwrap();
assert!(as_text.is_text());
 
let as_bool = value.as_bool();
assert!(as_bool.is_bool());

Implementation Notes

• Memory Management: Arrays use Box<Value> to avoid infinite recursion and stack overflow
• Error Handling: The Errata variant captures detailed error information for debugging
• Workflow Integration: Special variants like Node, Format, and Eval support agentic workflows
• Type Safety: All conversion methods return Result types to handle conversion failures gracefully

See Also

• Literal - Compile-time literal value representation
• Typedef - Type definition system
• ExpressionLike - Trait for expression evaluation
• ContextLike - Evaluation context interface

Variants

Empty

Errata(Errata)

Literal(Literal)

Array(Vec<Box<Value>>)

Closure(Closure)

Assignment(Reference)

Format(Format)

Eval(Eval)

Node(Node)

Implementations

impl Value

pub fn from_number(number: f64) -> Value

Create a Value from a number.

This is a convenience method for creating number values.

Arguments

• number - The numeric value

Examples

use aimx::Value;

let number_value = Value::from_number(42.0);
assert!(number_value.is_number());

pub fn is_of_type(&self, typedef: &Typedef) -> bool

Check if this value of the specified type definition.

This method determines whether this value conforms to the specified type definition. For arrays, it checks if the first element (if any) matches the type. For literals, it checks if the literal matches the type.

Arguments

• typedef - The type definition to check against

Returns

Returns true if this value matches the specified type, false otherwise.

Examples

use aimx::{Value, Literal, Typedef};

let number_value = Value::Literal(Literal::from_number(42.0));
assert!(number_value.is_of_type(&Typedef::Number));

let text_value = Value::Literal(Literal::from_text("Hello".to_string()));
assert!(text_value.is_of_type(&Typedef::Text));

let array_value = Value::Array(vec![
    Box::new(Value::Literal(Literal::from_number(1.0))),
    Box::new(Value::Literal(Literal::from_number(2.0))),
]);
assert!(array_value.is_of_type(&Typedef::Number));

pub fn is_actual_type(&self, typedef: &Typedef) -> bool

Check if this value matches the actual type definition, considering nested arrays.

This method provides a more precise type checking than is_of_type by properly handling nested array structures and ensuring the actual type matches the definition.

Arguments

• typedef - The type definition to check against

Returns

Returns true if this value’s actual type matches the specified type definition, false otherwise.

pub fn get_type(&self) -> Result<Typedef>

Get the type of this value.

Returns

Returns a Result<Typedef> containing the type of this value, or an error if this is an Empty value.

pub fn as_type(self, value: &Value) -> Result<Value>

Convert this value to match the type of another value.

This method performs type conversion according to the AIMX grammar’s type promotion rules, converting this value to match the type of the provided reference value.

Type conversion follows these rules:

• If the reference value is a Bool, converts this value to boolean
• If the reference value is a Date, converts this value to date
• If the reference value is a Number, converts this value to number
• If the reference value is a Task, converts this value to task
• If the reference value is Text, converts this value to text

Arguments

• value - The reference value whose type determines the conversion

Returns

Returns a Result<Value> containing the converted value or an error if conversion is not possible (e.g., trying to convert Empty to a specific type).

Examples

use aimx::{Value, Literal};

let number_value = Value::Literal(Literal::from_number(42.0));
let text_reference = Value::Literal(Literal::from_text("example".to_string()));

// Convert number to text
let converted = number_value.clone().as_type(&text_reference).unwrap();
assert!(converted.is_text());

let bool_reference = Value::Literal(Literal::from_bool(true));
// Convert number to boolean
let converted = number_value.as_type(&bool_reference).unwrap();
assert!(converted.is_bool());

pub fn to_type(self, typedef: &Typedef) -> Result<Value>

Convert this value to a specific type definition.

This method performs type conversion according to the AIMX grammar’s type promotion rules, converting this value to match the specified type definition.

Arguments

• typedef - The type definition to convert to

Returns

Returns a Result<Value> containing the converted value or an error if conversion is not possible.

Type Conversion Rules

The conversion follows these rules:

• Any: Returns the value unchanged
• Array: Converts non-arrays to single-element arrays
• Literal types: Converts values to the specified literal type
• Array types: Converts arrays to the specified element type
• Closure: Only allows conversion if already a closure

Examples

use aimx::{Value, Literal, Typedef};

let number_value = Value::Literal(Literal::from_number(42.0));
 
// Convert to text
let text_value = number_value.clone().to_type(&Typedef::Text).unwrap();
assert!(text_value.is_text());
 
// Convert to array
let array_value = number_value.to_type(&Typedef::NumberArray).unwrap();
assert!(array_value.is_array());

pub fn is_empty(&self) -> bool

Check if this value is empty.

Returns true if this value is the Empty variant, false otherwise.

Examples

use aimx::Value;

let empty_value = Value::Empty;
let non_empty_value = Value::Literal(aimx::Literal::from_number(42.0));

assert!(empty_value.is_empty());
assert!(!non_empty_value.is_empty());

pub fn has_error(&self) -> bool

Check if this value contains an error.

Returns true if this value represents an error condition, false otherwise.

pub fn has_errata(&self) -> bool

Check if this value contains an error (alias for has_error).

Returns true if this value represents an error condition, false otherwise.

pub fn is_literal(&self) -> bool

Check if this value is a literal.

Returns true if this value is the Literal variant, false otherwise. This includes all scalar types: booleans, numbers, text, dates, and tasks.

Examples

use aimx::{Value, Literal};

let literal_value = Value::Literal(Literal::from_number(42.0));
let array_value = Value::Array(vec![]);
let empty_value = Value::Empty;

assert!(literal_value.is_literal());
assert!(!array_value.is_literal());
assert!(!empty_value.is_literal());

pub fn is_constant(&self) -> bool

Check if this value is constant (immutable).

Returns true if this value represents a constant value that cannot be modified during evaluation, false otherwise.

pub fn to_literal(&self) -> &Literal

Get a reference to the literal representation of this value.

Returns a reference to a Literal representing this value’s type and content:

• For literal values, returns a reference to the embedded literal
• For arrays, returns the literal representation of the last element or Literal::Empty for empty arrays
• For all other value types, returns Literal::Empty

This method is useful for type checking and introspection, as it provides access to the underlying literal type without consuming the value.

Examples

use aimx::{Value, Literal};

let literal_value = Value::Literal(Literal::from_number(42.0));
assert!(literal_value.to_literal().is_number());

let array_value = Value::Array(vec![
    Box::new(Value::Literal(Literal::from_text("first".to_string()))),
    Box::new(Value::Literal(Literal::from_text("last".to_string()))),
]);
assert!(array_value.to_literal().is_text());

let empty_value = Value::Empty;
assert!(empty_value.to_literal().is_empty());

pub fn as_literal(self) -> Value

Convert this value to its literal representation.

This method consumes the value and returns the underlying literal representation:

• For literal values, returns the literal itself
• For arrays, returns the last element or Value::Empty for empty arrays
• For all other value types, returns Value::Empty

Examples

use aimx::{Value, Literal};

let literal_value = Value::Literal(Literal::from_number(42.0));
let literal = literal_value.as_literal();
assert!(literal.is_literal());

let array_value = Value::Array(vec![
    Box::new(Value::Literal(Literal::from_text("first".to_string()))),
    Box::new(Value::Literal(Literal::from_text("last".to_string()))),
]);
let literal = array_value.as_literal();
assert!(literal.is_literal());

let empty_value = Value::Empty;
let literal = empty_value.as_literal();
assert!(literal.is_empty());

pub fn is_array(&self) -> bool

Check if this value is an array.

Returns true if this value is the Array variant, false otherwise.

Examples

use aimx::{Value, Literal};

let array_value = Value::Array(vec![]);
let literal_value = Value::Literal(Literal::from_number(42.0));
let empty_value = Value::Empty;

assert!(array_value.is_array());
assert!(!literal_value.is_array());
assert!(!empty_value.is_array());

pub fn as_array(self) -> Value

Convert this value to an array representation.

If the value is already an array or empty, returns it unchanged. If the value is a literal, wraps it in a single-element array. Otherwise, returns an empty value.

pub fn is_bool(&self) -> bool

Check if this value represents a boolean.

Returns true if this value is a literal boolean, false otherwise.

Examples

See Value::as_bool for examples of boolean conversion behavior.

pub fn as_bool(self) -> Value

Convert this value to a boolean representation.

Performs type conversion to boolean according to the AIMX grammar’s truthiness rules:

• Empty values: Always false
• Numbers: 0 is false, non-zero is true
• Text: Empty string is false, non-empty is true
• Dates: Always true (they exist)
• Arrays: Empty array is false, non-empty is true
• Tasks: Status determines value, no status is false

Examples

use aimx::{Value, Literal};

let number_zero = Value::Literal(Literal::from_number(0.0));
let as_bool = number_zero.as_bool();
// Zero converts to false
assert!(!as_bool.to_literal().to_bool());

let number_non_zero = Value::Literal(Literal::from_number(42.0));
let as_bool = number_non_zero.as_bool();
// Non-zero converts to true
assert!(as_bool.to_literal().to_bool());

let empty_text = Value::Literal(Literal::from_text("".to_string()));
let as_bool = empty_text.as_bool();
// Empty string converts to false
assert!(!as_bool.to_literal().to_bool());

pub fn is_date(&self) -> bool

Check if this value represents a date.

Returns true if this value is a literal date, false otherwise.

Examples

use aimx::{Value, Literal};

let date_value = Value::Literal(Literal::Date(jiff::civil::DateTime::new(2023, 1, 1, 0, 0, 0, 0).unwrap()));
let number_value = Value::Literal(Literal::from_number(42.0));

assert!(date_value.is_date());
assert!(!number_value.is_date());

pub fn as_date(self) -> Result<Value>

Convert this value to a date representation.

Attempts to convert the value to a date according to the AIMX grammar’s conversion rules:

• Empty values: Remain empty (no conversion needed)
• Dates: No conversion needed
• Text: Parsed as date if possible (e.g., “2023-01-01”)
• Number: Interpreted as Unix timestamp
• Boolean: true becomes Unix epoch + 1 second, false becomes Unix epoch
• Task: Text component parsed as date if possible

Returns

Returns a Result<Value> containing the converted date value or an error if conversion is not possible.

Examples

use aimx::{Value, Literal};

let text_date = Value::Literal(Literal::from_text("2023-01-01".to_string()));
let as_date = text_date.as_date().unwrap();
assert!(as_date.is_date());

let number_timestamp = Value::Literal(Literal::from_number(1672531200.0)); // 2023-01-01 UTC
let as_date = number_timestamp.as_date().unwrap();
assert!(as_date.is_date());

pub fn is_number(&self) -> bool

Check if this value represents a number.

Returns true if this value is a literal number, false otherwise.

Examples

use aimx::{Value, Literal};

let number_value = Value::Literal(Literal::from_number(42.0));
let text_value = Value::Literal(Literal::from_text("hello".to_string()));

assert!(number_value.is_number());
assert!(!text_value.is_number());

pub fn as_number(self) -> Result<Value>

Convert this value to a number representation.

Attempts to convert the value to a number according to the AIMX grammar’s conversion rules:

• Empty values: Remain empty (no conversion needed)
• Numbers: No conversion needed
• Text: Parsed as number if it represents a valid numeric literal (e.g., “42”, “3.14”)
• Boolean: false becomes 0, true becomes 1
• Date: Converted to Unix timestamp
• Task: Status determines value (true=1, false=-1, none=0)

Returns

Returns a Result<Value> containing the converted number value or an error if conversion is not possible.

Examples

use aimx::{Value, Literal};

let text_number = Value::Literal(Literal::from_text("42".to_string()));
let as_number = text_number.as_number().unwrap();
assert!(as_number.is_number());

let bool_true = Value::Literal(Literal::from_bool(true));
let as_number = bool_true.as_number().unwrap();
// true converts to 1
assert_eq!(as_number.to_literal().to_number().unwrap(), 1.0);

pub fn to_number(&self) -> Result<f64>

Extract a numeric value from this value.

This is a convenience method for when you specifically need a f64 number. It’s particularly useful for arithmetic operations and mathematical functions.

Returns

Returns a Result<f64> containing the numeric value or an error if:

• The value is empty
• The value is an array with no elements
• The underlying literal cannot be converted to a number

Examples

use aimx::{Value, Literal};

let number_value = Value::Literal(Literal::from_number(42.5));
let num = number_value.to_number().unwrap();
assert_eq!(num, 42.5);

let array_value = Value::Array(vec![
    Box::new(Value::Literal(Literal::from_number(10.0))),
    Box::new(Value::Literal(Literal::from_number(20.0))),
]);
let num = array_value.to_number().unwrap();
// For arrays, gets the last element's number
assert_eq!(num, 20.0);

pub fn is_task(&self) -> bool

Check if this value represents a task.

Returns true if this value is a literal task, false otherwise.

Examples

use aimx::{Value, Literal};

let task_value = Value::Literal(Literal::from_task(Some(true), "Completed task".to_string()));
let text_value = Value::Literal(Literal::from_text("Just text".to_string()));

assert!(task_value.is_task());
assert!(!text_value.is_task());

pub fn as_task(self) -> Result<Value>

Convert this value to a task representation.

Attempts to convert the value to a task according to the AIMX grammar’s conversion rules:

• Empty values: Remain empty (no conversion needed)
• Tasks: No conversion needed
• Boolean: Status becomes the boolean value, text becomes “true”/“false”
• Date: No status, text becomes date string
• Number: Status based on sign (positive=true, negative=false, zero=none), text becomes number string
• Text: No status, text remains the same

Returns

Returns a Result<Value> containing the converted task value or an error if conversion is not possible.

Examples

use aimx::{Value, Literal};

let bool_true = Value::Literal(Literal::from_bool(true));
let as_task = bool_true.as_task().unwrap();
assert!(as_task.is_task());

let text_value = Value::Literal(Literal::from_text("Pending task".to_string()));
let as_task = text_value.as_task().unwrap();
// Text converts to task with no status
assert_eq!(as_task.to_literal().to_string(), "[ ] Pending task");

pub fn is_text(&self) -> bool

Check if this value represents text.

Returns true if this value is a literal text, false otherwise.

Examples

use aimx::{Value, Literal};

let text_value = Value::Literal(Literal::from_text("Hello".to_string()));
let number_value = Value::Literal(Literal::from_number(42.0));

assert!(text_value.is_text());
assert!(!number_value.is_text());

pub fn as_text(self) -> Result<Value>

Convert this value to a text representation.

Converts the value to text according to the AIMX grammar’s conversion rules:

• Empty values: Remain empty (no conversion needed)
• Text: No conversion needed
• Boolean: “true” or “false”
• Date: Formatted as ISO 8601 date string (e.g., “2023-01-01T00:00:00.000”)
• Number: Formatted as string (e.g., “42”, “3.14”)
• Task: Text component of the task (status is preserved in the Value but not in the text conversion)

Returns

Returns a Result<Value> containing the converted text value or an error if conversion is not possible.

Examples

use aimx::{Value, Literal};

let number_value = Value::Literal(Literal::from_number(42.0));
let as_text = number_value.as_text().unwrap();
assert!(as_text.is_text());
assert_eq!(as_text.to_literal().to_string(), "42");

let bool_true = Value::Literal(Literal::from_bool(true));
let as_text = bool_true.as_text().unwrap();
assert_eq!(as_text.to_literal().to_string(), "true");

pub fn is_closure(&self) -> bool

Check if this value represents a closure.

Returns true if this value is a closure, false otherwise.

pub fn invoke(&self, context: &mut dyn ContextLike) -> Result<Value>

Invoke this value as a closure.

If this value is a closure, invokes it with the given context. Otherwise, returns an error.

Arguments

• context - The evaluation context to use for invocation

Returns

Returns a Result<Value> containing the result of closure invocation or an error if this value is not a closure.

pub fn is_format(&self) -> bool

Check if this value represents a format.

Returns true if this value is a format, false otherwise.

pub fn is_eval(&self) -> bool

Check if this value represents an eval.

Returns true if this value is an eval, false otherwise.

pub fn is_node(&self) -> bool

Check if this value represents a node.

Returns true if this value is a node, false otherwise.

pub fn type_as_string(&self) -> &'static str

Get a string representation of this value’s type. Used to provide type information in error messages.

Returns a string indicating the type of this value based on its underlying literal representation. Possible return values are: “Empty”, “Error”, “Bool”, “Date”, “Number”, “Task”, “Text”, “Closure”, “Node”.

Examples

use aimx::{Value, Literal};

let number_value = Value::Literal(Literal::from_number(42.0));
assert_eq!(number_value.type_as_string(), "Number");

let text_value = Value::Literal(Literal::from_text("Hello".to_string()));
assert_eq!(text_value.type_as_string(), "Text");

let array_value = Value::Array(vec![
    Box::new(Value::Literal(Literal::from_number(1.0))),
]);
// For arrays, gets the type of the last element
assert_eq!(array_value.type_as_string(), "Number");

pub fn to_pretty(&self, prefix: Prefix) -> String

Convert value to string with specified prefix, for pretty printing.

This method formats the value for display with the specified prefix style. It’s primarily used for generating human-readable output with appropriate indentation and formatting.

Arguments

• prefix - The prefix style to use for formatting (None, Unordered, Ordered)

Returns

Returns a formatted string representation of the value.

Examples

use aimx::{Value, Literal, writer::Prefix};

let array_value = Value::Array(vec![
    Box::new(Value::Literal(Literal::from_text("first".to_string()))),
    Box::new(Value::Literal(Literal::from_text("second".to_string()))),
]);

let formatted = array_value.to_pretty(Prefix::Unordered);
// Would produce formatted output with bullet points

Trait Implementations

impl Clone for Value

fn clone(&self) -> Value

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Value

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Value

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Format this value for display using the default string representation.

This implementation uses the stringizer writer mode to produce a human-readable representation of the value. For arrays, this will include proper formatting with newlines and indentation where appropriate.

Arguments

• f - The formatter to write to

Returns

A fmt::Result indicating success or failure of the formatting operation.

impl ExpressionLike for Value

fn write(&self, writer: &mut Writer)

Write this value to the provided writer using the appropriate formatting.

This implementation delegates to the writer’s print_value method, which handles the formatting based on the writer’s mode (string, sanitized, formula).

Arguments

• writer - The writer to write to

fn to_sanitized(&self) -> String

Convert this value to a sanitized string representation.

This method produces a string with special characters escaped to make it safe for various contexts. Useful for generating JSON-compatible or safely quoted output.

Returns

A sanitized string representation of this value.

fn to_formula(&self) -> String

Convert this value to a formula string representation.

This method produces a string with proper quoting and escaping for use in formulas. Useful for generating round-trippable representations that can be parsed back into values.

Returns

A formula string representation of this value.

fn evaluate(&self, _context: &mut dyn ContextLike) -> Result<Value>

Evaluate the expression within the given context.

impl From<DateTime> for Value

fn from(value: DateTime) -> Self

Converts to this type from the input type.

impl From<String> for Value

fn from(value: String) -> Self

Converts to this type from the input type.

impl From<Vec<DateTime>> for Value

fn from(value: Vec<DateTime>) -> Self

Converts to this type from the input type.

impl From<Vec<String>> for Value

fn from(value: Vec<String>) -> Self

Converts to this type from the input type.

impl From<Vec<bool>> for Value

fn from(value: Vec<bool>) -> Self

Converts to this type from the input type.

impl From<Vec<f64>> for Value

fn from(value: Vec<f64>) -> Self

Converts to this type from the input type.

impl From<bool> for Value

fn from(value: bool) -> Self

Converts to this type from the input type.

impl From<f64> for Value

fn from(value: f64) -> Self

Converts to this type from the input type.

impl Ord for Value

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Value

fn eq(&self, other: &Value) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Value

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Eq for Value

impl StructuralPartialEq for Value