diff --git a/miden/src/repl/mod.rs b/miden/src/repl/mod.rs index b0c41f4e2..692e29df5 100644 --- a/miden/src/repl/mod.rs +++ b/miden/src/repl/mod.rs @@ -6,141 +6,141 @@ use processor::ContextId; use rustyline::{error::ReadlineError, DefaultEditor}; use stdlib::StdLibrary; -/// This work is in continuation to the amazing work done by team `Scribe` -/// [here](https://github.com/ControlCplusControlV/Scribe/blob/main/transpiler/src/repl.rs#L8) -/// -/// The Miden Read–eval–print loop (REPL) is a Miden shell that allows for quick and easy debugging -/// of Miden assembly. To use the repl, simply type "miden repl" after building it with feature -/// "executable" (cargo build --release --feature executable) when in the miden home -/// crate and the repl will launch. After the REPL gets initialized, you can execute any Miden -/// instruction, undo executed instructions, check the state of the stack and memory at a given -/// point, and do many other useful things! When the REPL is exited, a `history.txt` file is saved. -/// One thing to note is that all the REPL native commands start with an `!` to differentiate them -/// from regular assembly instructions. -/// -/// Miden Instructions -/// All Miden instructions mentioned in the -/// [Miden Assembly section](https://0xpolygonmiden.github.io/miden-vm/user_docs/assembly/main.html) -/// are valid. -/// One can either input instructions one by one or multiple instructions in one input. -/// For example, the below two commands will result in the same output. -/// >> push.1 -/// >> push.2 -/// >> push.3 -/// -/// >> push.1 push.2 push.3 -/// -/// In order to execute a control flow operation, one needs to write the entire flow operation in -/// a single line with spaces between individual operations. -/// Ex. -/// ``` -/// repeat.20 -/// pow2 -/// end -/// ``` -/// should be written as -/// `repeat.20 pow2 end` -/// -/// To execute a control flow operation, one must write the entire statement in a single line with -/// spaces between individual operations. -/// ``` -/// >> repeat.20 -/// pow2 -/// end -/// ``` -/// -/// The above example should be written as follows in the REPL tool: -/// >> repeat.20 pow2 end -/// -/// `!stack` -/// The `!stack` command prints out the state of the stack at the last executed instruction. Since -/// the stack always contains at least 16 elements, 16 or more elements will be printed out (even -/// if all of them are zeros). -/// >> push.1 push.2 push.3 push.4 push.5 -/// >> exp -/// >> u32wrapping_mul -/// >> swap -/// >> eq.2 -/// >> assert -/// -/// The `!stack` command will print out the following state of the stack: -/// ``` -/// >> !stack -/// 3072 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 -/// ``` -/// -/// `!undo` -/// The `!undo` command reverts to the previous state of the stack and memory by dropping off the -/// last executed assembly instruction from the program. One could use `!undo` as often as they want -/// to restore the state of a stack and memory $n$ instructions ago (provided there are $n$ -/// instructions in the program). The `!undo` command will result in an error if no remaining -/// instructions are left in the miden program. -/// ``` -/// >> push.1 push.2 push.3 -/// >> push.4 -/// >> !stack -/// 4 3 2 1 0 0 0 0 0 0 0 0 0 0 0 0 -/// >> push.5 -/// >> !stack -/// 5 4 3 2 1 0 0 0 0 0 0 0 0 0 0 0 -/// >> !undo -/// 4 3 2 1 0 0 0 0 0 0 0 0 0 0 0 0 -/// >> !undo -/// 3 2 1 0 0 0 0 0 0 0 0 0 0 0 0 0 -/// ``` -/// -///`!program` -/// The `!program` command prints out the entire miden program getting executed. E.g., in the below -/// ``` -/// scenario: >> push.1 -/// >> push.2 -/// >> push.3 -/// >> add -/// >> add -/// >> !program -/// begin -/// push.1 -/// push.2 -/// push.3 -/// add -/// add -/// end -/// ``` -/// -/// `!help` -/// The `!help` command prints out all the available commands in the REPL tool. -/// -/// `!mem` -/// The `!mem` command prints out the contents of all initialized memory locations. For each such -/// location, the address, along with its memory values, is printed. Recall that four elements are -/// stored at each memory address. -/// If the memory has at least one value that has been initialized: -/// ``` -/// >> !mem -/// 7: [1, 2, 0, 3] -/// 8: [5, 7, 3, 32] -/// 9: [9, 10, 2, 0] -/// ``` -/// -/// If the memory is not yet been initialized: -/// ``` -/// >> !mem -/// The memory has not been initialized yet -/// ``` -/// -/// `!mem[addr]` -/// The `!mem[addr]` command prints out memory contents at the address specified by `addr`. -/// If the `addr` has been initialized: -/// ``` -/// >> !mem[9] -/// 9: [9, 10, 2, 0] -/// ``` -/// -/// If the `addr` has not been initialized: -/// ``` -/// >> !mem[87] -/// Memory at address 87 is empty -/// ``` +// This work is in continuation to the amazing work done by team `Scribe` +// [here](https://github.com/ControlCplusControlV/Scribe/blob/main/transpiler/src/repl.rs#L8) +// +// The Miden Read–eval–print loop (REPL) is a Miden shell that allows for quick and easy debugging +// of Miden assembly. To use the repl, simply type "miden repl" after building it with feature +// "executable" (cargo build --release --feature executable) when in the miden home +// crate and the repl will launch. After the REPL gets initialized, you can execute any Miden +// instruction, undo executed instructions, check the state of the stack and memory at a given +// point, and do many other useful things! When the REPL is exited, a `history.txt` file is saved. +// One thing to note is that all the REPL native commands start with an `!` to differentiate them +// from regular assembly instructions. +// +// Miden Instructions +// All Miden instructions mentioned in the +// [Miden Assembly section](https://0xpolygonmiden.github.io/miden-vm/user_docs/assembly/main.html) +// are valid. +// One can either input instructions one by one or multiple instructions in one input. +// For example, the below two commands will result in the same output. +// >> push.1 +// >> push.2 +// >> push.3 +// +// >> push.1 push.2 push.3 +// +// In order to execute a control flow operation, one needs to write the entire flow operation in +// a single line with spaces between individual operations. +// Ex. +// ``` +// repeat.20 +// pow2 +// end +// ``` +// should be written as +// `repeat.20 pow2 end` +// +// To execute a control flow operation, one must write the entire statement in a single line with +// spaces between individual operations. +// ``` +// >> repeat.20 +// pow2 +// end +// ``` +// +// The above example should be written as follows in the REPL tool: +// >> repeat.20 pow2 end +// +// `!stack` +// The `!stack` command prints out the state of the stack at the last executed instruction. Since +// the stack always contains at least 16 elements, 16 or more elements will be printed out (even +// if all of them are zeros). +// >> push.1 push.2 push.3 push.4 push.5 +// >> exp +// >> u32wrapping_mul +// >> swap +// >> eq.2 +// >> assert +// +// The `!stack` command will print out the following state of the stack: +// ``` +// >> !stack +// 3072 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 +// ``` +// +// `!undo` +// The `!undo` command reverts to the previous state of the stack and memory by dropping off the +// last executed assembly instruction from the program. One could use `!undo` as often as they want +// to restore the state of a stack and memory $n$ instructions ago (provided there are $n$ +// instructions in the program). The `!undo` command will result in an error if no remaining +// instructions are left in the miden program. +// ``` +// >> push.1 push.2 push.3 +// >> push.4 +// >> !stack +// 4 3 2 1 0 0 0 0 0 0 0 0 0 0 0 0 +// >> push.5 +// >> !stack +// 5 4 3 2 1 0 0 0 0 0 0 0 0 0 0 0 +// >> !undo +// 4 3 2 1 0 0 0 0 0 0 0 0 0 0 0 0 +// >> !undo +// 3 2 1 0 0 0 0 0 0 0 0 0 0 0 0 0 +// ``` +// +//`!program` +// The `!program` command prints out the entire miden program getting executed. E.g., in the below +// ``` +// scenario: >> push.1 +// >> push.2 +// >> push.3 +// >> add +// >> add +// >> !program +// begin +// push.1 +// push.2 +// push.3 +// add +// add +// end +// ``` +// +// `!help` +// The `!help` command prints out all the available commands in the REPL tool. +// +// `!mem` +// The `!mem` command prints out the contents of all initialized memory locations. For each such +// location, the address, along with its memory values, is printed. Recall that four elements are +// stored at each memory address. +// If the memory has at least one value that has been initialized: +// ``` +// >> !mem +// 7: [1, 2, 0, 3] +// 8: [5, 7, 3, 32] +// 9: [9, 10, 2, 0] +// ``` +// +// If the memory is not yet been initialized: +// ``` +// >> !mem +// The memory has not been initialized yet +// ``` +// +// `!mem[addr]` +// The `!mem[addr]` command prints out memory contents at the address specified by `addr`. +// If the `addr` has been initialized: +// ``` +// >> !mem[9] +// 9: [9, 10, 2, 0] +// ``` +// +// If the `addr` has not been initialized: +// ``` +// >> !mem[87] +// Memory at address 87 is empty +// ``` /// Initiates the Miden Repl tool. pub fn start_repl(library_paths: &Vec, use_stdlib: bool) { @@ -295,8 +295,8 @@ pub fn start_repl(library_paths: &Vec, use_stdlib: bool) { .expect("Couldn't dump the program into the history file"); } -/// HELPER METHODS -/// -------------------------------------------------------------------------------------------- +// HELPER METHODS +// -------------------------------------------------------------------------------------------- /// Compiles and executes a compiled Miden program, returning the stack, memory and any Miden /// errors. The program is passed in as a String, passed to the Miden Assembler, and then passed