Using the Mech REPL
===============================================================================
The Mech Read-Eval-Print-Loop (REPL) provides an interactive environment for executing Mech commands, inspecting symbols, and debugging programs.
Below are the available REPL commands.
1. Starting the REPL
-------------------------------------------------------------------------------
To start the REPL, run:
```sh
mech
```
You can load a script into the REPL by running with the `--repl` option:
```sh
mech my_script.mec --repl
```
Once inside, you can enter commands prefixed with `:`, otherwise the REPL will interpret the input as a Mech expression, evaluate it, and print the result with the associated type.
2. Commands
-------------------------------------------------------------------------------
(a) `:cd PATH`
Changes the current working directory.
```sh
:cd /my/directory
```
(b) `:clc` (`:c`)
Clears the screen, resets the cursor position.
```sh
:clc
```
(c) `:clear`
Clears the interpreter state. If a target variable is provided, only that variable is cleared.
```sh
:clear
:clear x
```
(c) `:docs [NAME]` (`:d`)
Displays documentation for the specified name.
```sh
:docs install
:docs math/sin
```
(d) `:help` (`:h`)
Displays this help message with a list of available commands.
```sh
:help
```
(e) `:load`
Loads and executes the supplied Mech file(s) into the session.
```sh
:load my_script.mec
:load my_script.mec my_other_script.mec
:load my_directory
```
(f) `:ls [PATH]`
Lists contents of working directory. Optionally, provide a target path.
```sh
:ls
:ls /my/directory
```
(g) `:plan` (`:p`)
Displays the execution plan.
```sh
:plan
```
(h) `:quit` (`:q`)
Exits the REPL.
```sh
:quit
```
(i) `:step [N]`
Iterates the execution plan by the specified number of steps. If N is not provided, defaults to 1 step.
```sh
~x := 10
x += 1
:step 10
x == 21 -- true
```
(j) `:symbols` (`:s`)
Searches for symbols in the current session. You can provide an optional search pattern to filter results.
```sh
:s
:s velocity
```
(k) `:whos` (`:w`)
Searches the symbol directory. Optionally, provide a search pattern to filter results.
```sh
:whos
:whos position
```