Enum Cell

Source

pub enum Cell {
    Empty,
    Comment {
        comment: Arc<str>,
    },
    Errata {
        identifier: Arc<str>,
        typedef: Arc<str>,
        reason: Arc<str>,
        formula: Arc<str>,
        location: Arc<str>,
    },
    Node {
        identifier: Arc<str>,
        value: Arc<str>,
    },
    Format {
        identifier: Arc<str>,
        instruction: Arc<str>,
        template: Arc<str>,
        examples: Arc<Vec<Arc<str>>>,
    },
    Branch {
        identifier: Arc<str>,
        condition: Arc<str>,
        target: Arc<str>,
    },
    Retry {
        identifier: Arc<str>,
        count: u32,
        condition: Arc<str>,
        target: Arc<str>,
    },
    Formula {
        identifier: Arc<str>,
        typedef: Arc<str>,
        formula: Arc<str>,
        value: Arc<str>,
    },
    Result {
        identifier: Arc<str>,
        typedef: Arc<str>,
        value: Arc<str>,
    },
}

Variants§

§

Empty

§

Comment

Fields

§comment: Arc<str>

§

Errata

Fields

§identifier: Arc<str>

§typedef: Arc<str>

§reason: Arc<str>

§formula: Arc<str>

§location: Arc<str>

§

Node

Fields

§identifier: Arc<str>

§value: Arc<str>

§

Format

Fields

§identifier: Arc<str>

§instruction: Arc<str>

§template: Arc<str>

§examples: Arc<Vec<Arc<str>>>

§

Branch

Fields

§identifier: Arc<str>

§condition: Arc<str>

§target: Arc<str>

§

Retry

Fields

§identifier: Arc<str>

§count: u32

§condition: Arc<str>

§target: Arc<str>

§

Formula

Fields

§identifier: Arc<str>

§typedef: Arc<str>

§formula: Arc<str>

§value: Arc<str>

§

Result

Fields

§identifier: Arc<str>

§typedef: Arc<str>

§value: Arc<str>

Implementations§

Source §

impl Cell

Source

pub fn new(identifier: &str, typedef: &str, formula: &str, value: &str) -> Self

§Creates a new formula cell with predefined values for all fields.

§title: New

Creates a new formula cell with predefined values for all fields.

This function is primarily used for creating test cells with static formula definitions and existing values. It differs from workflow rule creation which typically starts blank and gets evaluated dynamically.

§Arguments

identifier - A string slice containing the unique identifier for the cell
typedef - A string slice specifying the type definition (e.g., “Number”, “Text”, “Bool”)
formula - A string slice containing the formula expression (can be empty)
value - A string slice containing the current computed value (can be empty)

§Returns

Returns a newly constructed Cell::Formula variant containing all specified parameters wrapped in Arc<str>.

§Behavior

Internally, new() performs the following operations:

Converts all string arguments to Arc<str> for efficient sharing
Constructs a Cell::Formula variant with the provided parameters
Returns the cell ready for immediate use

§Usage Pattern

use aimx::Cell;

// Create a basic formula cell
let cell = Cell::new("temperature", "Number", "celsius_to_fahrenheit(current_temp)", "");

// Create a cell with a computed value
let computed_cell = Cell::new("result", "Number", "5 * 8", "40");

// Create a static value cell (formula empty, value populated)
let static_cell = Cell::new("filename", "Text", "", "report.pdf");

§See Also

Cell::convert_row - Converts workflow rows to cell representations
Cell::convert_rule - Converts workflow rules to cell representations
Rule - The underlying workflow rule type

Source

pub fn convert_row(row: &Row) -> Self

§Converts a workflow row to a cell representation for API consumption.

§title: Convert row

Converts a workflow Row to a Cell representation for API consumption.

This function serves as the bridge between the internal workflow representation (Row) and the public API representation (Cell). It handles all Row variants and delegates to Cell::convert_rule() for rule-based rows.

§Arguments

row - A reference to a Row object containing workflow data

§Returns

Returns a Cell variant that represents the workflow row:

Cell::Empty for empty rows
Cell::Comment for comment rows
Delegates to Cell::convert_rule() for rule-based rows (Row::Rule and Row::Touched)

§Behavior

Internally, convert_row() performs the following operations:

Matches on the Row variant:
- Row::Empty → Returns Cell::Empty
- Row::Comment(comment) → Returns Cell::Comment with cloned comment
- Row::Rule(rule) or Row::Touched(rule) → Delegates to Cell::convert_rule(&rule)
The conversion preserves all workflow semantics while providing a clean API abstraction

§Usage Pattern

use aimx::{Cell, aim::Row};
use std::sync::Arc;
use aimx::aim::{Rule, Typedef};
use aimx::expressions::Expression;
use aimx::values::Value;

// Example: Convert an empty row
let empty_row = Row::Empty;
let empty_cell = Cell::convert_row(&empty_row);
assert!(empty_cell.is_empty());

// Example: Convert a comment row
let comment_row = Row::Comment(Arc::from("This is a comment"));
let comment_cell = Cell::convert_row(&comment_row);
assert!(comment_cell.is_comment());
assert_eq!(comment_cell.comment(), Some(Arc::from("This is a comment")));

// Example: Convert a rule row (delegates to convert_rule)
let rule = Rule::new(
    Arc::from("temperature"),
    Typedef::Number,
    Expression::Empty,
    Arc::new(Value::from_number(25.0))
);
let rule_row = Row::Rule(Arc::new(rule));
let rule_cell = Cell::convert_row(&rule_row);
assert!(rule_cell.is_formula());
assert_eq!(rule_cell.identifier(), Some(Arc::from("temperature")));

§API Integration

This function is primarily used internally by AIMX API methods that return Cell objects:

Aim::list() - Converts all workflow rows to cells
Aim::get_row() - Converts a specific row by index
Aim::clear_row() - Converts the cleared row
Aim::remove_row() - Converts the removed row
Aim::delete_cell() - Converts the deleted rule row

§See Also

Cell::convert_rule() - Converts individual rules to cells
Cell::convert_result() - Converts rows to result cells for inference output
Row - The internal workflow row representation

Source

pub fn convert_result(row: &Row) -> Self

§Converts a workflow row to a result cell representation for inference output.

§title: Convert result

Converts a workflow Row to a Cell::Result representation for inference output.

This function is specifically designed for converting workflow rows into result cells that represent the final evaluation outcome. Unlike Cell::convert_row(), which creates source-formula cells suitable for editing, this function creates result cells optimized for inference output display.

§Arguments

row - A reference to a Row object containing workflow data

§Returns

Returns a Cell variant optimized for result display:

Cell::Empty for empty rows
Cell::Comment for comment rows
Cell::Errata for error states (both rule value errors and expression errors)
Cell::Result for successful rule evaluations

§Behavior

Internally, convert_result() performs the following operations:

Matches on the Row variant:
- Row::Empty → Returns Cell::Empty
- Row::Comment(comment) → Returns Cell::Comment with cloned comment
- Row::Rule(rule) or Row::Touched(rule) → Processes rule content
For rule-based rows, handles error propagation:
- Checks if the rule is in an error state using rule.is_error()
- Extracts Value::Errata errors and converts to Cell::Errata
- Other error types are converted to Cell::Errata with appropriate messages
For successful evaluations:
- Creates Cell::Result with identifier, type definition, and evaluated value
- Uses rule.value().to_arc_str() to convert the evaluated value to string representation

§Key Differences from `convert_row()`

Feature	`convert_row()`	`convert_result()`
Purpose	API consumption and editing	Inference output display
Error Handling	Preserves source formula	Shows evaluated result
Cell Type	Formula cells with source	Result cells with values
Architecture	Breadth-first conversion (convert→rule→specific)	Depth-first conversion (convert→error→result)

§Usage Pattern

use aimx::{Cell, aim::Row};
use std::sync::Arc;
use aimx::aim::{Rule, Typedef};
use aimx::expressions::Expression;
use aimx::values::{Value, Errata};

// Example: Convert a successful rule evaluation
let rule = Rule::new(
    Arc::from("price"),
    Typedef::Number,
    Expression::Empty,
    Arc::new(Value::from_number(42.50))
);
let rule_row = Row::Rule(Arc::new(rule));
let result_cell = Cell::convert_result(&rule_row);
assert!(result_cell.is_result());
assert_eq!(result_cell.identifier(), Some(Arc::from("price")));
assert_eq!(result_cell.value(), Some(Arc::from("42.5")));

// Example: Convert a rule with evaluation error
let error = Errata::new_reason(Arc::from("Division by zero"));
let error_rule = Rule::new(
    Arc::from("calculation"),
    Typedef::Number,
    Expression::Empty,
    Arc::new(error)
);
let error_row = Row::Rule(Arc::new(error_rule));
let error_cell = Cell::convert_result(&error_row);
assert!(error_cell.is_error());
assert_eq!(error_cell.identifier(), Some(Arc::from("calculation")));
assert_eq!(error_cell.reason(), Some(Arc::from("Division by zero")));

// Example: Convert a comment row (same as convert_row)
let comment_row = Row::Comment(Arc::from("Quarterly results"));
let comment_cell = Cell::convert_result(&comment_row);
assert!(comment_cell.is_comment());
assert_eq!(comment_cell.comment(), Some(Arc::from("Quarterly results")));

§Error Propagation

This function follows AIMX’s error propagation model:

Rule errors (from rule.is_error()) are captured and converted to Cell::Errata
The error maintains the rule identifier and type definition for traceability
This allows error tracing from the final result back to the originating rule

§API Integration

This function is used internally by AIMX components that need to display inference results:

Inference engine final output formatting
Results API endpoint formatting
Debug and monitoring interfaces
Workflow execution visualization

§Performance Considerations

Since this function performs rule error checking and value conversion, it may involve:

Rule state inspection overhead
Value-to-string conversion for complex types
Error message extraction and formatting

However, it’s typically used in contexts where human-readable output is required, so this overhead is acceptable.

§See Also

Cell::convert_row() - Converts rows to editing-oriented cells
Cell::convert_rule() - Converts individual rules to cells
Row - The internal workflow row representation
Rule::is_error() - Determines if a rule is in error state
Value::Errata - Error representation in value system

Source

pub fn convert_rule(rule: &Rule) -> Self

§Converts a workflow rule to a cell representation for API consumption.

§title: Convert rule

Converts a workflow Rule to a Cell representation for API consumption.

This function is the core conversion logic that transforms internal rule representations into API-friendly cell variants. It handles all rule types including errors, nodes, special types like format/branch/retry, and generic formula rules.

§Arguments

rule - A reference to a Rule object containing workflow rule data

§Returns

Returns a Cell variant that represents the workflow rule:

Cell::Errata for rules with evaluation or expression errors
Cell::Node for node-type rules containing workflow references
Cell::Format for format-type rules with instructions and templates
Cell::Branch for branch-type workflow control rules
Cell::Retry for retry-type workflow control rules
Cell::Formula for standard formula-based rules

§Behavior

Internally, convert_rule() performs the following operations:

Error Checking Phase:
- Checks if the rule is in error state using rule.is_error()
- Extracts value errors from Value::Errata and converts to Cell::Errata
- Extracts expression errors from Expression::Errata and converts to Cell::Errata
Special Type Processing:
- Node Rules: Converts nodes to Cell::Node with identifier and string value
- Format Rules: Converts format specifications to Cell::Format with instruction, template, and examples
- Branch Rules: Converts branch control to Cell::Branch with condition and target
- Retry Rules: Converts retry control to Cell::Retry with count, condition, and target
Default Formula Conversion:
- Creates Cell::Formula with identifier, typedef, expression formula, and string value
- Uses rule.expression().to_formula() and rule.value().to_arc_str() for string representations

§Type Conversion Matrix

Rule Type	Cell Variant	Key Fields Converted
Error Rule	`Cell::Errata`	Identifier, type definition, error reason, formula, location
Node Rule	`Cell::Node`	Identifier, node value as string
Format Rule	`Cell::Format`	Identifier, instruction, template, examples
Branch Rule	`Cell::Branch`	Identifier, condition formula, target reference
Retry Rule	`Cell::Retry`	Identifier, count, condition formula, target reference
Generic Rule	`Cell::Formula`	Identifier, type definition, expression formula, value

§Usage Pattern

use aimx::{Cell, aim::Rule};
use std::sync::Arc;
use aimx::aim::{Typedef};
use aimx::expressions::Expression;
use aimx::values::{Value, Errata};

// Example: Convert a formula rule
let rule = Rule::new(
    Arc::from("temperature"),
    Typedef::Number,
    Expression::convert("25 + 10"),
    Arc::new(Value::from_number(35.0))
);
let formula_cell = Cell::convert_rule(&rule);
assert!(formula_cell.is_formula());
assert_eq!(formula_cell.identifier(), Some(Arc::from("temperature")));
assert_eq!(formula_cell.typedef(), Some(Arc::from("Number")));
// Note: The formula may be empty due to static evaluation

// Example: Convert an error rule
let errata_value = Errata::new_reason(Arc::from("Division by zero"));
let error_rule = Rule::new(
    Arc::from("calculation"),
    Typedef::Number,
    Expression::Empty,
    Arc::new(errata_value)
);
let error_cell = Cell::convert_rule(&error_rule);
assert!(error_cell.is_error());
assert_eq!(error_cell.reason(), Some(Arc::from("Division by zero")));

§Error Handling

This function converts AIMX’s error propagation model into Cell::Errata variants:

Value errors (from rule.value().is_error()) are captured with full error context
Expression errors (from rule.expression().is_error()) are similarly converted
Error cells preserve the original rule identifier and type definition for traceability
This maintains error tracing from API responses back to originating rules

§API Integration

This function is utilized by multiple AIMX API methods that expose rule data:

Aim::cell() - Gets a specific cell by reference
Aim::get_cell() - Gets a cell within a write context
Aim::list() - Internally calls Cell::convert_row() which delegates here
Various workflow navigation and inspection APIs

§Performance Considerations

Since this function performs type checks, error checking, and value conversion, it involves:

Multiple type-specific conditional branches
String conversion operations for formulas and values
Error context extraction and formatting

The complexity is justified by providing clean, type-aware API abstractions from internal representations.

§See Also

Cell::convert_row() - Converts rows by delegating to this function for rules
Cell::convert_result() - Converts rules to result-oriented cells for inference output
Rule - The internal workflow rule representation

Source

pub fn is_empty(&self) -> bool

§Checks whether a cell represents an empty workflow row.

§title: Is Empty

Checks whether a cell represents an empty workflow row.

This method determines if the cell is of type Cell::Empty, which represents a blank line or empty row in the workflow structure. Empty cells are typically used for formatting purposes or as placeholders.

§Returns

Returns true if the cell is an empty workflow row (Cell::Empty), otherwise returns false.

§Behavior

Internally, is_empty() performs a simple pattern match on the Cell enum:

Returns true only when the cell is Cell::Empty
Returns false for all other cell variants including comments, formulas, results, errors, etc.

§Usage Pattern

use aimx::Cell;

// Create an empty
let empty_cell = Cell::Empty;

// Test if the cell is empty
assert!(empty_cell.is_empty());

§API Integration

This method is commonly used to handle edge cases when working with cell results:

When deleting non-existent cells via the API, empty cells are returned
When iterating through workflow rows, empty cells indicate formatting breaks
In conditional logic for handling missing or deleted cells

§See Also

Cell - The main cell type containing various workflow representations
Cell::is_comment() - Checks if cell represents a comment
Cell::is_error() - Checks if cell represents an error

Source

pub fn is_comment(&self) -> bool

§Checks whether a cell represents a comment in the workflow.

§title: Is Comment

Checks whether a cell represents a comment in the workflow.

This method determines if the cell is of type Cell::Comment, which represents a comment line in the workflow structure. Comment cells are used to add explanatory text or documentation to workflows without affecting the workflow execution.

§Returns

Returns true if the cell is a comment (Cell::Comment), otherwise returns false.

§Behavior

Internally, is_comment() performs a simple pattern match on the Cell enum:

Returns true only when the cell is Cell::Comment { .. }
Returns false for all other cell variants including empty cells, formulas, results, errors, etc.

§Usage Pattern

use aimx::Cell;

// Create various cell types
let comment_cell = Cell::Comment { comment: std::sync::Arc::from("This is a workflow comment") };
let formula_cell = Cell::new("temperature", "Number", "32 + 25", "");
let empty_cell = Cell::Empty;

// Test for comment type
assert!(comment_cell.is_comment());
assert!(!formula_cell.is_comment());
assert!(!empty_cell.is_comment());

// Comments are often parsed from source files with '#' prefix
let parsed_line = "# This is a comment line";
// After parsing, this would become a Cell::Comment

§API Integration

This method is commonly used to filter or skip comment cells when processing workflow data:

When iterating through workflow rows, comment cells can be skipped during evaluation
In UI rendering, comment cells may be displayed differently from functional cells
During workflow validation, comments are typically ignored

§See Also

Cell - The main cell type containing various workflow representations
Cell::is_empty() - Checks if cell represents an empty row
Cell::is_error() - Checks if cell represents an error
Cell::comment() - Retrieves the comment text from a comment cell

Source

pub fn is_error(&self) -> bool

§Checks whether a cell represents an error state containing error information.

§title: is error

Checks whether a cell represents an error state containing error information.

§Returns

Returns true if the cell variant is Cell::Errata, which contains error details including identifier, type definition, reason, formula, and location. Returns false for all other cell variants.

§Usage Pattern

use aimx::Cell;

// Create a regular formula cell
let cell = Cell::new("test", "Number", "42", "42");
assert!(!cell.is_error());

// Cell::Errata contains error information
let errata_cell = Cell::Errata {
    identifier: "error_cell".into(),
    typedef: "Number".into(),
    reason: "Division by zero".into(),
    formula: "10 / 0".into(),
    location: "workspace/test.aim:5".into(),
};
assert!(errata_cell.is_error());

§See Also

Source

pub fn is_node(&self) -> bool

§Checks whether a cell represents a node in the workflow.

§title: Is Node

Checks whether a cell represents a node in the workflow.

This method determines if the cell is of type Cell::Node, which represents a workflow node reference. Node cells are used to reference child workflows within a parent workflow structure, enabling hierarchical organization of workflows.

§Returns

Returns true if the cell is a node (Cell::Node), otherwise returns false.

§Behavior

Internally, is_node() performs a simple pattern match on the Cell enum:

Returns true only when the cell is Cell::Node { .. }
Returns false for all other cell variants including empty cells, formulas, results, errors, comments, etc.

§Usage Pattern

use aimx::Cell;

// Create a node cell
let node_cell = Cell::Node {
    identifier: std::sync::Arc::from("child_workflow"),
    value: std::sync::Arc::from("active"),
};

// Create other cell types for comparison
let formula_cell = Cell::new("temperature", "Number", "32 + 25", "");
let empty_cell = Cell::Empty;

// Test for node type
assert!(node_cell.is_node());
assert!(!formula_cell.is_node());
assert!(!empty_cell.is_node());

// Node cells contain workflow references and their current state
if node_cell.is_node() {
    if let Some(identifier) = node_cell.identifier() {
        println!("Node identifier: {}", identifier);
    }
    if let Some(value) = node_cell.value() {
        println!("Node value: {}", value);
    }
}

§API Integration

This method is commonly used to:

Filter or identify node cells when processing workflow hierarchies
Distinguish between workflow references and computational cells during evaluation
UI rendering where nodes may be displayed differently from formula cells
Workflow validation to ensure proper hierarchical structure

§See Also

Cell - The main cell type containing various workflow representations
Cell::is_empty() - Checks if cell represents an empty row
Cell::is_formula() - Checks if cell represents a formula
Cell::is_result() - Checks if cell represents a result
Cell::identifier() - Retrieves the identifier from a cell
Cell::value() - Retrieves the value from a node or result cell

Source

pub fn is_format(&self) -> bool

§Checks whether a cell represents a format instruction in the workflow.

§title: Is Format

Checks whether a cell represents a format instruction in the workflow.

This method determines if the cell is of type Cell::Format, which represents a formatting instruction used for prompts or output schemas. Format cells contain structured information about how to format data, including an instruction, template, and examples.

Format cells are used to define formatting rules that can be applied during inference operations. They provide a structured way to specify how data should be formatted, making them useful for generating consistent output formats or defining prompt templates.

§Returns

Returns true if the cell is a format instruction (Cell::Format), otherwise returns false.

§Behavior

Internally, is_format() performs a simple pattern match on the Cell enum:

Returns true only when the cell is Cell::Format { .. }
Returns false for all other cell variants including empty cells, formulas, results, errors, comments, nodes, branches, and retries.

§Usage Pattern

use aimx::Cell;

// Create a format cell
let format_cell = Cell::Format {
    identifier: std::sync::Arc::from("output_format"),
    instruction: std::sync::Arc::from("Format the result as JSON"),
    template: std::sync::Arc::from("{{result}}"),
    examples: std::sync::Arc::new(vec![
        std::sync::Arc::from("{\"status\": \"success\", \"data\": $result}"),
        std::sync::Arc::from("{\"status\": \"error\", \"message\": $result}")
    ]),
};

// Create other cell types for comparison
let formula_cell = Cell::new("temperature", "Number", "32 + 25", "");
let empty_cell = Cell::Empty;
let node_cell = Cell::Node {
    identifier: std::sync::Arc::from("child_workflow"),
    value: std::sync::Arc::from("active"),
};

// Test for format type
assert!(format_cell.is_format());
assert!(!formula_cell.is_format());
assert!(!empty_cell.is_format());
assert!(!node_cell.is_format());

// Format cells contain formatting instructions and can be used to retrieve their components
if format_cell.is_format() {
    if let Some(identifier) = format_cell.identifier() {
        println!("Format identifier: {}", identifier);
    }
    if let Some(instruction) = format_cell.instruction() {
        println!("Format instruction: {}", instruction);
    }
    if let Some(template) = format_cell.template() {
        println!("Format template: {}", template);
    }
    
    if let Some(examples) = format_cell.examples() {
        println!("Format examples: {:?}", examples);
    }
}

§API Integration

This method is commonly used to:

Filter or identify format cells when processing workflow templates
Distinguish between formatting instructions and computational cells during evaluation
UI rendering where format cells may be displayed differently from formula cells
Workflow validation to ensure proper formatting rule structure
Inference pipeline setup where format cells define output schemas

§See Also

Cell - The main cell type containing various workflow representations
Cell::is_empty() - Checks if cell represents an empty row
Cell::is_formula() - Checks if cell represents a formula
Cell::is_result() - Checks if cell represents a result
Cell::is_node() - Checks if cell represents a node
Cell::instruction() - Retrieves the instruction from a format cell
Cell::template() - Retrieves the template from a format cell
Cell::examples() - Retrieves the examples from a format cell

Source

pub fn is_branch(&self) -> bool

§Checks whether a cell represents a branch instruction in the workflow.

§title: Is Branch

Checks whether a cell represents a branch instruction in the workflow.

This method determines if the cell is of type Cell::Branch, which represents a conditional branch that controls workflow execution flow. Branch cells contain a condition expression and a target reference that determines where execution should continue when the condition evaluates to true.

Branch cells are used to implement conditional logic in workflows, allowing different execution paths based on rule evaluations. They enable dynamic workflow behavior by testing conditions and redirecting execution flow accordingly when conditions are met.

§Returns

Returns true if the cell is a branch instruction (Cell::Branch), otherwise returns false.

§Behavior

Internally, is_branch() performs a simple pattern match on the Cell enum:

Returns true only when the cell is Cell::Branch { .. }
Returns false for all other cell variants including empty cells, formulas, results, errors, comments, nodes, formats, and retries.

§Usage Pattern

use aimx::Cell;
use std::sync::Arc;

// Create a branch cell
let branch_cell = Cell::Branch {
    identifier: Arc::from("decision_point"),
    condition: Arc::from("user.age > 18"),
    target: Arc::from("adult_workflow"),
};

// Create other cell types for comparison
let formula_cell = Cell::new("user", "Text", "\"John\"", "");
let empty_cell = Cell::Empty;
let retry_cell = Cell::Retry {
    identifier: Arc::from("retry_logic"),
    count: 3,
    condition: Arc::from("error_occurred"),
    target: Arc::from("fallback_node"),
};

// Test for branch type
assert!(branch_cell.is_branch());
assert!(!formula_cell.is_branch());
assert!(!empty_cell.is_branch());
assert!(!retry_cell.is_branch());

// Branch cells contain conditional logic and can be used to retrieve their components
if branch_cell.is_branch() {
    if let Some(identifier) = branch_cell.identifier() {
        println!("Branch identifier: {}", identifier);
    }
    if let Some(condition) = branch_cell.condition() {
        println!("Branch condition: {}", condition);
    }
    if let Some(target) = branch_cell.target() {
        println!("Branch target: {}", target);
    }
}

§API Integration

This method is commonly used to:

Filter or identify branch cells when processing workflow control flow
Distinguish between conditional branches and other workflow instructions during evaluation
UI rendering where branch cells may be displayed differently from computational cells
Workflow validation to ensure proper conditional logic structure
Execution engines that need to handle conditional branching

§See Also

Cell - The main cell type containing various workflow representations
Cell::is_empty() - Checks if cell represents an empty row
Cell::is_retry() - Checks if cell represents a retry instruction
Cell::is_formula() - Checks if cell represents a formula
Cell::condition() - Retrieves the condition from a branch cell
Cell::target() - Retrieves the target from a branch or retry cell

Source

pub fn is_retry(&self) -> bool

§Checks whether a cell represents a retry instruction in the workflow.

§title: Is Retry

Checks whether a cell represents a retry instruction in the workflow.

This method determines if the cell is of type Cell::Retry, which represents a retry mechanism that allows workflow execution to be attempted multiple times under certain conditions. Retry cells contain a retry count, a condition that triggers the retry, and a target reference for where to continue execution.

Retry cells are used to implement fault tolerance and resilience in workflows, allowing operations to be retried when they fail or when specific conditions are met. They enable robust workflow execution by providing automatic retry logic for error-prone operations. The retry mechanism works by evaluating the condition expression and, if true and the retry count is greater than zero, returning a branch to the target while decrementing the count.

§Returns

Returns true if the cell is a retry instruction (Cell::Retry), otherwise returns false.

§Behavior

Internally, is_retry() performs a simple pattern match on the Cell enum:

Returns true only when the cell is Cell::Retry { .. }
Returns false for all other cell variants including empty cells, formulas, results, errors, comments, nodes, formats, and branches.

§Usage Pattern

use aimx::Cell;
use std::sync::Arc;

// Create a retry cell with retry logic
let retry_cell = Cell::Retry {
    identifier: Arc::from("network_retry"),
    count: 3,
    condition: Arc::from("connection_failed"),
    target: Arc::from("retry_handler"),
};

// Test for retry type
assert!(retry_cell.is_retry());

// Extract retry-specific properties
if retry_cell.is_retry() {
    if let Some(identifier) = retry_cell.identifier() {
        println!("Retry identifier: {}", identifier);
    }
    println!("Retry count: {}", retry_cell.count().unwrap_or(0));
    if let Some(condition) = retry_cell.condition() {
        println!("Retry condition: {}", condition);
    }
    if let Some(target) = retry_cell.target() {
        println!("Retry target: {}", target);
    }
}

// Compare with other cell types
let formula_cell = Cell::new("calculation", "Number", "10 + 5", "");
let branch_cell = Cell::Branch {
    identifier: Arc::from("decision"),
    condition: Arc::from("x > 5"),
    target: Arc::from("alternative_path"),
};

assert!(!formula_cell.is_retry());
assert!(!branch_cell.is_retry());

§API Integration

This method is commonly used to:

Filter or identify retry cells when processing workflow resilience mechanisms
Distinguish between retry instructions and other workflow control structures during evaluation
UI rendering where retry cells may be displayed with special retry indicators
Workflow validation to ensure proper error handling and retry logic
Execution engines that need to implement retry mechanisms

When combined with other Cell methods, you can extract the complete retry configuration:

Use Cell::count() to get the remaining retry attempts
Use Cell::condition() to get the retry trigger condition
Use Cell::target() to get the workflow target for retry execution

§See Also

Cell - The main cell type containing various workflow representations
Cell::is_empty() - Checks if cell represents an empty row
Cell::is_branch() - Checks if cell represents a branch instruction
Cell::is_formula() - Checks if cell represents a formula
Cell::condition() - Retrieves the condition from a retry cell
Cell::target() - Retrieves the target from a branch or retry cell
Cell::count() - Retrieves the retry count from a retry cell

Source

pub fn is_formula(&self) -> bool

§Checks whether a cell represents a formula in the workflow.

§title: Is Formula

Checks whether a cell represents a formula in the workflow.

This method determines if the cell is of type Cell::Formula, which represents a computational formula that defines how to calculate a value. Formula cells are the primary computational elements in AIMX workflows and contain a type definition, a formula expression, and the computed value.

Formula cells are used to perform calculations, data transformations, and business logic within workflows. They can reference other cells, call functions, and perform complex operations. The formula field contains the expression that defines the computation, while the value field contains the current result of evaluating that expression.

Formula cells can represent either:

Dynamic formulas: Cells with a non-empty formula field that can be re-evaluated
Static values: Cells with an empty formula field that represent pre-computed results

§Returns

Returns true if the cell is a formula (Cell::Formula), otherwise returns false.

§Behavior

Internally, is_formula() performs a simple pattern match on the Cell enum:

Returns true only when the cell is Cell::Formula { .. }
Returns false for all other cell variants including empty cells, results, errors, comments, nodes, formats, branches, and retries.

This method does not inspect the contents of the formula field - it only checks the cell type. A formula cell with an empty formula field (representing static evaluation) will still return true.

§Usage Pattern

use aimx::Cell;
use std::sync::Arc;

// Create a formula cell using the convenience constructor
let formula_cell = Cell::new("temperature", "Number", "32 + 25", "57");

// Create other cell types for comparison
let result_cell = Cell::Result {
    identifier: Arc::from("final_result"),
    typedef: Arc::from("Number"),
    value: Arc::from("100"),
};
let empty_cell = Cell::Empty;
let node_cell = Cell::Node {
    identifier: Arc::from("child_workflow"),
    value: Arc::from("active"),
};

// Test for formula type
assert!(formula_cell.is_formula());
assert!(!result_cell.is_formula());
assert!(!empty_cell.is_formula());
assert!(!node_cell.is_formula());

// Formula cells contain computational logic and can be used to retrieve their components
if formula_cell.is_formula() {
    if let Some(identifier) = formula_cell.identifier() {
        println!("Formula identifier: {}", identifier);
    }
    if let Some(typedef) = formula_cell.typedef() {
        println!("Formula type: {}", typedef);
    }
    if let Some(formula) = formula_cell.formula() {
        println!("Formula expression: {}", formula);
    }
    if let Some(value) = formula_cell.value() {
        println!("Formula result: {}", value);
    }
}

// Handle both dynamic and static formula cells
let dynamic_formula = Cell::Formula {
    identifier: Arc::from("dynamic_calc"),
    typedef: Arc::from("Number"),
    formula: Arc::from("x + y"),
    value: Arc::from("10"),
};

let static_formula = Cell::Formula {
    identifier: Arc::from("static_value"),
    typedef: Arc::from("Text"),
    formula: Arc::from(""),  // Empty formula indicates static evaluation
    value: Arc::from("Hello World"),
};

assert!(dynamic_formula.is_formula());
assert!(static_formula.is_formula());  // Static formulas are still formulas

§API Integration

This method is commonly used to:

Filter or identify computational cells when processing workflow calculations
Distinguish between formulas and their results during workflow evaluation
UI rendering where formulas may be displayed differently from static values
Workflow validation to ensure proper computational structure
Code analysis tools that need to identify computational elements

When used with the AIMX API, formula cells are typically created using:

Cell::new() - Convenience constructor for formula cells
Cell::convert_rule() - Converts workflow rules to cell representations

§Static vs Dynamic Evaluation

Formula cells can represent two different evaluation patterns:

Dynamic Evaluation: Formula cells with non-empty formula fields represent expressions that can be re-evaluated when dependencies change.

Static Evaluation: Formula cells with empty formula fields represent pre-computed values that don’t need re-evaluation. This is an optimization used when the formula result is known at creation time.

Both patterns return true for is_formula() as they represent the same conceptual cell type.

§See Also

Cell - The main cell type containing various workflow representations
Cell::is_empty() - Checks if cell represents an empty row
Cell::is_result() - Checks if cell represents a result
Cell::is_format() - Checks if cell represents a format instruction
Cell::new() - Creates a new formula cell
Cell::typedef() - Retrieves the type definition from a formula cell
Cell::formula() - Retrieves the formula expression from a formula cell
Cell::value() - Retrieves the computed value from a formula cell
Cell::convert_rule() - Converts workflow rules to cell representations

Source

pub fn is_result(&self) -> bool

§Checks whether a cell represents a result in the workflow.

§title: Is Result

Checks whether a cell represents a computed result in the workflow.

This method determines if the cell is of type Cell::Result, which represents the final computed output of a workflow operation. Result cells contain the type definition and the evaluated value, typically representing the outcome of inference operations or workflow evaluations.

Result cells are created when workflows are evaluated and represent the final, computed values rather than the computational expressions themselves. They are distinct from formula cells which contain the expressions used to compute these results.

§Returns

Returns true if the cell is a result (Cell::Result), otherwise returns false.

§Behavior

Internally, is_result() performs a simple pattern match on the Cell enum:

Returns true only when the cell is Cell::Result { .. }
Returns false for all other cell variants including empty cells, formulas, errors, comments, nodes, formats, branches, and retries.

§Usage Pattern

Result cells are typically created through workflow evaluation rather than directly. Here’s how to work with them:

use aimx::{Aim, Cell, Reference};
use std::sync::Arc;

// Acquire workflow context
let reference = Reference::parse("inference.workflow").unwrap();
let handle = Aim::acquire(reference.clone()).unwrap();

// Add some computational cells
let formula_cell = Cell::new("calculation", "Number", "42 + 8", "");
Aim::append_or_update_cell(&handle, formula_cell).unwrap();
Aim::snapshot(&handle).unwrap();

// Get results - this creates Result cells from evaluated workflow
let results = Aim::results(reference.clone()).unwrap();

// Test for result type
for cell in results {
    if cell.is_result() {
        if let (Some(identifier), Some(value), Some(typedef)) = (cell.identifier(), cell.value(), cell.typedef()) {
            println!("Result: {} = {}", identifier, value);
            println!("Type: {}", typedef);
        }
    }
}

// Direct creation for testing
let result_cell = Cell::Result {
    identifier: Arc::from("final_output"),
    typedef: Arc::from("Text"),
    value: Arc::from("Workflow completed successfully"),
};

assert!(result_cell.is_result());

// Compare with other cell types
let formula_cell = Cell::new("temperature", "Number", "32 + 25", "57");
let empty_cell = Cell::Empty;

assert!(!formula_cell.is_result());
assert!(!empty_cell.is_result());

// Access result-specific properties
if result_cell.is_result() {
    if let Some(identifier) = result_cell.identifier() {
        println!("Result identifier: {}", identifier);
    }
    if let Some(typedef) = result_cell.typedef() {
        println!("Result type: {}", typedef);
    }
    if let Some(value) = result_cell.value() {
        println!("Result value: {}", value);
    }
}

// Make changes visible
Aim::release(&handle).unwrap();

§API Integration

This method is commonly used to:

Filter inference result cells when processing workflow outputs
Distinguish between computational formulas and final results during workflow evaluation
UI rendering where results may be displayed differently from computational cells
Workflow validation to ensure proper result handling
Inference pipelines where results represent the final computed output

Result cells are automatically created when workflows are evaluated and their results are retrieved. They represent the final, stable state of computed values rather than the expressions that generated them.

§See Also

Cell - The main cell type containing various workflow representations
Cell::is_empty() - Checks if cell represents an empty row
Cell::is_formula() - Checks if cell represents a formula
Cell::is_error() - Checks if cell represents an error state
Cell::convert_result() - Converts a workflow row to a result cell
Cell::typedef() - Retrieves the type definition from a result cell
Cell::value() - Retrieves the computed value from a result cell
Cell::Result - Retrieves inference results as result cells

Source

pub fn comment(&self) -> Option<Arc<str>>

§Retrieves the comment text from a comment cell, or an empty string for other cell types.

§title: Comment

This function retrieves the comment text from a cell if it represents a comment, otherwise returns an empty string.

The comment() method is used to extract the comment content from cells that are specifically comment cells. For all other cell types, it returns an empty string to indicate the absence of a comment.

§Arguments

This function takes no arguments.

§Returns

Returns an Arc<str> containing:

The comment text if the cell is a Cell::Comment
An empty string if the cell is any other type

§Behavior

The comment() function performs a simple pattern match on the cell variant:

If the cell is Cell::Comment, it returns the comment text
For all other cell types, it returns Value::empty_str()

§Usage Pattern

use aimx::{Cell, values::Value};
use std::sync::Arc;

// Create a comment cell
let comment_cell = Cell::Comment {
    comment: Arc::from("This is a workflow comment"),
};

// Extract the comment text
let comment_text = comment_cell.comment();
assert_eq!(comment_text, Some(Arc::from("This is a workflow comment")));

// For non-comment cells, returns None
let formula_cell = Cell::Formula {
    identifier: Arc::from("calc"),
    typedef: Arc::from("Number"),
    formula: Arc::from("1 + 1"),
    value: Arc::from("2"),
};

let empty_comment = formula_cell.comment();
assert_eq!(empty_comment, None);

§See Also

Cell::is_comment() - Check if a cell is a comment
Cell::Comment - The comment cell variant
Value::empty_str() - Empty string constant

Source

pub fn identifier(&self) -> Option<Arc<str>>

§Retrieves the identifier associated with a cell in the workflow.

§title: Identifier

This function retrieves the identifier associated with a cell in the workflow. The identifier serves as the unique name or key for the cell within its containing workflow.

§Returns

Returns a Arc<str> containing the cell’s identifier. For cells that don’t have an identifier (such as Empty or Comment cells), this function returns an empty string.

§Behavior

The identifier() function examines the cell’s variant and extracts the identifier field when available:

For Errata, Node, Format, Branch, Retry, Formula, and Result cells, it returns the stored identifier
For Empty and Comment cells, it returns an empty string since these cell types don’t contain identifiers

§Usage Pattern

use aimx::Cell;
use std::sync::Arc;

// Create a formula cell
let cell = Cell::new("my_formula", "Number", "42 * 2", "");

// Get the identifier
let id = cell.identifier();
assert_eq!(id, Some(Arc::from("my_formula")));

// For cells without identifiers, None is returned
let empty_cell = Cell::Empty;
let empty_id = empty_cell.identifier();
assert_eq!(empty_id, None);

§See Also

Cell::typedef() - Get the type definition of a cell
Cell::formula() - Get the formula expression of a cell
Cell::value() - Get the computed value of a cell
Cell::is_empty() - Check if a cell represents an empty row

Source

pub fn typedef(&self) -> Option<Arc<str>>

§Retrieves the type definition string associated with a cell in the workflow.

§title: Typedef

This method retrieves the type definition string associated with a cell in the workflow. The type definition indicates what kind of data the cell contains and follows the AIM type system.

§Returns

Returns an Arc<str> containing the type definition string for the cell. The return value depends on the cell variant:

For Errata, Formula, and Result cells: Returns the actual type definition (e.g., “Number”, “Text”, “Bool”)
For Node cells: Returns “Node”
For Format cells: Returns “Format”
For Branch cells: Returns “Branch”
For Retry cells: Returns “Retry”
For all other cell types: Returns an empty string

§Behavior

The typedef() method performs the following operations:

Matches against the cell variant to determine the appropriate type definition
For cells that store explicit type information (Errata, Formula, Result), returns the stored type definition
For special workflow constructs (Node, Format, Branch, Retry), returns the corresponding type name
For cells without meaningful type information (Empty, Comment), returns an empty string

§Usage Pattern

use aimx::{Cell, Reference, Aim};
use std::sync::Arc;

// Acquire workflow context
let reference = Reference::parse("foo.bar").unwrap();
let handle = Aim::acquire(reference.clone()).unwrap();

// Get a cell from the workflow
if let Some(cell) = Aim::get_cell(&handle, "my_cell").unwrap() {
    // Retrieve the type definition
    let type_def = cell.typedef();
    if let Some(type_str) = type_def {
        println!("Cell type: {}", type_str);
        
        // Use the type information for validation or processing
        match type_str.as_ref() {
            "Number" => println!("This is a numeric cell"),
            "Text" => println!("This is a text cell"),
            "Bool" => println!("This is a boolean cell"),
            _ => println!("Unknown or untyped cell"),
        }
    }
}

// Release the workflow handle
Aim::release(&handle).unwrap();

§See Also

Cell::identifier() - Retrieves the cell identifier
Cell::formula() - Retrieves the cell formula
Cell::value() - Retrieves the cell value

Source

pub fn reason(&self) -> Option<Arc<str>>

§Retrieves the error reason string from a cell that represents an error state.

§title: Reason

Retrieves the error reason string from a cell that represents an error state. For cells that don’t contain error information, this function returns an empty string.

§Returns

Returns a Arc<str> containing the error reason if the cell is an Errata variant, otherwise returns an empty string.

§Behavior

The reason() function examines the cell’s variant and extracts the error reason when available:

For Errata cells, it returns the stored error reason that describes what went wrong during expression parsing or evaluation
For all other cell types (Empty, Comment, Node, Format, Branch, Retry, Formula, and Result), it returns an empty string since these cells don’t contain error information

§Usage Pattern

use aimx::Cell;
use std::sync::Arc;

// Create an error cell with reason information
let error_cell = Cell::Errata {
    identifier: Arc::from("problematic_rule"),
    typedef: Arc::from("Number"),
    reason: Arc::from("Division by zero error"),
    formula: Arc::from("10 / 0"),
    location: Arc::from("rule:15"),
};

// Get the error reason
let error_reason = error_cell.reason();
assert_eq!(error_reason, Some(Arc::from("Division by zero error")));

// For non-error cells, None is returned
let formula_cell = Cell::new("safe_calculation", "Number", "42 + 1", "");
let empty_reason = formula_cell.reason();
assert_eq!(empty_reason, None);

// Check if a cell has error information before accessing reason
if error_cell.is_error() {
    if let (Some(identifier), Some(reason)) = (error_cell.identifier(), error_cell.reason()) {
        println!("Error in cell '{}': {}", identifier, reason);
    }
}

§See Also

Cell::is_error() - Check if a cell represents an error state
Cell::formula() - Get the formula expression that caused the error
Cell::location() - Get the specific location within the formula where the error occurred
Cell::identifier() - Get the identifier of the cell containing the error

Source

pub fn formula(&self) -> Option<Arc<str>>

§Retrieves the formula string from a cell that contains a formula or error information.

§title: Formula

Retrieves the formula string from a cell that contains a formula or error information.

This method returns the formula content for cells that represent computational expressions or error states containing formula information. For other cell types, it returns an empty string.

§Returns

Returns an Arc<str> containing:

The formula string for Cell::Formula and Cell::Errata cells
An empty string for all other cell types

§Cell Types Supported

Cell::Formula - Returns the formula expression
Cell::Errata - Returns the formula that caused the error
All other cell types - Returns an empty string

§Examples

use aimx::Cell;
use std::sync::Arc;

// Formula cell
let formula_cell = Cell::Formula {
    identifier: Arc::from("calc"),
    typedef: Arc::from("Number"),
    formula: Arc::from("2 + 2"),
    value: Arc::from("4"),
};

assert_eq!(formula_cell.formula(), Some(Arc::from("2 + 2")));

// Error cell with formula
let error_cell = Cell::Errata {
    identifier: Arc::from("bad_calc"),
    typedef: Arc::from("Number"),
    reason: Arc::from("Division by zero"),
    formula: Arc::from("1 / 0"),
    location: Arc::from(""),
};

assert_eq!(error_cell.formula(), Some(Arc::from("1 / 0")));

// Node cell (no formula)
let node_cell = Cell::Node {
    identifier: Arc::from("my_node"),
    value: Arc::from("node_value"),
};

assert_eq!(node_cell.formula(), None);

§See Also

Cell::value - Get the computed value
Cell::reason - Get error reason for error cells
Cell::location - Get error location for error cells

Source

pub fn location(&self) -> Option<Arc<str>>

§Retrieves the error location string from a cell that represents an error state, or an empty string for other cell types.

§title: Location

Retrieves the error location string from a cell that represents an error state, or an empty string for other cell types.

This method provides access to the specific location within a formula or expression where an error occurred. It is primarily used for diagnostic purposes when working with error cells (Cell::Errata).

§Arguments

This function takes no arguments.

§Returns

Returns an Arc<str> containing:

The error location string if the cell is an Errata variant with location information
An empty string (Arc::from("")) for all other cell types

§Behavior

The function pattern matches on the cell variant:

For Cell::Errata with location information (from Errata::Three), returns the location string that points to the specific part of the formula where the error occurred
For all other cell types (including Cell::Errata variants without location information), returns an empty string

§Usage Pattern

use aimx::{Cell, values::Value};
use std::sync::Arc;

// Create an error cell
let error_cell = Cell::Errata {
    identifier: Arc::from("test"),
    typedef: Arc::from("Number"),
    reason: Arc::from("Division by zero"),
    formula: Arc::from("10 / 0"),
    location: Arc::from("/ 0"),
};

// Retrieve the error location
let location = error_cell.location();
if let Some(loc) = location {
    println!("Error location: {}", loc); // Prints: "/ 0"
}

// For non-error cells, returns None
let formula_cell = Cell::Formula {
    identifier: Arc::from("test"),
    typedef: Arc::from("Number"),
    formula: Arc::from("1 + 2"),
    value: Arc::from("3"),
};

let empty_location = formula_cell.location();
assert_eq!(empty_location, None);

§See Also

Cell::is_error() - Check if a cell represents an error state
Cell::reason() - Get the error reason string
Cell::formula() - Get the formula string from error or formula cells

Source

pub fn value(&self) -> Option<Arc<str>>

§Retrieves the computed value string from a cell that contains a value or an empty string for other cell types.

§title: Value

This method retrieves the computed value string from a cell that contains a value or an empty string for other cell types. It provides access to the result of formula evaluation or the static value stored in node and result cells.

§Arguments

This method takes no arguments.

§Returns

Returns an Arc<str> containing:

The computed value for Cell::Node cells
The computed value for Cell::Formula cells
The computed value for Cell::Result cells
An empty string for all other cell types via Value::empty_str()

§Behavior

The value() method examines the cell’s variant and extracts the value field when available:

For Cell::Node cells: Returns the stored node value
For Cell::Formula cells: Returns the computed result of the formula evaluation
For Cell::Result cells: Returns the inference result value
For all other cell types (Empty, Comment, Errata, Format, Branch, Retry): Returns an empty string

§Usage Pattern

The value() method is commonly used to:

Retrieve the computed result of a formula cell
Access the value stored in node cells
Get inference results from result cells
Display cell values in user interfaces or debugging tools

use aimx::{Cell, Reference};
use std::sync::Arc;

// Create a formula cell with a computed value
let formula_cell = Cell::new("calculation", "Number", "10 + 5", "15");

// Retrieve the computed value
let value = formula_cell.value();
assert_eq!(value, Some(Arc::from("15")));

// Create a node cell
let node_cell = Cell::Node {
    identifier: Arc::from("my_node"),
    value: Arc::from("node content"),
};

// Retrieve the node value
let node_value = node_cell.value();
assert_eq!(node_value, Some(Arc::from("node content")));

// For cells without values, None is returned
let empty_cell = Cell::Empty;
let empty_value = empty_cell.value();
assert_eq!(empty_value, None);

§See Also

Cell::formula() - Retrieves the formula expression of a cell
Cell::identifier() - Gets the identifier of a cell
Cell::is_formula() - Checks if a cell contains a formula
Cell::is_result() - Checks if a cell represents a result
Value::empty_str() - Returns an empty string reference

Source

pub fn instruction(&self) -> Option<Arc<str>>

§Retrieves the instruction string from a cell that contains a format instruction.

§title: Instruction

This method retrieves the instruction string from a cell that contains a format instruction. It provides access to the formatting instruction that defines how output should be processed or displayed.

§Arguments

This method takes no arguments.

§Returns

Returns an Arc<str> containing:

The instruction string for Cell::Format cells
An empty string for all other cell types

§Behavior

The instruction() method examines the cell’s variant and extracts the instruction field when available:

For Cell::Format cells: Returns the stored instruction string that describes the formatting operation
For all other cell types: Returns an empty string via Value::empty_str()

The instruction typically describes the type of formatting to be applied, such as “Format as JSON”, “Convert to CSV”, or other processing directives.

§Usage Pattern

The instruction() method is commonly used to:

Inspect the formatting instruction associated with a format cell
Display formatting metadata in development or debugging tools
Determine the type of processing required for output formatting

use aimx::{Cell, Reference, values::Value};
use std::sync::Arc;

// Create a format cell with instruction
let format_cell = Cell::Format {
    identifier: Arc::from("output_format"),
    instruction: Arc::from("Format as JSON"),
    template: Arc::from("{{result}}"),
    examples: Arc::new(vec![
        Arc::from("{\"status\": \"success\"}"),
        Arc::from("{\"status\": \"error\"}")
    ]),
};

// Retrieve the instruction
let instruction = format_cell.instruction();
assert_eq!(instruction, Some(Arc::from("Format as JSON")));

// Check if the cell is a format cell and get its instruction
if format_cell.is_format() {
    if let Some(inst) = instruction {
        println!("Formatting instruction: {}", inst);
    }
}

// For non-format cells, None is returned
let formula_cell = Cell::new("calculation", "Number", "10 + 5", "");
let empty_instruction = formula_cell.instruction();
assert_eq!(empty_instruction, None);

§See Also

Cell::template() - Retrieves the template string from a format cell
Cell::examples() - Retrieves the example strings from a format cell
Cell::is_format() - Checks if a cell contains a format instruction
Value::empty_str() - Returns an empty string reference

Source

pub fn template(&self) -> Option<Arc<str>>

§Retrieves the template string from a cell that contains a format instruction.

§title: Template

This method retrieves the template string from a cell that contains a format instruction. It provides access to the template that defines how data should be formatted or structured in the output.

§Arguments

This method takes no arguments.

§Returns

Returns an Arc<str> containing:

The template string for Cell::Format cells
An empty string for all other cell types

§Behavior

The template() method examines the cell’s variant and extracts the template field when available:

For Cell::Format cells: Returns the stored template string that defines the output format structure
For all other cell types: Returns an empty string via Value::empty_str()

The template typically contains placeholders and formatting instructions that guide how data should be rendered, such as "{{result}}" for simple substitution or more complex patterns for structured output.

§Usage Pattern

The template() method is commonly used to:

Retrieve formatting templates associated with format cells
Inspect the output structure definition in development or debugging tools
Extract template strings for further processing or validation

use aimx::{Cell, values::Value};
use std::sync::Arc;

// Create a format cell with template
let format_cell = Cell::Format {
    identifier: Arc::from("output_format"),
    instruction: Arc::from("Format as JSON"),
    template: Arc::from("{{result}}"),
    examples: Arc::new(vec![
        Arc::from("{\"status\": \"success\"}"),
        Arc::from("{\"status\": \"error\"}")
    ]),
};

// Retrieve the template
let template = format_cell.template();
assert_eq!(template, Some(Arc::from("{{result}}")));

// Check if the cell is a format cell and get its template
if format_cell.is_format() {
    if let Some(temp) = template {
        println!("Formatting template: {}", temp);
    }
}

// For non-format cells, None is returned
let formula_cell = Cell::new("calculation", "Number", "10 + 5", "");
let empty_template = formula_cell.template();
assert_eq!(empty_template, None);

§See Also

Cell::instruction() - Retrieves the instruction string from a format cell
Cell::examples() - Retrieves the example strings from a format cell
Cell::is_format() - Checks if a cell contains a format instruction
Value::empty_str() - Returns an empty string reference

Source

pub fn examples(&self) -> Option<Arc<Vec<Arc<str>>>>

§Retrieves the example strings from a cell that contains a format instruction.

§title: Examples

Retrieves the example strings from a cell that contains a format instruction.

This method extracts the examples array from a Cell::Format variant, which contains sample values used to demonstrate how data should be formatted. Format cells are used to define formatting rules for prompts or output schemas, and the examples provide concrete illustrations of the expected format.

The examples are stored as an Arc<Vec<Arc<str>>> containing string representations of sample values that show how the template should be applied in practice.

§Returns

Returns Some(Arc<Vec<Arc<str>>>) containing the examples array if the cell is a format instruction (Cell::Format), otherwise returns None.

§Behavior

Internally, examples() performs pattern matching on the Cell enum:

Returns Some(examples.clone()) when the cell is Cell::Format { .. } where examples is the examples field
Returns None for all other cell variants including empty cells, formulas, results, errors, comments, nodes, branches, and retries

§Usage Pattern

use aimx::Cell;
use std::sync::Arc;

// Create a format cell with examples
let format_cell = Cell::Format {
    identifier: Arc::from("output_format"),
    instruction: Arc::from("Format the result as JSON"),
    template: Arc::from("{{result}}"),
    examples: Arc::new(vec![
        Arc::from("{\"status\": \"success\", \"data\": $result}"),
        Arc::from("{\"status\": \"error\", \"message\": $result}"),
        Arc::from("{\"status\": \"pending\", \"progress\": 50}")
    ]),
};

// Create other cell types for comparison
let formula_cell = Cell::new("temperature", "Number", "32 + 25", "");
let empty_cell = Cell::Empty;

// Retrieve examples from format cell
if let Some(examples) = format_cell.examples() {
    println!("Found {} examples:", examples.len());
    for (i, example) in examples.iter().enumerate() {
        println!("  {}: {}", i + 1, example);
    }
    // Output:
    // Found 3 examples:
    //   1: {"status": "success", "data": $result}
    //   2: {"status": "error", "message": $result}
    //   3: {"status": "pending", "progress": 50}
} else {
    println!("No examples found - not a format cell");
}

// For non-format cells, examples() returns None
assert!(formula_cell.examples().is_none());
assert!(empty_cell.examples().is_none());

// Use with format cells to validate structure
if format_cell.is_format() {
    if let Some(examples) = format_cell.examples() {
        assert_eq!(examples.len(), 3);
        assert!(examples.iter().any(|ex| ex.contains("success")));
        assert!(examples.iter().any(|ex| ex.contains("error")));
    }
}

§API Integration

This method is commonly used to:

Extract example data when processing format cells for inference pipelines
Validate that format cells contain appropriate examples for training or guidance
Display example formats in UI components that show workflow templates
Generate documentation or help text from workflow format instructions
Populate inference prompts with concrete examples of expected output format
Test scenarios where format validation requires checking example content

§See Also

Cell - The main cell type containing various workflow representations
Cell::is_format() - Checks if cell represents a format instruction
Cell::instruction() - Retrieves the instruction from a format cell
Cell::template() - Retrieves the template from a format cell
Value::Format - The underlying format value type

Source

pub fn condition(&self) -> Option<Arc<str>>

§Retrieves the condition string from a cell that contains a condition or an empty string for other cell types.

§title: Condition

This method retrieves the condition string from a cell that contains a condition or an empty string for other cell types. It provides access to the conditional expressions used in branch and retry workflow instructions.

§Arguments

This method takes no arguments.

§Returns

Returns an Arc<str> containing:

The condition expression for Cell::Branch cells
The condition expression for Cell::Retry cells
An empty string for all other cell types via Value::empty_str()

§Behavior

The condition() method examines the cell’s variant and extracts the condition field when available:

For Cell::Branch cells: Returns the condition that determines the branch path (e.g., “x > 5”, “status == ‘error’”)
For Cell::Retry cells: Returns the condition that triggers retry logic (e.g., “network_error”, “timeout_occurred”)
For all other cell types (Empty, Comment, Errata, Node, Format, Formula, Result): Returns an empty string

§Usage Pattern

The condition() method is commonly used to:

Inspect branch conditions during workflow debugging
Retrieve retry conditions for error handling analysis
Display conditional logic in workflow visualization tools
Validate conditional expressions during workflow testing

use aimx::Cell;
use std::sync::Arc;

// Create a branch cell with a condition
let branch_cell = Cell::Branch {
    identifier: Arc::from("decision_point"),
    condition: Arc::from("x > 5"),
    target: Arc::from("target_node"),
};

// Retrieve the branch condition
let branch_condition = branch_cell.condition();
assert_eq!(branch_condition, Some(Arc::from("x > 5")));

// Create a retry cell with a condition
let retry_cell = Cell::Retry {
    identifier: Arc::from("retry_logic"),
    count: 3,
    condition: Arc::from("network_error"),
    target: Arc::from("fallback_node"),
};

// Retrieve the retry condition
let retry_condition = retry_cell.condition();
assert_eq!(retry_condition, Some(Arc::from("network_error")));

// For cells without conditions, None is returned
let formula_cell = Cell::new("calculation", "Number", "10 + 5", "15");
let empty_condition = formula_cell.condition();
assert_eq!(empty_condition, None);

§See Also

Cell::target() - Retrieves the target identifier for branch and retry cells
Cell::is_branch() - Checks if a cell represents a branch instruction
Cell::is_retry() - Checks if a cell represents a retry instruction
Cell::count() - Gets the retry count for retry cells
Value::empty_str() - Returns an empty string reference

Source

pub fn target(&self) -> Option<Arc<str>>

§Retrieves the target identifier string from cells that contain target information.

§title: Target

This function retrieves the target identifier string from cells that contain target information.

§Arguments

This function takes no arguments.

§Returns

Returns an Arc<str> containing the target identifier string for cells that have a target field (Branch and Retry cells), or an empty string for all other cell types.

§Behavior

The target() method examines the cell variant and returns the target field for cells that contain target information:

For Cell::Branch cells, returns the target node identifier that the branch should jump to when the condition is true
For Cell::Retry cells, returns the target node identifier that should be executed when retry conditions are met
For all other cell types, returns an empty string using Value::empty_str()

§Side Effects

This function has no side effects. It is a pure accessor method that only reads data from the cell.

§Usage Pattern

use aimx::Cell;
use std::sync::Arc;

// Create a branch cell with a target
let branch_cell = Cell::Branch {
    identifier: Arc::from("decision"),
    condition: Arc::from("x > 10"),
    target: Arc::from("next_step"),
};

// Retrieve the target
let target = branch_cell.target();
assert_eq!(target, Some(Arc::from("next_step")));

§See Also

Cell::condition() - Retrieves the condition string from Branch and Retry cells
Cell::count() - Retrieves the retry count from Retry cells
Cell::is_branch() - Checks if a cell is a Branch cell
Cell::is_retry() - Checks if a cell is a Retry cell

Source

pub fn count(&self) -> Option<u32>

§Retrieves the retry count from a cell that represents a retry instruction in the workflow.

§title: Count

This function retrieves the retry count from a cell that represents a retry instruction in the workflow, or returns None for other cell types.

The retry count indicates how many times a retry operation should be attempted when the retry condition is met. This is used in workflow retry logic to control the number of retry attempts for error handling or conditional re-execution.

§Arguments

This function takes no arguments.

§Returns

Returns an Option<u32> containing:

Some(count) - The retry count value when the cell represents a retry instruction
None - When the cell is any other type (empty, comment, errata, node, format, branch, formula, or result)

§Behavior

The function performs pattern matching on the cell variant:

If the cell is Cell::Retry, extracts and returns the count field as Some(count)
For all other cell variants, returns None

§Usage Pattern

use aimx::Cell;
use std::sync::Arc;

// Create a retry cell
let retry_cell = Cell::Retry {
    identifier: Arc::from("retry_logic"),
    count: 3,
    condition: Arc::from("error_occurred"),
    target: Arc::from("fallback_node"),
};

// Get the retry count
if let Some(count) = retry_cell.count() {
    println!("Retry count: {}", count);
} else {
    println!("Not a retry cell");
}

// For non-retry cells, count() returns None
let formula_cell = Cell::Formula {
    identifier: Arc::from("calculation"),
    typedef: Arc::from("Number"),
    formula: Arc::from("10 + 5"),
    value: Arc::from("15"),
};

assert!(formula_cell.count().is_none());

§See Also

Cell::is_retry() - Check if a cell represents a retry instruction
Cell::condition() - Get the retry condition string
Cell::target() - Get the retry target identifier
Cell::Retry - The retry cell variant containing this count information

Source

pub fn print(&self, writer: &mut Writer)

§Serializes a cell’s content to a writer in a human-readable format.

§title: Print

This function serializes a cell’s content to a writer in a human-readable format. The output format varies based on the cell type and the writer’s mode, providing either plain text representation or formula-style serialization.

§Arguments

writer - A mutable reference to a Writer that receives the serialized cell content. The writer’s mode determines the output format:
- formulizer mode: Produces formula-style output with line endings and quoted values
- Other modes: Produce compact representations without line endings

§Behavior

Internally, print() performs the following operations:

Matches the cell variant and formats each type according to its semantic structure
For most cell types, writes the identifier followed by type information and values
Uses the writer’s print() method for proper escaping and formatting of string values
Adds line endings only when the writer is in formulizer mode

The function handles all cell variants:

Empty: Writes nothing
Comment: Writes only the comment text (in formulizer mode)
Errata: Writes identifier, typedef, formula, and error reason in error format
Result: Writes identifier, typedef, and computed value with $ prefix
Node: Writes identifier and node value with $ prefix
Format: Writes identifier, instruction, template, and examples
Branch: Writes identifier, condition, and target with -> separator
Retry: Writes identifier, retry count, condition, and target
Formula: Writes identifier, typedef, formula, and computed value

§Side Effects

Modifies the internal buffer of the provided writer
No file I/O operations are performed
No external state changes occur

§Usage Pattern

use aimx::{Cell, aim::Writer};
use std::sync::Arc;

// Create a formula cell
let cell = Cell::Formula {
    identifier: Arc::from("calculate"),
    typedef: Arc::from("Number"),
    formula: Arc::from("1 + 1"),
    value: Arc::from("2"),
};

// Serialize to formula format
let mut writer = Writer::formulizer();
cell.print(&mut writer);
let output = writer.finish();
assert_eq!(output, "calculate: Number = 1 + 1 $'2'\n");

// Serialize to string format
let mut string_writer = Writer::stringizer();
cell.print(&mut string_writer);
let compact_output = string_writer.finish();
// Compact output without line endings or quotes
assert_eq!(compact_output, "calculate: Number = 1 + 1 $2");

§See Also

Writer - The buffered writer used for serialization
to_formula() - Convenience method that uses print() to create formula strings
WriterLike - Trait that provides print() via the write() method

Source

pub fn to_formula(&self) -> String

§Return the formula-string representation (round-trippable by the parser).

§title: To Formula

This method returns a string representation of the cell that can be parsed back into the same cell structure. It provides a human-readable, round-trippable format suitable for serialization, debugging, and display purposes.

§Arguments

This method takes no arguments.

§Returns

Returns a String containing the cell’s content formatted as an AIMX formula that can be parsed back into the same cell structure.

§Behavior

The to_formula() method performs the following operations:

Creates a new Writer using Writer::formulizer() mode
Calls the cell’s Cell::print() method to serialize the cell content
Returns the finished string using Writer::finish()

The formulizer mode:

Wraps string values in single quotes
Escapes special characters within quoted strings
Uses a clean, readable format without list prefixes

§Side Effects

None. This method only reads the cell’s data and returns a formatted string representation.

§Usage Pattern

The to_formula() method is commonly used for:

Serialization: Converting cell data to a string format for storage or transmission
Debugging: Displaying cell contents in a human-readable format during development
Logging: Recording cell state changes in logs with proper escaping
Round-trip parsing: Generating output that can be parsed back into the same cell structure

use aimx::Cell;

// Create a formula cell
let formula_cell = Cell::new("calculation", "Number", "10 + 5", "15");

// Get the formula representation
let formula_string = formula_cell.to_formula();
println!("Cell representation: {}", formula_string);
// Output: "calculation: Number = 10 + 5 $15"

// Create a text cell with special characters
let text_cell = Cell::new("message", "Text", "\"Hello, World!\"", "Hello, World!");

// Get the escaped formula representation
let escaped_string = text_cell.to_formula();
println!("Escaped representation: {}", escaped_string);
// Output: "message: Text = \"Hello, World!\" $'Hello, World!'"

§Examples by Cell Type

Different cell types produce different formula representations:

use aimx::Cell;
use std::sync::Arc;

// Formula cell
let formula_cell = Cell::new("result", "Number", "42 * 2", "84");
assert_eq!(formula_cell.to_formula(), "result: Number = 42 * 2 $84");

// Comment cell
let comment_cell = Cell::Comment { comment: Arc::from("This is a comment") };
assert_eq!(comment_cell.to_formula(), "This is a comment\n");

// Error cell
let error_cell = Cell::Errata {
    identifier: Arc::from("error_cell"),
    typedef: Arc::from("Number"),
    reason: Arc::from("Division by zero"),
    formula: Arc::from("10 / 0"),
    location: Arc::from("line 5"),
};
assert_eq!(error_cell.to_formula(), "error_cell: Number = 10 / 0 # Division by zero");

// Node cell
let node_cell = Cell::Node {
    identifier: Arc::from("config"),
    value: Arc::from("production"),
};
assert_eq!(node_cell.to_formula(), "config: Node = $'production'");