rialo_venus_dsl/
lib.rs

1// Copyright (c) Subzero Labs, Inc.
2// SPDX-License-Identifier: Apache-2.0
3
4//! # Rialo Workflow Macro (V2 - syngen-generated parser)
5//!
6//! This crate provides the `rialo!` procedural macro for generating Solana program interfaces and implementations
7//! from high-level workflow definitions. The macro follows a classic compiler architecture pattern:
8//!
9//! **Parse → Model → Transform → Generate**
10//!
11//! ## Architecture Overview
12//!
13//! The compilation pipeline consists of four main phases:
14//!
15//! 1. **Parse** (`parse` module): Converts macro input tokens into an internal data model using syngen-generated parser
16//! 2. **Model** (`model` module): Provides the internal representation of workflow components
17//! 3. **Transform** (`transform` module): Analyzes and transforms the model for code generation
18//! 4. **Generate** (`generate` module): Produces Solana program code from the transformed model
19//!
20//! ## Key Concepts
21//!
22//! - **Workflow State**: Persistent data structure that survives across async operations
23//! - **Workflow Program**: Collection of functions that define the workflow's behavior
24//! - **Function Types**: Different categories of functions (initiating, handler, control, terminating, internal)
25//! - **Async Operations**: Venus DSL syntax (AFTER, EVERY, ON, SEND, START) that are transformed into Solana program calls
26//! - **Resource Analysis**: Automatic calculation of required Solana accounts based on async operations
27//!
28//! ## Input Format
29//!
30//! ```rust,ignore
31//! rialo! {
32//!     state {
33//!         // Persistent state fields
34//!         field_name: Type,
35//!     }
36//!
37//!     program {
38//!         // Use statements and function definitions
39//!         use some_crate::SomeType;
40//!
41//!         initiating fn entry_point(&mut self, param: Type) -> ProgramResult {
42//!             // Function body with Venus DSL async syntax
43//!         }
44//!
45//!         handler fn async_callback(&mut self, data: Type) -> ProgramResult {
46//!             // Handler function body
47//!         }
48//!     }
49//! }
50//! ```
51//!
52//!
53//! ## Generated Code Structure
54//!
55//! The macro generates two main modules:
56//! - `interface`: Instruction definitions and constructors (always generated)
57//! - `implementation`: Program logic, state struct, and Solana entrypoint (feature-gated)
58//!
59//! ## Example Usage
60//!
61//! ```rust,ignore
62//! use crate::workflow;
63//!
64//! rialo! {
65//!     state {
66//!         counter: u64,
67//!         next_timestamp: u64,
68//!     }
69//!
70//!     program {
71//!         use rialo_s_program::entrypoint::ProgramResult;
72//!
73//!         initiating fn start(&mut self, frequency: u64) -> ProgramResult {
74//!             self.next_timestamp = self.unix_timestamp() as u64 + frequency;
75//!             AFTER self.next_timestamp seconds CALL self.tick();
76//!             Ok(())
77//!         }
78//!
79//!         handler fn tick(&mut self, _now: u64) -> ProgramResult {
80//!             self.counter += 1;
81//!             Ok(())
82//!         }
83//!     }
84//! }
85//! ```
86
87pub mod generate;
88pub mod generate_client;
89pub mod generate_manifest;
90pub mod generate_rex_wasm;
91pub mod generate_server_wit;
92pub mod model;
93pub mod parse;
94pub mod transform;
95
96// Re-export the main types for easy access
97pub use model::{Model, WorkflowBlock};
98
99/// Parse a Venus DSL program from a string
100///
101/// This is a convenience wrapper around `syn::parse_str` that works because
102/// the syngen! macro now generates `impl Parse for Model` directly.
103///
104/// ## Example
105///
106/// ```rust,ignore
107/// use crate::parse_from_str;
108///
109/// let source = r#"
110///     workflow {
111///         state { counter: u64 }
112///         program {
113///             fn test() -> ProgramResult { Ok(()) }
114///         }
115///     }
116/// "#;
117///
118/// let model = parse_from_str(source).unwrap();
119/// ```
120pub fn parse_from_str(input: &str) -> syn::Result<Model> {
121    syn::parse_str(input)
122}
123
124#[allow(dead_code)]
125fn _assert_model_is_parse() {
126    fn _assert_parse<T: syn::parse::Parse>() {}
127    _assert_parse::<Model>();
128}
129
130/// Generate Solana program code from a workflow model.
131///
132/// This function takes ownership of a parsed `Model` and generates the corresponding
133/// Solana program interface and implementation code.
134///
135/// ## Compilation Process
136///
137/// 1. **Parse**: The input tokens are parsed into a `model::Model` using syngen-generated parser
138/// 2. **Transform**: The model undergoes resource analysis and AST transformations
139/// 3. **Generate**: Solana program code is generated from the transformed model
140///
141/// ## Generated Output
142///
143/// The function generates two modules:
144/// - `interface`: Contains instruction enums and constructor functions
145/// - `implementation`: Contains the program struct, state management, and Solana entrypoint
146///
147/// See the `model::Model::generate` method for details on the code generation process.
148pub fn generate(model: &mut Model) -> proc_macro2::TokenStream {
149    model.generate()
150}
rialo_venus_dsl/lib.rs

rialo_venus_dsl/
lib.rs
