Add bilingual documentation (EN + BG) in docs/

2026-05-08 16:59:24 +03:00
parent 5971c062d1
commit f189dbd14a
15 changed files with 1377 additions and 546 deletions
@@ -0,0 +1,94 @@
+# Архитектура на 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/import "strutils")
+(nim/call "strutils.join" ", " ["a" "b"])
+```
+
+## Отговорности на Модулите
+
+| Модул | Роля |
+|---|---|
+| `src/reader.nim` | Парсира `.clj` текст към `CljVal` AST |
+| `src/emitter.nim` | Трансформира `CljVal` AST в Nim изходен код |
+| `src/repl.nim` | Имплементация на human и AI REPL |
+| `src/types.nim` | Типове на AST възли (използват се от reader/emitter) |
+| `src/macros.nim` | Двигател за разширяване на макроси |
+| `src/runtime.nim` | Допълнителни runtime помощници |
+| `lib/cljnim_runtime.nim` | Основна runtime библиотека |
+
+## Модел на Паметта
+
+- Използва Nim's ORC garbage collector
+- `CljVal` е `ref object` (заделя се на heap)
+- Бъдеще: persistent структури от данни използват структурно споделяне