Skip to content

Commit fe35fc7

Browse files
bethropolisbethropolis
committed
feat: add CLI reference documentation and update existing guides to reflect mimo command usage, formatting, and testing.
1 parent cc695db commit fe35fc7

5 files changed

Lines changed: 322 additions & 23 deletions

File tree

‎docs/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ A minimal prefix-notation programming language.
1414
## Quick Links
1515

1616
- [Syntax Guide](syntax-guide.md) - Complete language reference
17+
- [CLI Reference](cli.md) - All commands, flags, and examples
1718
- [Testing Guide](testing.md) - How to test Mimo programs
1819

1920
## Language Reference

‎docs/_sidebar.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
* Getting Started
22
* [Overview](README.md)
33
* [Syntax Guide](syntax-guide.md)
4+
* [CLI Reference](cli.md)
45
* [Testing](testing.md)
56
* Language Reference
67
* [Variables](syntax/variables.md)

‎docs/cli.md‎

Lines changed: 267 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,267 @@
1+
# CLI Reference
2+
3+
The Mimo Language Toolkit is invoked via the `mimo` command (or `bun bin/cli.js` in the source tree).
4+
5+
```
6+
mimo <command> [options]
7+
mimo <file>
8+
```
9+
10+
---
11+
12+
## Global Options
13+
14+
| Flag | Description |
15+
|------|-------------|
16+
| `--version`, `-v` | Print the version number and exit |
17+
| `--help`, `-h` | Show global help |
18+
| `--eval <code>`, `-e <code>` | Evaluate a string of Mimo code |
19+
| `-` | Read and execute Mimo code from STDIN |
20+
21+
### Per-command help
22+
23+
Every command supports `--help`. Either of the following works:
24+
25+
```bash
26+
mimo help <command>
27+
mimo <command> --help
28+
```
29+
30+
### Colored output
31+
32+
Output is colored automatically when stdout is a TTY. Set `NO_COLOR=1` to suppress ANSI codes unconditionally.
33+
34+
---
35+
36+
## Commands
37+
38+
### `run`
39+
40+
Execute a Mimo source file.
41+
42+
```bash
43+
mimo run <file>
44+
mimo <file> # shorthand — file is run directly
45+
```
46+
47+
Passing `-` or piping via STDIN also works:
48+
49+
```bash
50+
echo 'show + 1 2' | mimo
51+
mimo -
52+
```
53+
54+
**Exit codes:** `0` on success, `1` on parse or runtime error.
55+
56+
---
57+
58+
### `repl`
59+
60+
Start the interactive Read-Eval-Print Loop.
61+
62+
```bash
63+
mimo repl
64+
```
65+
66+
The REPL supports multiline input, command history (`.mimo_history`), and special commands:
67+
68+
| Command | Description |
69+
|---------|-------------|
70+
| `:load <file>` | Load and evaluate a `.mimo` file |
71+
| `:ast <expr>` | Print the AST for an expression |
72+
| `:time <expr>` | Time the evaluation of an expression |
73+
| `:save <file>` | Save session history to a file |
74+
75+
---
76+
77+
### `fmt`
78+
79+
Format `.mimo` source files using the canonical pretty-printer.
80+
81+
```bash
82+
mimo fmt [options] [paths...]
83+
echo "code" | mimo fmt
84+
```
85+
86+
| Option | Description |
87+
|--------|-------------|
88+
| `--write` | Write formatted output back to files in place |
89+
| `--check` | Exit with code `1` if any file is not already formatted (CI mode) |
90+
| `--quiet` | Suppress all output except errors |
91+
| `--verbose` | Show each file's status even when unchanged |
92+
93+
**Examples:**
94+
95+
```bash
96+
# Preview formatting (does not modify files)
97+
mimo fmt src/
98+
99+
# Format all files in place
100+
mimo fmt --write src/
101+
102+
# CI check — fails if any file needs formatting
103+
mimo fmt --check src/
104+
105+
# Format from STDIN
106+
echo 'show + 1 2' | mimo fmt
107+
```
108+
109+
**Notes:**
110+
- Without `--write` or `--check`, `fmt` prints the formatted output to stdout (preview mode).
111+
- The canonical indentation is **4 spaces**.
112+
- The formatter is idempotent — running it twice produces the same result.
113+
114+
---
115+
116+
### `lint`
117+
118+
Statically analyse `.mimo` files for common issues.
119+
120+
```bash
121+
mimo lint [options] [paths...]
122+
```
123+
124+
| Option | Description |
125+
|--------|-------------|
126+
| `--fail-on-warning` | Exit `1` on warnings, not just errors |
127+
| `--quiet` | Suppress per-file output; print only the summary line |
128+
| `--verbose` | Show rule IDs alongside each diagnostic message |
129+
| `--json` | Output results as JSON (useful for editor integrations) |
130+
| `--rule:<name>=<bool>` | Override a specific rule on the command line |
131+
132+
**Available rules:**
133+
134+
| Rule | Default | Description |
135+
|------|---------|-------------|
136+
| `no-unused-vars` | on | Variables declared but never read |
137+
| `prefer-const` | on | Variables that could be `const` |
138+
| `no-magic-numbers` | off | Bare numeric literals outside declarations |
139+
| `no-empty-function` | off | Functions with empty bodies |
140+
| `max-depth` | off | Nesting depth exceeds threshold |
141+
| `no-shadow` | off | Variable shadows an outer-scope binding |
142+
| `consistent-return` | off | Inconsistent use of `return` in a function |
143+
144+
**Examples:**
145+
146+
```bash
147+
mimo lint src/
148+
mimo lint --fail-on-warning src/
149+
mimo lint --rule:no-magic-numbers=true src/
150+
mimo lint --json src/ | jq .
151+
```
152+
153+
**Exit codes:** `0` if clean, `1` on errors (or warnings when `--fail-on-warning` is set).
154+
155+
---
156+
157+
### `test`
158+
159+
Discover and run `.mimo` test files, reporting pass/fail per file.
160+
161+
```bash
162+
mimo test [options] [path]
163+
```
164+
165+
| Option | Description |
166+
|--------|-------------|
167+
| `--quiet` | Print only the final summary line |
168+
| `--verbose` | Show captured output even for passing tests |
169+
170+
**File discovery:** the runner picks up `.mimo` files that are inside a directory named `test`, or have `.test.` in their filename.
171+
172+
**Examples:**
173+
174+
```bash
175+
# Run all tests discovered from the current directory
176+
mimo test
177+
178+
# Run tests in a specific directory
179+
mimo test test/source/
180+
181+
# Run a single test file
182+
mimo test test/source/strings.mimo
183+
```
184+
185+
**Exit codes:** `0` if all tests pass, `1` if any fail.
186+
187+
---
188+
189+
### `convert`
190+
191+
Transpile Mimo source to another language.
192+
193+
```bash
194+
mimo convert --in <file> --out <file> --to <target>
195+
```
196+
197+
| Option | Description |
198+
|--------|-------------|
199+
| `--in <file>` | Input `.mimo` file |
200+
| `--out <file>` | Output file path |
201+
| `--to <target>` | Target language: `javascript`, `python`, `alya` |
202+
203+
**Examples:**
204+
205+
```bash
206+
mimo convert --in app.mimo --out app.js --to javascript
207+
mimo convert --in app.mimo --out app.py --to python
208+
```
209+
210+
---
211+
212+
### `doctor`
213+
214+
Validate the Mimo runtime environment and report any issues.
215+
216+
```bash
217+
mimo doctor
218+
```
219+
220+
Checks performed:
221+
222+
| Check | Description |
223+
|-------|-------------|
224+
| Adapter API | All required host-adapter methods are present |
225+
| Bun runtime | Bun version is detectable |
226+
| Filesystem access | Read/write works in the current directory |
227+
| HTTP dependency | `curl` is installed (required by the `http` stdlib module) |
228+
| Interpreter smoke test | Basic evaluation (`+ 1 2`) succeeds |
229+
| Stdlib module registry | All built-in stdlib modules resolve correctly |
230+
231+
**Exit codes:** `0` (PASS), `0` (PASS WITH WARNINGS), `1` (FAILED).
232+
233+
---
234+
235+
### `help`
236+
237+
Show global help or per-command help.
238+
239+
```bash
240+
mimo help
241+
mimo help <command>
242+
```
243+
244+
---
245+
246+
## `--eval` / `-e`
247+
248+
Evaluate a snippet of Mimo code directly on the command line without creating a file.
249+
250+
```bash
251+
mimo -e "show + 1 2"
252+
mimo --eval "set x 10 show * x x"
253+
```
254+
255+
**Exit codes:** `0` on success, `1` on error.
256+
257+
---
258+
259+
## STDIN
260+
261+
Pipe Mimo code into the toolkit via STDIN. Equivalent to `mimo run`:
262+
263+
```bash
264+
echo 'show "hello"' | mimo
265+
cat program.mimo | mimo
266+
mimo -
267+
```

‎docs/syntax/style-guide.md‎

Lines changed: 23 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -23,17 +23,9 @@ end
2323

2424
## Indentation
2525

26-
Use consistent indentation (2 or 4 spaces):
26+
Use 4 spaces per level. This is what `mimo fmt` produces and enforces:
2727

2828
```mimo
29-
// 2-space indentation
30-
if > x 0
31-
if < x 100
32-
show "in range"
33-
end
34-
end
35-
36-
// 4-space indentation
3729
if > x 0
3830
if < x 100
3931
show "in range"
@@ -114,3 +106,25 @@ end
114106
call process(10) -> result
115107
show result
116108
```
109+
110+
## Formatter
111+
112+
Mimo ships with a built-in formatter (`mimo fmt`) that enforces the conventions in this guide automatically. The canonical style is:
113+
114+
- **4 spaces** per indent level
115+
- Blank lines around block-level constructs (`if`, `while`, `for`, `function`, `try`, `match`)
116+
- Long arrays and objects (> 4 elements or > 80–100 chars) expanded to multiline
117+
- Double-quoted strings
118+
119+
```bash
120+
# Preview formatted output (does not modify files)
121+
mimo fmt src/
122+
123+
# Format in place
124+
mimo fmt --write src/
125+
126+
# CI check — exit 1 if any file needs formatting
127+
mimo fmt --check src/
128+
```
129+
130+
Running `mimo fmt --write` on your codebase is the easiest way to bring it into conformance with this guide. See the [CLI Reference](../cli.md) for full flag documentation.

0 commit comments

Comments
 (0)