[← Back to Index](index.md)

---

# Clojure/Nim User Guide

## Installation

### Prerequisites
- Nim >= 2.0
- GCC or Clang
- make

### Build from Source
```bash
git clone https://gitlab.com/balvatar/lisp-nim.git
cd lisp-nim
make build
```

## CLI Commands

### `compile` — Compile to Nim
```bash
./cljnim compile input.clj output.nim
```
Generates a `.nim` file from Clojure source.

### `run` — Compile and Execute
```bash
./cljnim run examples/hello.clj
```
Compiles to Nim, then to C, then to a binary, and runs it.

### `read` — Parse and Print AST
```bash
./cljnim read examples/hello.clj
```
Shows the Clojure AST as S-expressions.

### `repl` — Interactive REPL
```bash
# Human-friendly mode
./cljnim repl

# AI mode (structured JSON)
./cljnim repl --json
```

## Writing Clojure/Nim Programs

### Basic Syntax
```clojure
; Comments start with semicolon

; Define a variable
(def x 42)

; Define a function
(defn greet [name]
  (println "Hello, " name))

; Call a function
(greet "World")

; Arithmetic
(+ 1 2 3)      ; => 6
(* 10 20)      ; => 200
(/ 100 4)      ; => 25

; Conditionals
(if (> x 0)
  "positive"
  "non-positive")

; Local bindings
(let [a 10
      b 20]
  (+ a b))     ; => 30
```

### Working with Data
```clojure
; Vectors (use Nim seq internally)
(def nums [1 2 3 4 5])

; Keywords
(def person {:name "Alice" :age 30})

; Maps and sets use persistent HAMT data structures
; with structural sharing and O(log₃₂ n) operations.
```

### Recursion
```clojure
(defn factorial [n]
  (if (= n 0)
    1
    (* n (factorial (- n 1)))))

(println (factorial 5))  ; => 120
```

## AI REPL Guide

The JSON REPL is designed for programmatic interaction.

### Start AI REPL
```bash
./cljnim repl --json
```

### Evaluate a Form
```json
{"op": "eval", "form": "(+ 1 2 3)"}
```
Response:
```json
{
  "status": "ok",
  "result": {"printed": "6"},
  "meta": {"ns": "user", "ms": 861, "form": "(+ 1 2 3)"}
}
```

### Batch Evaluation
```json
{"op": "eval-batch", "forms": ["(defn f [x] x)", "(f 42)"]}
```

### List Definitions
```json
{"op": "get-defs"}
```
Response:
```json
{"status": "ok", "defs": ["f"], "ns": "user"}
```

### Clear Session
```json
{"op": "clear"}
```

### Exit
```json
{"op": "quit"}
```

## Tips

- Use `:help` in human REPL for available commands.
- Definitions in REPL persist across evaluations in the same session.
- The `--json` flag makes the REPL fully machine-readable.