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
```
