Content editorial

Author: Ehsan M. Kermani

book/src/01_calculator/ast.md

@@ -1,6 +1,6 @@
 ## Abstract Syntax Tree (AST)
 
-AST comes into picture when we want to go from the string representation of our program like `"-1"` or `"1 + 2"` to something more manageable and easier to work with. Since our program is not a random string (the grammar is for), we can use the structure within the expressions like `"-1"` and `"1 + 2"` to our own advantage and come up with a *new representation* like a [tree](https://en.wikipedia.org/wiki/Tree_structure)
+AST comes into picture when we want to go from the string representation of our program like `"-1"` or `"1 + 2"` to something more manageable and easier to work with. Since our program is not a random string (the grammar is for), we can use the structure within the expressions `"-1"` and `"1 + 2"` to our own advantage and come up with a *new representation* like a [tree](https://en.wikipedia.org/wiki/Tree_structure)
 
 <p align="center">
   </br>
@@ -73,13 +73,13 @@ in later stages of compilation.
 
 ## Interpreter
 
-CPU is the *ultimate interpreter*. That is, it executes opcodes as it goes. After we have changed the representation (aka *lowered* the representation) of our source code `&str` to AST `Node` the a basic interpreter looks and each node of the AST (via any [tree traversal methods](https://en.wikipedia.org/wiki/Tree_traversal)) and simply **evaluates** it *recursively*
+CPU is the *ultimate interpreter*. That is, it executes opcodes as it goes. To do that, after we have changed the representation (aka *lowered* the representation) of our source code `&str` to AST `Node`, a basic interpreter looks and each node of the AST (via any [tree traversal methods](https://en.wikipedia.org/wiki/Tree_traversal)) and simply **evaluates** it *recursively*
 
 ```rust,ignore
 {{#include ../../../calculator/src/compiler/interpreter.rs:interpreter_eval}}
 ```
 
-To sum up, we can define a `Compile` trait
+To sum up, we define a `Compile` trait
 
 ```rust,ignore
 {{#include ../../../calculator/src/lib.rs:compile_trait}}

book/src/01_calculator/ast_traversal.md

@@ -3,7 +3,7 @@
 Recall from the previous section that JITing our [add function](./basic_llvm.md) was very detailed and cumbersome to write. Fortunately, there are some useful patterns for traversing complicated ASTs (and IRs)
 
 * **Builder pattern**
-* **Visitor pattern** (Will introduce it in chapter 4)
+* **Visitor pattern** (Will be introduced in chapter 4)
 
 ### Builder Pattern
 
@@ -26,3 +26,9 @@ and similar to our addition example, we can JIT the builder output
 {{#include ../../../calculator/src/compiler/jit.rs:jit_ast}}
 ```
 <span class="filename">Filename: calculator/src/compiler/jit.rs</span>
+
+Finally, we can test it
+
+```rust,ignore
+assert_eq!(Jit::from_source("1 + 2").unwrap(), 3)
+```

book/src/01_calculator/basic_llvm.md

@@ -3,13 +3,13 @@
 
 ### Setup
 
-The code is available in [`calculator/examples/llvm/src/main.rs`](../../../calculator/examples/llvm/src/main.rs). Because my `llvm-config --version` shows `10.0.0` so I'm using `branch = "llvm=10-0"` in inkwell
+The code is available in [`calculator/examples/llvm/src/main.rs`](https://github.com/ehsanmok/create-your-own-lang-with-rust/blob/master/calculator/examples/llvm/src/main.rs). Because my `llvm-config --version` shows `10.0.0` so I'm using `branch = "llvm=10-0"` in inkwell
 
 ```text
 inkwell = { git = "https://github.com/TheDan64/inkwell", branch = "llvm10-0" }
 ```
 
-Go to [`calculator/examples/llvm` crate](../../../calculator/examples/llvm/) and `cargo run`.
+Go to [`calculator/examples/llvm`](https://github.com/ehsanmok/create-your-own-lang-with-rust/blob/master/calculator/examples/llvm/) sub-crate and `cargo run`.
 
 
 ### Add Function
@@ -30,7 +30,7 @@ Here is how to *stitch* our add function in LLVM
 {{#include ../../../calculator/examples/llvm/src/main.rs:first}}
 ```
 
-2. We define the signature of `add(i32, i32) -> i32`, add the function to our module, create a [basic block]((https://thedan64.github.io/inkwell/inkwell/basic_block/index.html)) entry point and a builder to add later parts
+2. We define the signature of `add(i32, i32) -> i32`, add the function to our module, create a [basic block](https://thedan64.github.io/inkwell/inkwell/basic_block/index.html) entry point and a builder to add later parts
 
 ```rust,ignore
 

book/src/01_calculator/calc_intro.md

@@ -4,7 +4,7 @@ Our first programming language is a simple calculator supporting addition and su
 
 If you haven't cloned the [GitHub](https://github.com/ehsanmok/create-your-own-lang-with-rust) repo already, please do and navigate to the `calculator` subdirectory.
 
-To start, we have `1 + 1;` in [examples/simple.calc](../../../calculator/src/examples/simple.calc) where you can compile with
+To start, we have `1 + 1;` in [examples/simple.calc](https://github.com/ehsanmok/create-your-own-lang-with-rust/blob/master/calculator/examples/simple.calc) where you can compile with
 
 ```text
 cargo build --bin main // create the CLI executable for Calc

book/src/01_calculator/grammar_lexer_parser.md

@@ -41,3 +41,5 @@ and does all the steps of the frontend pipeline that we mentioned so that we can
 ```rust,ignore
 CalcParser::parse(Rule::Program, source)
 ```
+
+Before doing that, we need to define our Abstract Syntax Tree (AST) in the [next section](./ast.md).

book/src/01_calculator/jit_intro.md

@@ -1,6 +1,6 @@
 ## Just-In-Time (JIT) Compiler with LLVM
 
-JIT compilation is a combination of Ahead-Of-Time (AOT) compilation and interpretation. As we saw previously, our `Calc` interpreter evaluates AST to values (actual integer `i32` values) but a JIT compiler differs from an interpreter in what it outputs. Intuitively, JIT outputs are like AOT outputs but generated at runtime when traversing the AST (similar to interpreter).
+JIT compilation is a combination of Ahead-Of-Time (AOT) compilation and interpretation. As we saw previously, our `Calc` interpreter evaluates AST to values (actual integer `i32` values) but a JIT compiler differs from an interpreter in what it outputs. Intuitively, JIT outputs are like AOT outputs but generated at runtime when traversing the AST.
 
 ### LLVM
 

book/src/01_calculator/repl.md

@@ -84,7 +84,7 @@ CTRL-C
 
 ## Conclusion
 
-This concludes our [Calculator](./calc_intro.md) chapter. We took advantage of the simplicity of our `Calc` language to cover a lot of topics.
+This concludes our [Calculator](./calc_intro.md) chapter. We took advantage of the simplicity of our `Calc` language to touch on a lot of topics.
 
 Thanks for following along and reading up this far!
 

book/src/01_calculator/vm.md

@@ -39,7 +39,7 @@ We define
 ```
 <span class="filename">Filename: calculator/src/compiler/vm/bytecode.rs</span>
 
-and as an example, here is `"1 + 2"` AST to Bytecode conversion pictorially
+and pictorially, here is how `"1 + 2"` AST to Bytecode conversion would look like
 
 <p align="center">
 </br>
@@ -91,3 +91,15 @@ and with the help of *instruction pointer (IP)*, we execute the Bytecodes as fol
 {{#include ../../../calculator/src/compiler/vm/vm.rs:vm_interpreter}}
 ```
 <span class="filename">Filename: calculator/src/compiler/vm/vm.rs</span>
+
+To examine the generated Bytecodes and run our VM, we can do
+
+```rust,ignore
+let byte_code = Interpreter::from_source(source);
+println!("byte code: {:?}", byte_code);
+let mut vm = VM::new(byte_code);
+vm.run();
+println!("{}", vm.pop_last());
+```
+
+Checkout the [next section](./repl.md) on how to create a REPL for our `Calc` and see some samples of computations.

book/src/intro.md

@@ -7,7 +7,7 @@ This book assumes some basic knowledge of Rust language. Please take a look at t
 
 The accompanying codes and materials for this book are available in [GitHub](https://github.com/ehsanmok/create-your-own-lang-with-rust). To follow along, make sure you have
 
-* [Rust installed](https://www.rust-lang.org/tools/install)
+* [Rust toolchain installed](https://www.rust-lang.org/tools/install)
 * Cloned the repository
 
     ```text