cairo_args_runner/
lib.rs

1//! # Cairo Args Runner
2//!
3//! `cairo_args_runner` is a utility designed to execute Cairo 1 programs with arguments directly from the command line.
4//! This tool simplifies the process of running Cairo programs by allowing you to specify arguments directly in the command line.
5//!
6//! ## Configuration
7//!
8//! Make sure your `Scarb.toml` file includes the following section:
9//!
10//! ```toml
11//! [lib]
12//! sierra-text = true
13//! ```
14//!
15//! ## Examples
16//!
17//! ### Running a Complex Function
18//! Run a complex function with an array of arguments:
19//! ```rust
20//! use cairo_args_runner::{arg_array, felt_vec, run};
21//!
22//! let target = "target/dev/complex.sierra.json";
23//! let function = "main";
24//! let args = vec![arg_array![1, 2, 4, 8, 16], arg_array![1, 2, 3, 4, 5, 6]];
25//!
26//! let result = run(target, function, &args);
27//! assert_eq!(result.unwrap(), felt_vec![31, 21, 5, 6]);
28//! ```
29//! **Note:** There is a known bug in this example related to passing arrays as arguments.
30//! For more details and updates on this issue, please visit
31//! [Issue #7 on GitHub](https://github.com/neotheprogramist/cairo-args-runner/issues/7).
32//!
33//! ### Fibonacci Sequence
34//! Calculate the 10th number in the Fibonacci sequence:
35//! ```rust
36//! use cairo_args_runner::{arg_value_vec, felt_vec, run};
37//!
38//! let target = "target/dev/fib.sierra.json";
39//! let function = "main";
40//! let args = arg_value_vec![10];
41//!
42//! let result = run(target, function, &args);
43//! assert_eq!(result.unwrap(), felt_vec![55]);
44//! ```
45//!
46//! ### Working with Structs
47//! Execute a function that works with multiple struct arguments:
48//! ```rust
49//! use cairo_args_runner::{arg_array, arg_value_vec, felt_vec, run};
50//!
51//! let target = "target/dev/structs.sierra.json";
52//! let function = "main";
53//! let mut args = arg_value_vec![1, 2, 10, 5, 9];
54//! args.push(arg_array![1, 2, 3]);
55//!
56//! let result = run(target, function, &args);
57//! assert_eq!(result.unwrap(), felt_vec![33]);
58//! ```
59//!
60//! ### Summation Example
61//! Run a function to sum an array of numbers:
62//! ```rust
63//! use cairo_args_runner::{arg_array, felt_vec, run};
64//!
65//! let target = "target/dev/sum.sierra.json";
66//! let function = "main";
67//! let args = vec![arg_array![1, 3, 9, 27]];
68//!
69//! let result = run(target, function, &args);
70//! assert_eq!(result.unwrap(), felt_vec![40]);
71//! ```
72//!
73//! These examples demonstrate various ways to use `cairo_args_runner` to execute Cairo 1 programs with different types of arguments,
74//! aiding users in understanding and utilizing the utility effectively.
75
76pub use cairo_felt::Felt252;
77pub use cairo_lang_runner::Arg;
78use errors::SierraRunnerError;
79use utils::parse::SingleFileParser;
80
81pub use crate::utils::args::VecArg;
82use crate::utils::{parse::SierraParser, run::SierraRunner};
83
84pub mod errors;
85mod macros;
86mod utils;
87
88/// Runs the specified function with the provided arguments.
89///
90/// # Arguments
91///
92/// * `file_name` - A string slice that holds the file name.
93/// * `function` - A string slice that holds the function to run.
94/// * `args` - A slice of `Arg` that holds the arguments to the function.
95///
96/// # Returns
97///
98/// * `Result<Vec<Felt252>>` - A Result containing a vector of `Felt252` if the function runs successfully, or an error if it fails.
99///
100/// # Errors
101///
102/// This function will return an error if:
103///
104/// * The file specified by `file_name` cannot be found or read.
105/// * The function specified by `function` cannot be found in the file.
106/// * The arguments provided in `args` are not valid for the function.
107/// * The function execution fails for any reason.
108pub fn run(
109    file_name: &str,
110    function: &str,
111    args: &[Arg],
112) -> Result<Vec<Felt252>, SierraRunnerError> {
113    let parser = SingleFileParser::new(file_name);
114    let runner = parser.parse()?;
115
116    runner.run(format!("::{function}").as_str(), args)
117}
cairo_args_runner/lib.rs

cairo_args_runner/
lib.rs
