docs: reorganize into en/ and bg/ subfolders with numbered indices
- New docs/index.md with language selector - docs/en/ — 01-getting-started, 02-architecture, 03-ai-integration, 04-api-reference, 05-user-guide, 06-roadmap - docs/bg/ — same structure in Bulgarian - Root README.md trimmed to quick-start + links to docs/ - Removed old flat docs/ files (ARCHITECTURE.md, AI_FIRST.md, etc.) - Added swap!/reset! examples to getting-started guides
This commit is contained in:
@@ -0,0 +1,127 @@
|
||||
|
||||
[← Към индекса](index.md)
|
||||
|
||||
---
|
||||
|
||||
# Първи стъпки
|
||||
|
||||
> Диалект на Clojure, който се компилира до Nim → C → нативен бинарен файл.
|
||||
|
||||
## Изисквания
|
||||
|
||||
- **Nim** >= 2.0.0
|
||||
- **GCC** или **Clang**
|
||||
- **make**
|
||||
- **curl** (за AI функциите, незадължително)
|
||||
|
||||
## Инсталация
|
||||
|
||||
```bash
|
||||
git clone https://gitlab.com/balvatar/lisp-nim.git
|
||||
cd lisp-nim
|
||||
make build
|
||||
```
|
||||
|
||||
## Проверка
|
||||
|
||||
```bash
|
||||
make check # компилация + 276+ теста + всички примери
|
||||
```
|
||||
|
||||
## CLI Команди
|
||||
|
||||
| Команда | Описание |
|
||||
|---------|----------|
|
||||
| `./cljnim compile <file.clj>` | Компилиране до Nim изходен код |
|
||||
| `./cljnim compile-lib <file.clj>` | Компилиране с експортирани функции (`*`) |
|
||||
| `./cljnim run <file.clj>` | Компилиране и изпълнение |
|
||||
| `./cljnim read <file.clj>` | Парсиране и печат на AST |
|
||||
| `./cljnim repl` | Стартиране на човешки REPL |
|
||||
| `./cljnim repl --json` | JSON REPL (за AI агенти) |
|
||||
| `./cljnim deps` | Разрешаване на зависимости от `deps.edn` |
|
||||
| `./cljnim -e '<код>'` | Оценка на израз |
|
||||
| `./cljnim ai '<описание>'` | Генериране на Clojure код с AI |
|
||||
|
||||
## Бързи примери
|
||||
|
||||
### Hello World
|
||||
```clojure
|
||||
;; examples/hello.clj
|
||||
(println "Hello, Nim world!")
|
||||
(println (+ 1 2 3))
|
||||
```
|
||||
|
||||
```bash
|
||||
$ ./cljnim run examples/hello.clj
|
||||
Hello, Nim world!
|
||||
6
|
||||
```
|
||||
|
||||
### Функции и рекурсия
|
||||
```clojure
|
||||
(defn square [x] (* x x))
|
||||
(defn factorial [n]
|
||||
(if (= n 0)
|
||||
1
|
||||
(* n (factorial (- n 1)))))
|
||||
|
||||
(let [a 5]
|
||||
(println (square a))
|
||||
(println (factorial a)))
|
||||
```
|
||||
|
||||
### loop/recur
|
||||
```clojure
|
||||
(defn sum [n]
|
||||
(loop [acc 0 i 1]
|
||||
(if (> i n)
|
||||
acc
|
||||
(recur (+ acc i) (inc i)))))
|
||||
(println (sum 10)) ;; => 55
|
||||
```
|
||||
|
||||
### Atoms (REPL)
|
||||
```clojure
|
||||
user> (def a (atom 0))
|
||||
user> (swap! a inc)
|
||||
1
|
||||
user> (reset! a 42)
|
||||
42
|
||||
user> (deref a)
|
||||
42
|
||||
```
|
||||
|
||||
## AI Настройка (незадължително)
|
||||
|
||||
```bash
|
||||
export DEEPSEEK_API_KEY="sk-..."
|
||||
# или OPENAI_API_KEY, или MIMO_API_KEY
|
||||
```
|
||||
|
||||
Виж [03-ai-integration.md](03-ai-integration.md) за пълна AI документация.
|
||||
|
||||
## Структура на проекта
|
||||
|
||||
```
|
||||
├── src/ # Изходен код на компилатора
|
||||
│ ├── cljnim.nim # CLI входна точка
|
||||
│ ├── reader.nim # EDN парсер
|
||||
│ ├── emitter.nim # Clojure AST → Nim
|
||||
│ ├── eval.nim # Интерпретатор (REPL бърз път)
|
||||
│ └── ai_assist.nim # AI API интеграция
|
||||
├── lib/ # Runtime библиотеки
|
||||
│ ├── cljnim_runtime.nim # Нативен runtime
|
||||
│ └── cljnim_runtime_js.nim # JS runtime
|
||||
├── tests/ # Тестове (8 файла, 276+ теста)
|
||||
├── examples/ # Примери .clj
|
||||
├── benchmarks/ # Бенчмаркове
|
||||
├── docs/ # Документация
|
||||
└── experiments/ # Web, WASM, native-lib target-и
|
||||
```
|
||||
|
||||
## Следващи стъпки
|
||||
|
||||
- [02-architecture.md](02-architecture.md) — Как работи компилаторът
|
||||
- [03-ai-integration.md](03-ai-integration.md) — AI-асистирана разработка
|
||||
- [04-api-reference.md](04-api-reference.md) — JSON REPL протокол
|
||||
- [05-user-guide.md](05-user-guide.md) — Макроси, interop, напреднали шаблони
|
||||
@@ -0,0 +1,107 @@
|
||||
|
||||
[← Към индекса](index.md)
|
||||
|
||||
---
|
||||
|
||||
# Архитектура на Clojure/Nim
|
||||
|
||||
## Общ Преглед
|
||||
|
||||
Clojure/Nim е **компилатор**, не интерпретатор. Следва модела на ClojureScript: Clojure изходният код се чете, разширява с макроси, анализира и се генерира като Nim изходен код, който после се компилира до C и накрая до native бинарен файл.
|
||||
|
||||
## Компилационен Пайплайн
|
||||
|
||||
```
|
||||
┌─────────────┐
|
||||
│ .clj Файл │
|
||||
└──────┬──────┘
|
||||
│
|
||||
┌────▼────┐
|
||||
│ Reader │ ← EDN парсер. Произвежда Clojure структури от данни.
|
||||
└────┬────┘
|
||||
│
|
||||
┌────▼────┐
|
||||
│ Макроси │ ← Разширение на defmacro. Работи върху Clojure данни.
|
||||
└────┬────┘
|
||||
│
|
||||
┌────▼────┐
|
||||
│Анализатор│ ← Специални форми, locals, анализ на closures.
|
||||
└────┬────┘
|
||||
│
|
||||
┌────▼────┐
|
||||
│ Генератор│ ← Генерира Nim AST / изходен код.
|
||||
└────┬────┘
|
||||
│
|
||||
┌────▼────┐
|
||||
│ Nim CC │ ← Nim → C компилация.
|
||||
└────┬────┘
|
||||
│
|
||||
┌────▼────┐
|
||||
│ C CC │ ← C → машинен код (GCC/Clang).
|
||||
└────┬────┘
|
||||
│
|
||||
┌────▼────┐
|
||||
│ Бинарен│ ← Единичен native изпълним файл.
|
||||
└─────────┘
|
||||
```
|
||||
|
||||
## Ключови Дизайн Решения
|
||||
|
||||
### 1. AOT Компилатор
|
||||
Компилираме предварително (ahead-of-time), като ClojureScript. Това ни дава:
|
||||
- Бързо изпълнение (скорост на C)
|
||||
- Малък размер на бинарния файл
|
||||
- Без overhead на интерпретатор
|
||||
|
||||
Компромисът е, че компилацията в REPL е по-бавна (всяка форма се компилира индивидуално).
|
||||
|
||||
### 2. Clojure Макроси върху Clojure Данни
|
||||
Разширяването на макроси става **преди** да стигнем до Nim. Nim никога не вижда Clojure макроси:
|
||||
|
||||
```clojure
|
||||
(defmacro unless [condition & body]
|
||||
`(if (not ~condition)
|
||||
(do ~@body)))
|
||||
```
|
||||
|
||||
Този макро оперира върху `CljVal` обекти (Clojure списъци, символи), не върху Nim AST.
|
||||
|
||||
### 3. Runtime в Nim
|
||||
Модулът `lib/cljnim_runtime.nim` предоставя:
|
||||
- `CljVal` — tagged union, представящ всички Clojure стойности
|
||||
- `cljAdd`, `cljMul`, и т.н. — полиморфна аритметика
|
||||
- `cljRepr` — текстово представяне
|
||||
|
||||
### 4. Nim Interop
|
||||
Вместо Java interop, имаме директен Nim interop:
|
||||
|
||||
```clojure
|
||||
(nim/math/sin x)
|
||||
(nim/strutils/toUpper s)
|
||||
```
|
||||
|
||||
Nim модулите се импортират автоматично при извикване през `nim/module/fn` шаблона.
|
||||
|
||||
## Отговорности на Модулите
|
||||
|
||||
| Модул | Роля |
|
||||
|---|---|
|
||||
| `src/reader.nim` | Парсира `.clj` текст към `CljVal` AST |
|
||||
| `src/emitter.nim` | Трансформира `CljVal` AST в Nim изходен код |
|
||||
| `src/repl.nim` | Имплементация на human и AI REPL |
|
||||
| `src/eval.nim` | Tree-walking interpreter за бързо in-memory eval |
|
||||
| `src/deps.nim` | Резолюция на зависимости (deps.edn формат) |
|
||||
| `src/core.nim` | Core runtime функции (AOT компилирани) |
|
||||
| `src/types.nim` | Типове на AST възли (използват се от reader/emitter) |
|
||||
| `src/macros.nim` | Двигател за разширяване на макроси |
|
||||
| `src/runtime.nim` | Допълнителни runtime помощници |
|
||||
| `lib/cljnim_runtime.nim` | Основна runtime библиотека |
|
||||
| `lib/cljnim_pvec.nim` | Persistent Vector (HAMT имплементация) |
|
||||
| `lib/cljnim_pmap.nim` | Persistent Hash Map (HAMT имплементация) |
|
||||
| `lib/cljnim_async.nim` | core.async channels runtime |
|
||||
|
||||
## Модел на Паметта
|
||||
|
||||
- Използва Nim's ORC garbage collector
|
||||
- `CljVal` е `ref object` (заделя се на heap)
|
||||
- Persistent структури от данни (Vector, Map, Set) използват структурно споделяне през HAMT
|
||||
@@ -0,0 +1,112 @@
|
||||
|
||||
[← Към индекса](index.md)
|
||||
|
||||
---
|
||||
|
||||
# AI-First Философия на Дизайна
|
||||
|
||||
## Защо AI-First?
|
||||
|
||||
Съвременната софтуерна разработка се извършва все повече от **AI агенти**, работещи в терминални среди. Тези агенти не използват GUI, IDE или syntax highlighting. Те се нуждаят от:
|
||||
|
||||
1. **Структуриран I/O** — JSON/EDN, не просто текст
|
||||
2. **Програмно Управление** — Всяка операция трябва да е скриптваема
|
||||
3. **Самоописващи Се Системи** — AI може да открива възможности по време на изпълнение
|
||||
4. **Git Интеграция** — Контрол на версиите като част от работния процес
|
||||
|
||||
## Принципи
|
||||
|
||||
### 1. Структуриран I/O
|
||||
|
||||
Цялата REPL комуникация използва JSON:
|
||||
|
||||
```json
|
||||
// Вход
|
||||
{"op": "eval", "form": "(+ 1 2)", "request-id": "uuid"}
|
||||
|
||||
// Изход
|
||||
{
|
||||
"status": "ok",
|
||||
"request-id": "uuid",
|
||||
"result": {"type": "int", "value": 3, "printed": "3"},
|
||||
"meta": {"ms": 0.5, "ns": "user"}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Batch Операции
|
||||
|
||||
AI агентите оценяват множество форми наведнъж:
|
||||
|
||||
```json
|
||||
{"op": "eval-batch",
|
||||
"forms": [
|
||||
"(defn add [a b] (+ a b))",
|
||||
"(add 10 20)"
|
||||
]}
|
||||
```
|
||||
|
||||
### 3. Персистентност на Сесията
|
||||
|
||||
Дефинициите се запазват в рамките на REPL сесия, позволявайки инкрементална разработка:
|
||||
|
||||
```json
|
||||
{"op": "eval", "form": "(defn square [x] (* x x))"}
|
||||
{"op": "eval", "form": "(square 5)"}
|
||||
{"op": "get-defs"}
|
||||
```
|
||||
|
||||
### 4. Възстановяване от Грешки
|
||||
|
||||
Всички грешки са структурирани с тип, съобщение и контекст:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "error",
|
||||
"error": {
|
||||
"type": "compiler/unknown-symbol",
|
||||
"symbol": "unknwon-fn",
|
||||
"message": "Unknown symbol: unknwon-fn",
|
||||
"form": "(unknwon-fn 1 2)"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## AI Работен Процес
|
||||
|
||||
```bash
|
||||
# 1. Клониране на репото
|
||||
git clone git@gitlab.com:balvatar/lisp-nim.git
|
||||
cd lisp-nim
|
||||
|
||||
# 2. Стартиране на AI REPL
|
||||
cljnim repl --json
|
||||
|
||||
# 3. AI оценява форми, получава структурирани отговори
|
||||
# 4. AI пише файлове през (file/write ...) [бъдеще]
|
||||
# 5. AI commit-ва през (git/commit ...) [бъдеще]
|
||||
# 6. AI push-ва през (git/push) [бъдеще]
|
||||
```
|
||||
|
||||
## Сравнение
|
||||
|
||||
| Аспект | Човешки IDE | AI Терминал |
|
||||
|---|---|---|
|
||||
| Интерфейс | GUI + мишка | Текст + команди |
|
||||
| Навигация | Кликване | `(apropos ...)`, `(doc ...)` |
|
||||
| Рефакториране | Ръчно | Batch eval + git diff |
|
||||
| Тестване | Run button | `(run-tests)` структуриран отговор |
|
||||
| Commit | GUI диалог | `(git/commit "msg")` |
|
||||
|
||||
## Бъдеще: Tool-Call Формат
|
||||
|
||||
Директна интеграция с AI frameworks:
|
||||
|
||||
```json
|
||||
{
|
||||
"tool": "cljnim/eval",
|
||||
"arguments": {
|
||||
"code": "(defn fib [n] ...)",
|
||||
"mode": "compile"
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,180 @@
|
||||
|
||||
[← Към индекса](index.md)
|
||||
|
||||
---
|
||||
|
||||
# REPL API Референция
|
||||
|
||||
## JSON REPL Протокол
|
||||
|
||||
Стартирайте JSON REPL:
|
||||
```bash
|
||||
cljnim repl --json
|
||||
```
|
||||
|
||||
REPL чете по един JSON обект на ред и отговаря с по един JSON обект на ред.
|
||||
|
||||
## Операции
|
||||
|
||||
### `eval`
|
||||
Оценява единична Clojure форма.
|
||||
|
||||
**Заявка:**
|
||||
```json
|
||||
{"op": "eval", "form": "(+ 1 2 3)"}
|
||||
```
|
||||
|
||||
**Отговор (успех):**
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"result": {
|
||||
"type": "unknown",
|
||||
"value": "6",
|
||||
"printed": "6"
|
||||
},
|
||||
"meta": {
|
||||
"ns": "user",
|
||||
"ms": 861.5,
|
||||
"form": "(+ 1 2 3)"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Отговор (грешка):**
|
||||
```json
|
||||
{
|
||||
"status": "error",
|
||||
"error": {
|
||||
"type": "reader/error",
|
||||
"message": "Unterminated list",
|
||||
"form": "( + 1 2"
|
||||
},
|
||||
"meta": {
|
||||
"ns": "user",
|
||||
"ms": 0.1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Незадължителни полета:**
|
||||
- `request-id` — Correlation ID, върнат в отговора
|
||||
- `ns` — Целево namespace (по подразбиране: `"user"`)
|
||||
|
||||
---
|
||||
|
||||
### `eval-batch`
|
||||
Оценява множество форми последователно.
|
||||
|
||||
**Заявка:**
|
||||
```json
|
||||
{"op": "eval-batch", "forms": ["(defn f [x] x)", "(f 42)"]}
|
||||
```
|
||||
|
||||
**Отговор:**
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"results": [
|
||||
{"status": "ok", "result": {"type": "var", "name": "f", ...}},
|
||||
{"status": "ok", "result": {"printed": "42"}, ...}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `get-defs`
|
||||
Листва всички дефинирани променливи в текущата сесия.
|
||||
|
||||
**Заявка:**
|
||||
```json
|
||||
{"op": "get-defs"}
|
||||
```
|
||||
|
||||
**Отговор:**
|
||||
```json
|
||||
{"status": "ok", "defs": ["add", "square"], "ns": "user"}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `clear`
|
||||
Изчиства всички дефиниции от сесията.
|
||||
|
||||
**Заявка:**
|
||||
```json
|
||||
{"op": "clear"}
|
||||
```
|
||||
|
||||
**Отговор:**
|
||||
```json
|
||||
{"status": "ok", "cleared": true}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `quit`
|
||||
Излиза от REPL.
|
||||
|
||||
**Заявка:**
|
||||
```json
|
||||
{"op": "quit"}
|
||||
```
|
||||
|
||||
**Отговор:**
|
||||
```json
|
||||
{"status": "ok", "bye": true}
|
||||
```
|
||||
|
||||
## Схема на Отговора
|
||||
|
||||
Всички отговори съдържат:
|
||||
- `status` — `"ok"` или `"error"`
|
||||
|
||||
При успех:
|
||||
- `result` — Обект с резултат от оценката
|
||||
- `type` — `"var"`, `"unknown"`, и т.н.
|
||||
- `printed` — Текстово представяне на резултата
|
||||
- `meta` — Метаданни
|
||||
- `ns` — Текущо namespace
|
||||
- `ms` — Време за изпълнение в милисекунди
|
||||
- `form` — Оригиналната форма (ако е `eval`)
|
||||
|
||||
При грешка:
|
||||
- `error` — Обект с грешка
|
||||
- `type` — Категория на грешката
|
||||
- `message` — Четимо съобщение
|
||||
- `meta` — Както при успех
|
||||
|
||||
## Файлови Операции (от Clojure код)
|
||||
|
||||
| Функция | Пример | Връща |
|
||||
|---|---|---|
|
||||
| `file/read` | `(file/read "path")` | Низ със съдържание или map с грешка |
|
||||
| `file/write` | `(file/write "path" "content")` | `true` или map с грешка |
|
||||
| `file/append` | `(file/append "path" "more")` | `true` или map с грешка |
|
||||
| `file/ls` | `(file/ls "dir")` | Вектор с имена на файлове |
|
||||
| `file/exists?` | `(file/exists? "path")` | `true` / `false` |
|
||||
|
||||
## Git Операции (от Clojure код)
|
||||
|
||||
| Функция | Пример | Връща |
|
||||
|---|---|---|
|
||||
| `git/status` | `(git/status)` | Map с `:branch`, `:modified`, `:untracked`, `:staged`, `:clean` |
|
||||
| `git/commit` | `(git/commit "msg")` | Map с `:sha`, `:success` |
|
||||
| `git/push` | `(git/push)` | Map с `:success`, `:output` |
|
||||
| `git/diff` | `(git/diff)` | Низ с diff |
|
||||
| `git/log` | `(git/log)` или `(git/log 10)` | Вектор с commit низове |
|
||||
|
||||
## Команди в Човешки REPL
|
||||
|
||||
В човешки режим (`cljnim repl`):
|
||||
|
||||
| Команда | Описание |
|
||||
|---|---|
|
||||
| `:quit`, `:q` | Изход от REPL |
|
||||
| `:help`, `:h` | Показване на помощ |
|
||||
| `:defs` | Листване на дефинирани променливи |
|
||||
| `:clear` | Изчистване на дефинициите |
|
||||
| `:ns` | Показване на текущото namespace |
|
||||
@@ -0,0 +1,155 @@
|
||||
|
||||
[← Към индекса](index.md)
|
||||
|
||||
---
|
||||
|
||||
# Ръководство за Потребителя — 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 структури
|
||||
; със structural sharing и O(log₃₂ n) операции.
|
||||
```
|
||||
|
||||
### Рекурсия
|
||||
```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 изцяло машинно-четим.
|
||||
@@ -0,0 +1,86 @@
|
||||
|
||||
[← Към индекса](index.md)
|
||||
|
||||
---
|
||||
|
||||
# Пътна Карта за Разработка
|
||||
|
||||
## Фаза 0: Компилаторно Ядро ✅
|
||||
- [x] Clojure Reader (EDN парсер)
|
||||
- [x] Reader поддържа: списъци `()`, вектори `[]`, карти `{}`, низове, ключови думи, символи, числа, булеви, nil
|
||||
- [x] Reader поддържа: quote `'`, syntax-quote `` ` ``, unquote `~`, unquote-splicing `~@`
|
||||
- [x] Reader поддържа: коментари `;`, read-all
|
||||
- [x] AST → Nim Генератор
|
||||
- [x] CLI (`compile`, `run`, `read`, `repl`)
|
||||
- [x] Специални форми: `def`, `defn`, `fn`, `let`, `if`, `do`, `quote`
|
||||
- [x] Специални форми: `when`, `cond`
|
||||
- [x] Аритметични оператори: `+`, `-`, `*`, `/`
|
||||
- [x] Оператори за сравнение: `=`, `not=`, `not`, `<`, `>`, `<=`, `>=`
|
||||
- [x] Core функции: `println`, `map`, `filter`, `reduce`
|
||||
- [x] Runtime типова система: `CljVal` с `nil`, `bool`, `int`, `float`, `string`, `keyword`, `symbol`, `list`, `vector`, `map`, `fn`, `atom`
|
||||
|
||||
## Фаза 1: Макро Система ✅
|
||||
- [x] `macroexpand`, `macroexpand-1`
|
||||
- [x] `syntax-quote`, `unquote`, `unquote-splicing`
|
||||
- [x] `gensym`
|
||||
- [x] `defmacro` (потребителски макроси)
|
||||
- [x] Вградени макроси: `->`, `->>`, `and`, `or`, `when`, `when-not`, `cond`
|
||||
- [x] Вградени макроси: `cond->`, `cond->>`, `doto`, `as->`, `some->`, `some->>`
|
||||
- [x] Вградени макроси: `for`, `doseq`, `dotimes`
|
||||
- [x] Вградени макроси: `when-let`, `if-let`
|
||||
- [x] Вградени макроси: `comment`, `assert`, `with-open`
|
||||
|
||||
## Фаза 2: REPL и Инструменти ✅
|
||||
- [x] Човешки REPL (`:help`, `:defs`, `:clear`, `:ns`, `:quit`)
|
||||
- [x] JSON REPL (`--json`) със структуриран I/O
|
||||
- [x] Batch оценка (`eval-batch`)
|
||||
- [x] Структурирани грешки (тип, съобщение, форма, ред)
|
||||
- [x] Персистентност на сесията за `def`/`defn`
|
||||
|
||||
## Фаза 3: Nim Interop ✅
|
||||
- [x] Извикване на Nim функции: `(nim/math/sin x)`, `(nim/strutils/toUpper s)`
|
||||
- [x] C FFI през Nim `importc`
|
||||
|
||||
## Фаза 4: AI-Native Инструменти ✅
|
||||
- [x] Файлови операции: `(file/read "path")`, `(file/write "path" "content")`, `(file/append "path" "content")`
|
||||
- [x] Файлови операции: `(file/ls "dir")`, `(file/exists? "path")`
|
||||
- [x] Git операции: `(git/status)`, `(git/commit "msg")`, `(git/push)`
|
||||
- [x] Git операции: `(git/diff)`, `(git/log)`
|
||||
- [x] nREPL протокол съвместимост (JSON over TCP, `--tcp PORT`)
|
||||
- [x] Tool-call формат за интеграция с AI frameworks
|
||||
|
||||
## Фаза 5: Persistent Структури от Данни ✅ (Завършена)
|
||||
- [x] Persistent Vector (Hash Array Mapped Trie, 32-way branching)
|
||||
- [x] Persistent Map (HAMT) — `pmapAssoc`, `pmapDissoc`, `pmapGet` в O(log₃₂ n)
|
||||
- [x] Persistent Set
|
||||
- [x] `conj`, `assoc`, `dissoc`, `get`, `get-in`
|
||||
- [x] `nth`, `first`, `rest`, `last`, `count` върху persistent колекции
|
||||
- [x] Transients за batch мутации
|
||||
- [x] `conj!`, `assoc!`, `persistent!`
|
||||
|
||||
## Фаза 6: Clojure Core Библиотека ✅ (Завършена)
|
||||
- [x] `range`, `repeat`, `cycle`, `iterate`
|
||||
- [x] `take`, `drop`, `partition`, `interleave`, `concat`
|
||||
- [x] `str`, `pr-str`, `println`, `prn`
|
||||
- [x] `slurp`, `spit`, `read-line`
|
||||
- [x] `meta`, `with-meta`, `vary-meta`
|
||||
- [x] `type`, `instance?`, `satisfies?`
|
||||
|
||||
## Фаза 7: Компилация на Проекти ✅
|
||||
- [x] Компилиране на цели проекти (не само отделни файлове)
|
||||
- [x] Система за namespaces (`ns`, `(:require [lib :as alias])`)
|
||||
- [x] Кеширане на модули за по-бърз REPL старт
|
||||
- [x] Резолюция на зависимости (deps.edn, Git deps към .deps/)
|
||||
|
||||
## Фаза 8: Self-Hosted REPL ✅
|
||||
- [x] Компилиране на форми в паметта (tree-walking interpreter, <1ms eval)
|
||||
- [x] Бърз REPL старт (~0.02ms на eval спрямо 1133ms компилиран)
|
||||
- [x] Hot code reloading (def/defn обновяват средата незабавно)
|
||||
|
||||
## Фаза 9: Конкурентност ✅
|
||||
- [x] Atoms (compare-and-swap)
|
||||
- [x] Agents (send, await, deref — sync dispatch в interpreter)
|
||||
- [x] core.async channels (chan, >!, <!, close!, go — interpreter-first)
|
||||
|
||||
## Известни Проблеми
|
||||
- `->>` threading macro с вложени `map`/`reduce` изисква правилен macro expansion контекст
|
||||
@@ -0,0 +1,36 @@
|
||||
|
||||
[← Към индекса](index.md)
|
||||
|
||||
---
|
||||
|
||||
# Clojure/Nim Документация (Български)
|
||||
|
||||
> Диалект на Clojure, който се компилира до Nim → C → нативен бинарен файл.
|
||||
|
||||
## Съдържание
|
||||
|
||||
| # | Документ | Описание |
|
||||
|---|----------|----------|
|
||||
| 01 | [Първи стъпки](01-getting-started.md) | Инсталация, компилация, CLI команди, бързи примери |
|
||||
| 02 | [Архитектура](02-architecture.md) | Компилационен pipeline, дизайн решения, вътрешна структура |
|
||||
| 03 | [AI Интеграция](03-ai-integration.md) | DeepSeek, OpenAI, MiMo — помощ при грешки, генериране на код, оптимизация, дебъг |
|
||||
| 04 | [API Справочник](04-api-reference.md) | JSON REPL протокол, операции, tool-call формат |
|
||||
| 05 | [Ръководство](05-user-guide.md) | Макроси, threading, interop, напреднали шаблони |
|
||||
| 06 | [Пътна карта](06-roadmap.md) | Завършени фази, бъдещи планове, цели за перформанс |
|
||||
|
||||
## Бърз старт
|
||||
|
||||
```bash
|
||||
git clone https://gitlab.com/balvatar/lisp-nim.git
|
||||
cd lisp-nim
|
||||
make build
|
||||
make check # компилация + тестове + примери
|
||||
./cljnim repl # човешки REPL
|
||||
```
|
||||
|
||||
## Статистика
|
||||
|
||||
- **Тестове:** 276+ в 8 suite-а
|
||||
- **Компилатор:** Nim → C → нативен код
|
||||
- **Target-и:** Linux, macOS, Windows, JS, WASM, C shared libraries
|
||||
- **AI Поддръжка:** DeepSeek API, OpenAI-compatible, Xiaomi MiMo
|
||||
Reference in New Issue
Block a user