Enum Literal

pub enum Literal {
    Empty,
    Bool(bool),
    Date(DateTime),
    Number(f64),
    Task(Option<bool>, String),
    Text(String),
}

Represents a literal value in the AIM expression grammar.

The Literal enum encapsulates all fundamental value types that can appear directly in AIM expressions, without requiring evaluation. Literals form the basis of the type system and provide the primary mechanism for type conversion and promotion throughout the expression evaluation pipeline.

Literal Variants

Each variant represents a specific data type with its own semantics:

• Empty - Represents an empty or null value. Used as a placeholder when no meaningful value is present or appropriate. This variant has special handling in comparison operations and type conversion.

• Bool(bool) - Boolean values, representing logical true/false states. Booleans have straightforward truthiness semantics and can be converted to numbers (1/0) or text (“true”/“false”) as needed.

• Date(DateTime) - Date and time values using the jiff crate’s DateTime type. Dates support conversion from Unix timestamps (numbers) and ISO 8601-style date strings while maintaining timezone awareness.

• Number(f64) - 64-bit floating point numbers. The primary numeric type used throughout AIMX, supporting arithmetic operations, mathematical functions, and various conversion contexts.

• Task(Option<bool>, String) - Task primitives with optional status and description text. Tasks are a unique semantic type in AIMX that represent work items in agentic workflows. Status can be Some(true) (completed), Some(false) (failed), or None (pending).

• Text(String) - UTF-8 string values. Text literals support the full Unicode character set and provide comprehensive string manipulation capabilities through built-in functions.

Type System Integration

Literals implement comprehensive type checking and conversion capabilities:

• Type Matching: The Literal::is_type method checks compatibility with Typedef
• Type Resolution: The Literal::get_type method returns the literal’s type
• Type Conversion: Various as_* methods handle type promotion
• Type Casting: The Literal::as_type method converts to match another literal’s type

Operator Implementations

The Literal type implements several important traits:

• PartialEq and Eq - Equality comparison for all literal types
• PartialOrd and Ord - Consistent ordering across different literal types
• ExpressionLike - Integration with the expression evaluation system
• Display - Human-readable string representation

Examples

Creating Literals

use aimx::literal::Literal;

// Using constructor functions
let bool_lit = Literal::from_bool(true);
let number_lit = Literal::from_number(42.5);
let text_lit = Literal::from_text("hello".to_string());

// Direct enum construction
let task_lit = Literal::Task(Some(true), "Completed task".to_string());
let empty_lit = Literal::Empty;

Type Conversion

use aimx::literal::Literal;

let number = Literal::from_number(42.0);
 
// Convert number to text
let as_text = number.clone().as_text().unwrap();
assert_eq!(as_text.to_string(), "42");
 
// Convert number to boolean (non-zero is true)
let as_bool = number.as_bool();
assert!(as_bool.to_bool());

Type Checking

use aimx::literal::Literal;
use aimx::typedef::Typedef;

let date_lit = Literal::Date(jiff::civil::DateTime::new(2023, 1, 1, 0, 0, 0, 0).unwrap());
 
assert!(date_lit.is_date());
assert!(date_lit.is_type(&Typedef::Date));
assert!(date_lit.is_type(&Typedef::Any));

let date_type = date_lit.get_type().unwrap();
assert_eq!(date_type, Typedef::Date);

See Also

• Typedef - The type definition system used for type checking
• Value - The runtime value representation that wraps literals
• parse_literal - Function for parsing literal values from strings

Variants

Empty

Represents an empty or null value.

Empty literals are used when no meaningful value is available or appropriate. They have special behavior in comparisons and type conversions:

• Empty compared to empty text is considered equal
• Cannot be converted to most specific types except boolean (false)
• Used as default values in various contexts

Bool(bool)

A boolean value representing logical true or false.

Boolean literals participate in logical operations and can be converted to numbers (1 for true, 0 for false) or text (“true”/“false”).

Date(DateTime)

A date and time value using the jiff crate’s DateTime type.

Date literals support comprehensive date/time operations including date arithmetic, formatting, and timezone-aware operations.

Number(f64)

A 64-bit floating point number.

Number literals are the primary numeric type in AIMX, supporting mathematical operations, functions, and various numeric conversions.

Task(Option<bool>, String)

A task primitive with optional status and description text.

Tasks are a semantic type unique to AIMX, representing work items in agentic workflows. The status can be:

• Some(true) - Completed task
• Some(false) - Failed task
• None - Pending task

Tasks have special numeric semantics: completed=1, failed=-1, pending=0.

Text(String)

A UTF-8 string value.

Text literals support the full Unicode character set and provide comprehensive string manipulation through built-in functions.

Implementations

impl Literal

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

Check if this literal matches the specified type.

Arguments

• typedef - The type definition to check against

Returns

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

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

Get the type of this literal.

Returns

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

pub fn as_type(self, literal: &Literal) -> Result<Literal>

Convert this literal to match the type of another literal.

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

Arguments

• literal - The reference literal whose type determines the conversion

Returns

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

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

pub fn is_empty(&self) -> bool

Check if this literal is empty.

pub fn is_bool(&self) -> bool

Check if this literal represents a boolean value.

pub fn from_bool(b: bool) -> Self

Create a boolean literal from a boolean value.

pub fn as_bool(self) -> Literal

Convert this literal to a boolean representation.

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

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

This function provides an implicit error free conversion from any literal to bool specifically for the conditional ternary operator making a type safe error free check possible.

e.g. user.birthday ? user.birthday : _

pub fn to_bool(&self) -> bool

Extract a boolean value from this literal.

This is a convenience method for when you specifically need a bool value.

pub fn is_date(&self) -> bool

Check if this literal represents a date value.

pub fn from_date(d: DateTime) -> Self

Create a date literal from a DateTime value.

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

Convert this literal to a date representation.

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

• Boolean: true becomes Unix epoch + 1 second, false becomes Unix epoch
• Number: Interpreted as Unix timestamp
• Text: Parsed as date if possible
• Task: Text component parsed as date if possible

pub fn is_number(&self) -> bool

Check if this literal represents a number value.

pub fn from_number(n: f64) -> Self

Create a number literal from an f64 value.

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

Convert this literal to a number representation.

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

• Boolean: false becomes 0, true becomes 1
• Date: Converted to Unix timestamp
• Text: Parsed as number if it represents a valid numeric literal
• Task: Status determines value (true=1, false=-1, none=0)

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

Extract a numeric value from this literal.

This is a convenience method for when you specifically need a f64 number.

pub fn is_task(&self) -> bool

Check if this literal represents a task value.

pub fn from_task(status: Option<bool>, task: String) -> Self

Create a task literal from status and text.

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

Convert this literal to a task representation.

Converts the literal to a task according to the grammar’s conversion rules:

• 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

pub fn is_text(&self) -> bool

Check if this literal represents a text value.

pub fn from_text(t: String) -> Self

Create a text literal from a String.

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

Convert this literal to a text representation.

Converts the literal to text according to the grammar’s conversion rules:

• Boolean: “true” or “false”
• Date: Formatted as date string
• Number: Formatted as string
• Task: Text component of the task

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

Get a string representation of this literal’s type.

Trait Implementations

impl Clone for Literal

fn clone(&self) -> Literal

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Literal

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

Formats the value using the given formatter.

impl Display for Literal

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

Formats the value using the given formatter.

impl ExpressionLike for Literal

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

Evaluate the expression within the given context.

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

Write this expression to the provided writer.

fn to_sanitized(&self) -> String

Convert this expression to a sanitized string representation.

fn to_formula(&self) -> String

Convert this expression to a formula string representation.

impl Ord for Literal

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 Literal

fn eq(&self, other: &Literal) -> 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 Literal

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 Literal

impl StructuralPartialEq for Literal