carbon_macros/

schemas.rs

//! # Schema Module
//!
//! The `schema` module provides macros for constructing and organizing transaction schemas
//! in a hierarchical manner. These macros are designed to simplify the creation of complex
//! transaction structures by allowing inline specification of schema elements, which represent instructions
//! within transactions.
//!
//! ## Overview
//!
//! This module includes two primary macros:
//! - **`schema!`**: The main macro for constructing a `TransactionSchema`, which is a hierarchical
//!   schema representation.
//! - **`schema_inner!`**: A helper macro, used internally by `schema!` for recursive schema node construction.
//!
//! Together, these macros enable you to define schema nodes in a flexible and intuitive manner,
//! allowing for combinations of `Any` and `Instruction` nodes with optional nested instructions.
//!
//! ## Key Macros
//!
//! ### `schema!`
//!
//! The `schema!` macro is the primary entry point for constructing a `TransactionSchema`.
//! It parses provided tokens into a `TransactionSchema` object, allowing inline definition
//! of various schema elements in a tree-like structure. This macro supports keywords like
//! `any` to create branches that can match multiple instruction types.
//!
//! #### Example
//!
//! ```rust
//! use your_crate::schema;
//!
//! let transaction_schema = schema![
//!     any,
//!     [
//!         AllInstructionTypes::JupSwap(JupiterInstructionType::SwapEvent),
//!         "jup_swap_event",
//!         []
//!     ],
//!     any,
//! ];
//! ```
//!
//! This example defines a schema with an `any` branch, an `Instruction` node with nested
//! instructions, and another `any` branch, creating a flexible transaction structure.
//! In practical terms, this means that the schema represents a transaction that has a Jupiter Swap Event
//! instruction anywhere within the transaction.
//!
//! ### `schema_inner!`
//!
//! This macro is used internally by `schema!` to build out individual `SchemaNode` elements.
//! It supports three main syntax patterns: `any`, single `Instruction` nodes, and nested `Instruction`
//! nodes. Users typically don’t need to interact with this macro directly, as it’s invoked by `schema!`
//! to handle recursive node construction.
//!
//! #### Supported Syntax Patterns
//!
//! 1. **`any`**: Adds an `Any` node, which can match any instruction type, multiple times.
//! 2. **`[$ix_type:expr, $name:expr]`**: Adds an `Instruction` node without nested instructions.
//! 3. **`[$ix_type:expr, $name:expr, [$($inner:tt)*]]`**: Adds an `Instruction` node with nested inner instructions.
//!
//! ## Notes
//!
//! - The `schema!` macro relies on `schema_inner!` for recursive parsing and node creation.
//! - When using the `schema!` macro, ensure that all instruction types and identifiers correspond
//!   to valid values expected by the `TransactionSchema` to avoid compilation errors.
//!
//! ## Crate Dependencies
//!
//! This module relies on components like `SchemaNode` and `InstructionSchemaNode` to build the schema tree.
//! Make sure these types are defined and accessible within the scope of the module’s usage.
//!

/// Constructs a `TransactionSchema` from provided tokens.
///
/// The `schema!` macro facilitates the creation of a `TransactionSchema` by parsing
/// the provided tokens and assembling the structure. This macro simplifies schema
/// construction by allowing inline specification of schema elements, including
/// instruction types and associated names.
///
/// # Syntax
///
/// The `schema!` macro uses a flexible token-based syntax, enabling you to define
/// schema nodes inline. Nodes are defined in a hierarchical manner, with keywords
/// like `any` indicating schema branches, followed by instruction types, string
/// identifiers, and additional attributes or sub-nodes as needed.
///
/// # Example
///
/// ```rust
///
/// let transaction_schema = schema![
///     any
///     [
///         AllInstructionTypes::JupSwap(JupiterInstructionType::SwapEvent),
///         "jup_swap_event",
///         []
///     ]
///     any
/// ];
///
/// ```
///
/// # Parameters
///
/// - `$tt`: The token stream passed to the macro, which may include multiple schema
///   nodes and attributes. These tokens are parsed to construct the schema tree,
///   forming a `TransactionSchema` object with a root node containing the specified
///   elements.
///
/// # Returns
///
/// This macro returns a `TransactionSchema` instance with the constructed schema
/// tree based on the tokens provided. The schema is organized with nodes added
/// to the root, allowing for complex, multi-layered transaction structures, which represent
/// real transaction instructions, in order.
///
/// # Notes
///
/// - This macro requires that the inner macro `schema_inner!` is also defined,
///   as it handles the recursive parsing and node addition to the schema.
/// - Ensure that types and keywords used within the schema correspond to valid
///   identifiers and instructions expected by `TransactionSchema`. Inconsistent
///   tokens may lead to compilation errors or incorrect schema construction.
///
#[macro_export]
macro_rules! schema {
    ($($tt:tt)*) => {{
        let mut nodes = Vec::new();
        schema_inner!(&mut nodes, $($tt)*);
        carbon_core::schema::TransactionSchema { root: nodes }
    }};
}

/// Recursively constructs schema nodes within the `schema!` macro.
///
/// The `schema_inner!` macro is utilized internally by the `schema!` macro to build
/// a `TransactionSchema` structure by parsing tokens into individual `SchemaNode`
/// elements. This macro supports multiple node types, including `Any` nodes and
/// `Instruction` nodes with optional nested instructions. Each parsed node is
/// appended to the provided vector, forming a hierarchical schema structure.
///
/// # Syntax
///
/// This macro supports three main syntax patterns:
///
/// 1. `any`: Adds an `Any` node to the schema, indicating a branch point that
///    accepts multiple instructions of any type.
/// 2. `[$ix_type:expr, $name:expr]`: Adds an `Instruction` node with the
///    specified instruction type and name, without nested instructions.
/// 3. `[$ix_type:expr, $name:expr, [$($inner:tt)*]]`: Adds an `Instruction` node
///    with the specified instruction type and name, including inner instructions
///    which are parsed recursively.
///
/// # Parameters
///
/// - `$nodes`: A mutable reference to a `Vec<SchemaNode>`. This vector accumulates
///   the constructed schema nodes, which can include both `Any` and `Instruction`
///   node variants with nested instructions.
/// - `$ix_type`: The instruction type for the node, provided as an expression.
///   This identifies the specific instruction type in the schema.
/// - `$name`: A string literal representing the name of the instruction.
///   This name is associated with the `Instruction` node for identification.
///
/// # Returns
///
/// This macro modifies the `Vec<SchemaNode>` passed as `$nodes`, adding each
/// parsed `SchemaNode` to the vector. Nodes can be nested, with the structure
/// reflecting any provided inner instructions.
///
/// # Notes
///
/// - This macro is intended for internal use within the `schema!` macro and is
///   not typically called directly by users.
/// - Ensure that each `$ix_type` corresponds to a valid instruction type
///   and that `$name` is a string literal for compatibility with `InstructionSchemaNode`.
/// - The recursive structure allows for complex, multi-level instruction schemas
///   suitable for detailed transaction validation and processing.
///
#[macro_export]
macro_rules! schema_inner {
    ($nodes:expr, ) => {};

    ($nodes:expr, any $($rest:tt)*) => {
        $nodes.push(carbon_core::schema::SchemaNode::Any);
        schema_inner!($nodes, $($rest)*);
    };

    ($nodes:expr, [$ix_type:expr, $name:expr] $($rest:tt)*) => {
        $nodes.push(carbon_core::schema::SchemaNode::Instruction(carbon_core::schema::InstructionSchemaNode {
            ix_type: $ix_type,
            name: $name.to_string(),
            inner_instructions: Vec::new(),
        }));
        schema_inner!($nodes, $($rest)*);
    };

    ($nodes:expr, [$ix_type:expr, $name:expr, [$($inner:tt)*]] $($rest:tt)*) => {{
        let mut inner_nodes = Vec::new();
        schema_inner!(&mut inner_nodes, $($inner)*);
        $nodes.push(carbon_core::schema::SchemaNode::Instruction(carbon_core::schema::InstructionSchemaNode {
            ix_type: $ix_type,
            name: $name.to_string(),
            inner_instructions: inner_nodes,
            }));
        schema_inner!($nodes, $($rest)*);
    }};
}