aimx/info_library/
misc_cards.rs

1//! Miscellaneous utility function documentation for AIMX expressions.
2//!
3//! Provides documentation for debugging and error handling functions used during
4//! expression evaluation and workflow development.
5
6use crate::{
7    info_library::{ArgumentInfo, FunctionCard},
8};
9
10/// Get documentation for all miscellaneous utility functions.
11pub fn get_misc_function_cards() -> Vec<FunctionCard> {
12    vec![
13        debug_function_card(),
14        error_function_card(),
15    ]
16}
17
18/// Documentation for the debug() function.
19fn debug_function_card() -> FunctionCard {
20    FunctionCard {
21        identifier: "debug",
22        signature: "debug(value)",
23        brief: "Print debug information for development and troubleshooting",
24        description: "The debug() function outputs the formula representation of a value to stderr \
25            and returns the value unchanged. This is useful for inspecting intermediate \
26            values during expression evaluation, tracing execution flow, and debugging \
27            complex workflows. The function has no impact on the actual computation \
28            result, making it safe to use during development and remove from production code.",
29        arguments: &[
30            &ArgumentInfo {
31                label: "value",
32                description: "Any value to debug (numbers, text, collections, arrays)",
33                type_hint: "Any",
34                optional: false,
35            },
36        ],
37        returns: "The input value unchanged, after printing its formula representation",
38        errors: "None - the function always succeeds",
39        categories: &["utility"],
40        examples: &[
41            "debug((1, 2, 3))",
42            "debug({\"name\": \"John\", \"age\": 30})",
43            "debug(\"Hello World\")",
44            "debug(42)",
45            "avg(debug(sales_data))",
46        ],
47    }
48}
49
50/// Documentation for the error() function.
51fn error_function_card() -> FunctionCard {
52    FunctionCard {
53        identifier: "error",
54        signature: "error(message)",
55        brief: "Create error values for testing and error handling simulation",
56        description: "The error() function creates an Errata value with the specified message, \
57            allowing you to simulate error conditions for testing purposes. This is \
58            particularly useful for testing error handling workflows, validating \
59            error propagation through expressions, and ensuring your workflow \
60            gracefully handles failure scenarios. The function always returns an \
61            error value, making it predictable for testing error paths.",
62        arguments: &[
63            &ArgumentInfo {
64                label: "message",
65                description: "Error message to include in the Errata value",
66                type_hint: "Text",
67                optional: false,
68            },
69        ],
70        returns: "An Errata value containing the specified error message",
71        errors: "Always returns an error value (Errata) for testing purposes",
72        categories: &["utility"],
73        examples: &[
74            "error(\"Invalid input format\")",
75            "error(\"Division by zero\")",
76            "if(condition, value, error(\"Fallback failed\"))",
77            "try_operation() ?? error(\"Operation failed\")",
78            "error(\"Test error\")",
79        ],
80    }
81}
aimx/info_library/misc_cards.rs

aimx/info_library/
misc_cards.rs
