add more details to readme

README.md

@@ -1,5 +1,133 @@
-# monkey
+# monkey-rs
 
 ![Rust](https://github.com/binoyjayan/monkey-rs/actions/workflows/rust.yaml/badge.svg)
 
-Interpreter for the monkey programming language
+🦀 🦀 🦀 A Rust port of the Interpreter for the monkey programming language by Thorsten Ball 🦀 🦀 🦀
+
+## Features
+
+- **REPL**: A Read-Eval-Print-Loop (REPL)
+- Tokenizer and parser that parses code into an AST
+- An expression evaluator to evaluate the AST
+- A bytecode compiler that compiles the same AST into bytecode
+- A virtual machine to execute the bytecode
+- A byte code disassembler for debugging
+
+## Language features
+
+- Numeric, string, boolean, arrays, and maps
+- Global and local bindings
+- User defined and higher order functions
+- Closures and access to surrounding variables
+- Builtin functions to manipulate objects and strings
+
+## Build and test
+
+### Run tests
+
+It has decent test coverage for all the modules, including tests for
+the scanner, parser, evaluator, opcode definitions, compiler,
+virtual machine, and built-ins.
+
+```bash
+cargo test
+```
+
+### Run examples
+
+```bash
+cargo run --release examples/formatted-output.mky
+cargo run --release examples/recursive-fibonacci.mky
+```
+
+### Run the REPL
+
+Run an interactive REPL loop to execute program statements
+on the terminal one at a time and see the output immediately.
+
+```bash
+cargo run --release
+```
+```
+>> 1 + 2
+3
+```
+
+
+### Create a release build
+
+Build release with default options
+
+```bash
+cargo build --release
+```
+
+
+This will create a release binary in the './target/release' directory.
+
+### Bytecode compiler vs expression evaluator
+
+By default, the AST generated by the parser is compiled into a bytecode
+that is later executed by a bytecode virtual machine. To evaluate the AST
+directly without compilation, set the environment 'AST_EVAL' to true.
+Note that 'AST_EVAL' is a runtime option and not a compile time one.
+
+```bash
+AST_EVAL=true cargo run --release
+```
+
+
+### Additional build options
+
+#### debug_print_code
+
+The option helps building source with source code disassembly enabled.
+
+Build with the option:
+
+```bash
+cargo build --release --features  'debug_print_code'
+```
+
+Run the REPL:
+
+```bash
+cargo run --release --features  'debug_print_code'
+```
+```
+...
+
+>> 1 + 2
+--------- Instructions [len: 8   ] -------------------
+0000 OpConstant 0
+0003 OpConstant 1
+0006 OpAdd
+0007 OpPop
+------------------------------------------------------
+----------- Constants [len: 2   ] --------------------
+[0] 1
+[1] 2
+------------------------------------------------------
+3
+```
+
+Run an example:
+
+```bash
+cargo run --release --features  'debug_print_code' examples/recursive-fibonacci.mky
+```
+
+#### debug_trace_execution
+
+This option helps build the release for tracing program execution and
+examining the state of the stack.
+
+```bash
+cargo build --release --features  'debug_trace_execution'
+```
+
+
+## Examples
+
+- **Examples** may be found in the  [examples](./examples) directory
+- More examples may be found in [VM Tests](./src/vm/tests.rs)