cairo-args-runner 2.0.1

Cairo Args Runner is a utility designed to execute Cairo programs with arguments directly from the command line.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117

//! # Cairo Args Runner
//!
//! `cairo_args_runner` is a utility designed to execute Cairo 1 programs with arguments directly from the command line.
//! This tool simplifies the process of running Cairo programs by allowing you to specify arguments directly in the command line.
//!
//! ## Configuration
//!
//! Make sure your `Scarb.toml` file includes the following section:
//!
//! ```toml
//! [lib]
//! sierra-text = true
//! ```
//!
//! ## Examples
//!
//! ### Running a Complex Function
//! Run a complex function with an array of arguments:
//! ```rust
//! use cairo_args_runner::{arg_array, felt_vec, run};
//!
//! let target = "target/dev/complex.sierra.json";
//! let function = "main";
//! let args = vec![arg_array![1, 2, 4, 8, 16], arg_array![1, 2, 3, 4, 5, 6]];
//!
//! let result = run(target, function, &args);
//! assert_eq!(result.unwrap(), felt_vec![31, 21, 5, 6]);
//! ```
//! **Note:** There is a known bug in this example related to passing arrays as arguments.
//! For more details and updates on this issue, please visit
//! [Issue #7 on GitHub](https://github.com/neotheprogramist/cairo-args-runner/issues/7).
//!
//! ### Fibonacci Sequence
//! Calculate the 10th number in the Fibonacci sequence:
//! ```rust
//! use cairo_args_runner::{arg_value_vec, felt_vec, run};
//!
//! let target = "target/dev/fib.sierra.json";
//! let function = "main";
//! let args = arg_value_vec![10];
//!
//! let result = run(target, function, &args);
//! assert_eq!(result.unwrap(), felt_vec![55]);
//! ```
//!
//! ### Working with Structs
//! Execute a function that works with multiple struct arguments:
//! ```rust
//! use cairo_args_runner::{arg_array, arg_value_vec, felt_vec, run};
//!
//! let target = "target/dev/structs.sierra.json";
//! let function = "main";
//! let mut args = arg_value_vec![1, 2, 10, 5, 9];
//! args.push(arg_array![1, 2, 3]);
//!
//! let result = run(target, function, &args);
//! assert_eq!(result.unwrap(), felt_vec![33]);
//! ```
//!
//! ### Summation Example
//! Run a function to sum an array of numbers:
//! ```rust
//! use cairo_args_runner::{arg_array, felt_vec, run};
//!
//! let target = "target/dev/sum.sierra.json";
//! let function = "main";
//! let args = vec![arg_array![1, 3, 9, 27]];
//!
//! let result = run(target, function, &args);
//! assert_eq!(result.unwrap(), felt_vec![40]);
//! ```
//!
//! These examples demonstrate various ways to use `cairo_args_runner` to execute Cairo 1 programs with different types of arguments,
//! aiding users in understanding and utilizing the utility effectively.

pub use cairo_felt::Felt252;
pub use cairo_lang_runner::Arg;
use errors::SierraRunnerError;
use utils::parse::SingleFileParser;

pub use crate::utils::args::VecArg;
use crate::utils::{parse::SierraParser, run::SierraRunner};

pub mod errors;
mod macros;
mod utils;

/// Runs the specified function with the provided arguments.
///
/// # Arguments
///
/// * `file_name` - A string slice that holds the file name.
/// * `function` - A string slice that holds the function to run.
/// * `args` - A slice of `Arg` that holds the arguments to the function.
///
/// # Returns
///
/// * `Result<Vec<Felt252>>` - A Result containing a vector of `Felt252` if the function runs successfully, or an error if it fails.
///
/// # Errors
///
/// This function will return an error if:
///
/// * The file specified by `file_name` cannot be found or read.
/// * The function specified by `function` cannot be found in the file.
/// * The arguments provided in `args` are not valid for the function.
/// * The function execution fails for any reason.
pub fn run(
    file_name: &str,
    function: &str,
    args: &[Arg],
) -> Result<Vec<Felt252>, SierraRunnerError> {
    let parser = SingleFileParser::new(file_name);
    let runner = parser.parse()?;

    runner.run(format!("::{function}").as_str(), args)
}