dimgigov
10e4ec07d6
- 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
108 lines
4.7 KiB
Markdown
108 lines
4.7 KiB
Markdown
|
||
[← Към индекса](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
|