cljrs 0.1.39

clojurust CLI — run, repl, compile, and eval
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80

# cljrs (Clojurust CLI)

The `cljrs` binary — command-line interface for running, compiling, and
interactively exploring clojurust programs.

---

## File layout

```
src/
  main.rs   — CLI entry point: Clap structs, miette error hook, subcommand dispatch
```

---

## CLI reference

```
cljrs <SUBCOMMAND>

Subcommands:
  run      Interpret a .cljrs or .cljc source file
  repl     Start an interactive REPL
  compile  AOT-compile a source file to a native binary
  eval     Evaluate a single Clojure expression and print the result
  test     Run clojure.test tests for one or more namespaces```

`--src-path` may be repeated to add multiple source directories searched by
`require` when resolving namespace names to files.

`--gc-stats [FILE]` is a global flag honoured by the `run`, `eval`, and `test`
subcommands.  At program exit, it prints a snapshot of `cljrs_gc::GC_STATS`
(GC heap allocations, region/bump allocations, GC pause count and total
duration, freed objects/bytes).  With no value the report goes to stdout;
with a path it is written to that file.

### Examples

```bash
cljrs run hello.cljrs
cljrs run main.cljrs --src-path src --src-path lib
cljrs repl --src-path src
cljrs compile app.cljrs -o app
cljrs eval '(+ 1 2)'
cljrs test --src-path src/ --src-path test/ my-ns.my-tests

# GC stats:
cljrs run main.cljrs --gc-stats              # → stdout
cljrs eval '(reduce + (range 1e6))' --gc-stats stats.txt
cljrs test --src-path test/ --gc-stats /tmp/test-gc.log
```

---

## Implementation notes

- Argument parsing uses [Clap](https://docs.rs/clap) derive macros (`Parser`,
  `Subcommand`).
- The miette error hook is installed at startup so that any `CljxError`
  propagated to `main` renders with terminal-linked source snippets.
- All subcommand handlers currently print `[not yet implemented]` to stderr;
  they will be filled in as `cljrs-reader`, `cljrs-eval`, `cljrs-compiler`, and
  `cljrs-runtime` reach their respective phases.

---

## Dependencies

| Crate | Role |
|-------|------|
| `cljrs-types` (workspace) | `CljxError` — error type for `miette::Result` propagation |
| `cljrs-gc` (workspace) | GC (initialisation at startup, future phases) |
| `cljrs-reader` (workspace) | Lexer + parser (future phases) |
| `cljrs-eval` (workspace) | Interpreter (future phases) |
| `cljrs-runtime` (workspace) | Standard library (future phases) |
| `cljrs-compiler` (workspace) | JIT/AOT (future phases) |
| `cljrs-interop` (workspace) | Rust interop (future phases) |
| `clap` (workspace) | CLI argument parsing |
| `miette` (workspace) | Rich terminal error rendering |