# Ръководство за Потребителя — Clojure/Nim

## Инсталация

### Изисквания
- Nim >= 2.0
- GCC или Clang
- make

### Изграждане от Източник
```bash
git clone https://gitlab.com/balvatar/lisp-nim.git
cd lisp-nim
make build
```

## CLI Команди

### `compile` — Компилиране до Nim
```bash
./cljnim compile input.clj output.nim
```
Генерира `.nim` файл от Clojure изходен код.

### `run` — Компилиране и Изпълнение
```bash
./cljnim run examples/hello.clj
```
Компилира до Nim, после до C, после до бинарен файл, и го изпълнява.

### `read` — Парсиране и Отпечатване на AST
```bash
./cljnim read examples/hello.clj
```
Показва Clojure AST като S-изрази.

### `repl` — Интерактивен REPL
```bash
# Човешки режим
./cljnim repl

# AI режим (структуриран JSON)
./cljnim repl --json
```

## Писане на Clojure/Nim Програми

### Базов Синтаксис
```clojure
; Коментарите започват с точка и запетая

; Дефиниране на променлива
(def x 42)

; Дефиниране на функция
(defn greet [name]
  (println "Здравей, " name))

; Извикване на функция
(greet "Свят")

; Аритметика
(+ 1 2 3)      ; => 6
(* 10 20)      ; => 200
(/ 100 4)      ; => 25

; Условни изрази
(if (> x 0)
  "положително"
  "неположително")

; Локални обвързвания
(let [a 10
      b 20]
  (+ a b))     ; => 30
```

### Работа с Данни
```clojure
; Вектори (използват Nim seq вътрешно)
(def nums [1 2 3 4 5])

; Ключови думи
(def person {:name "Алиса" :age 30})

; В момента картите и множествата са ограничени.
; Пълни persistent структури (HAMT) са в разработка.
```

### Рекурсия
```clojure
(defn factorial [n]
  (if (= n 0)
    1
    (* n (factorial (- n 1)))))

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

## Ръководство за AI REPL

JSON REPL е проектиран за програмно взаимодействие.

### Стартиране на AI REPL
```bash
./cljnim repl --json
```

### Оценка на Форма
```json
{"op": "eval", "form": "(+ 1 2 3)"}
```
Отговор:
```json
{
  "status": "ok",
  "result": {"printed": "6"},
  "meta": {"ns": "user", "ms": 861, "form": "(+ 1 2 3)"}
}
```

### Batch Оценка
```json
{"op": "eval-batch", "forms": ["(defn f [x] x)", "(f 42)"]}
```

### Листване на Дефиниции
```json
{"op": "get-defs"}
```
Отговор:
```json
{"status": "ok", "defs": ["f"], "ns": "user"}
```

### Изчистване на Сесия
```json
{"op": "clear"}
```

### Изход
```json
{"op": "quit"}
```

## Съвети

- Използвайте `:help` в човешки REPL за налични команди.
- Дефинициите в REPL се запазват през оценките в рамките на една сесия.
- Флагът `--json` прави REPL изцяло машинно-четим.