chore: rebrand Clojure/Nim → Bara Lang across codebase

- Bulk replace Clojure/Nim → Bara Lang in src/, lib/, examples/, benchmarks/, experiments/, books/, LICENSE, cljnim.nimble, PLAN.md, AI_AGENT.md - Rename book chapters: 05-clojure-nim.md → 05-bara-lang.md (en + bg) - Update all chapter index links and anchors - Replace project-specific 'Clojure' references with 'Bara Lang' in experiments/, src/ai_assist.nim, src/tui_screens.nim, src/emitter.nim, src/reader.nim, src/types.nim, lib/cljnim_runtime*.nim - Keep legitimate JVM Clojure/ClojureScript/Clojure CLR references intact
2026-05-11 12:23:29 +03:00
parent 606605c95c
commit 79cd9c08d8
41 changed files with 128 additions and 128 deletions
@@ -0,0 +1,289 @@
+# Bara Lang: Native Clojure
+
+> Същият език, който обичаш. Компилиран до нативен код. Без JVM.
+
+---
+
+## Какво е Bara Lang?
+
+**Bara Lang** е пълен диалект на Clojure, който се компилира до нативен машинен код през Nim компилатора. Това не е интерпретатор — това е истински компилатор с пълен pipeline за оптимизация:
+
+```
+Твоят .clj файл
+      ↓
+  Reader (EDN парсер)
+      ↓
+  Разширяване на макроси (defmacro, syntax-quote, ->, ->>)
+      ↓
+  Emitter (Clojure AST → Nim изходен код)
+      ↓
+  Nim компилатор → C код
+      ↓
+  C компилатор → Нативен бинарен файл
+```
+
+Резултатът е един изпълним файл, често под **1 MB**, който стартира мигновено — **без JVM warmup**.
+
+### Защо native?
+
+| JVM Clojure | Bara Lang |
+|-------------|-------------|
+| Нуждае се от Java runtime | Самостоятелен бинарен файл |
+| ~2-5 секунди startup | Мигновен старт |
+| ~100-300 MB RAM | ~1-10 MB |
+| JIT паузи | Ahead-of-time, предсказуем |
+| Идеален за сървъри | Идеален за CLI, embedded, WASM |
+
+Това не е играчка. Това е production компилатор с **276+ теста**, **persistent структури от данни (HAMT)**, **core.async канали** и **AI-асистиран workflow**.
+
+---
+
+## Инсталация
+
+```bash
+git clone https://gitlab.com/balvatar/lisp-nim.git
+cd lisp-nim
+make build
+make check   # всички тестове + примери
+```
+
+**Изисквания:** Nim ≥ 2.0, GCC или Clang, make.
+
+Толкова. Няма Java. Няма Leiningen. Няма deps, които се свалят по десет минути.
+
+---
+
+## Първа програма
+
+Създай `hello.clj`:
+
+```clojure
+(println "Здравей от native Clojure!")
+(println (+ 1 2 3 4 5))
+```
+
+Изпълни:
+
+```bash
+$ ./cljnim run hello.clj
+Здравей от native Clojure!
+15
+```
+
+Забележи: програмата беше парсирана, разширена с макроси, емитирана като Nim, компилирана до C, компилирана до машинен код и изпълнена — всичко за под секунда.
+
+---
+
+## REPL: Два режима
+
+### Човешки REPL
+
+```bash
+$ ./cljnim repl
+user> (defn square [x] (* x x))
+user> (square 7)
+=> 49
+user> (atom 42)
+=> (atom 42)
+user> :ai функция за фибоначи
+🤖 Мисля...
+💡 AI Предложение:
+   (defn fib [n]
+     (loop [a 0 b 1 i 0]
+       (if (= i n) a (recur b (+ a b) (inc i)))))
+```
+
+### JSON REPL (за AI агенти)
+
+```bash
+$ ./cljnim repl --json
+{"status":"ready","ns":"user","mode":"json"}
+
+> {"op":"eval","form":"(+ 1 2 3)"}
+{"status":"ok","result":{"printed":"6"},"meta":{"ms":12}}
+
+> {"tool":"cljnim/eval","args":{"form":"(defn greet [name] (str \"Hello \" name))"}}
+{"status":"ok","result":{"type":"var","name":"greet"},...}
+```
+
+JSON REPL е проектиран за програмно взаимодействие. Всяка операция има структуриран вход и изход. AI агенти могат да откриват възможности, оценяват код, инспектират дефиниции и обработват batch форми без парсиране на човешки текст.
+
+---
+
+## AI-асистирана разработка
+
+Bara Lang е първата Clojure имплементация, в която AI асистенцията е първокласна функция.
+
+### Обяснение на грешки
+
+Когато компилацията fail-не, компилаторът пита AI за помощ:
+
+```bash
+$ ./cljnim run broken.clj
+Compilation failed
+Error: identifier expected, but got 'keyword var'
+
+💡 AI Предложение:
+   Грешката е защото `var` е запазена дума в Nim.
+   Оправи: Преименувай функцията на `my-var`.
+```
+
+### Генериране на код
+
+Генерирай идиоматичен Clojure от описание:
+
+```bash
+$ ./cljnim ai "функция, която филтрира четните числа"
+(defn filter-even [coll]
+  (loop [remaining coll result []]
+    (if (empty? remaining)
+      result
+      (let [x (first remaining)]
+        (recur (rest remaining)
+               (if (even? x) (conj result x) result))))))
+```
+
+### Настройка
+
+```bash
+export DEEPSEEK_API_KEY="sk-..."
+# или OPENAI_API_KEY, или MIMO_API_KEY
+```
+
+---
+
+## `loop` / `recur`: Истинска TCO
+
+За разлика от JVM Clojure (който използва `recur`, за да избегне stack overflow, но все пак работи върху stack-based VM), Bara Lang компилира `loop`/`recur` до native `while` цикъл:
+
+```clojure
+(defn factorial [n]
+  (loop [acc 1 i n]
+    (if (= i 0)
+      acc
+      (recur (* acc i) (dec i)))))
+```
+
+Това генерира ефективен C код без функционални извиквания. **Истински O(1) stack space**.
+
+---
+
+## Cross-Compilation Target-и
+
+Bara Lang може да таргетира множество платформи от един и същи изходен код:
+
+### Нативен бинарен файл (по подразбиране)
+```bash
+./cljnim run program.clj
+```
+
+### JavaScript
+```bash
+./cljnim compile program.clj program.nim
+nim js -o:program.js program.nim
+node program.js
+```
+
+### C Shared Library
+```bash
+./cljnim compile-lib program.clj program.nim
+nim c --app:lib -o:libprogram.so program.nim
+```
+
+### WASM (експериментално)
+```bash
+nim c -d:release --cpu:wasm32 --os:linux program.nim
+```
+
+Това е нещо, което JVM Clojure просто не може да направи.
+
+---
+
+## Persistent Структури от Данни
+
+Bara Lang имплементира истински **Hash Array Mapped Trie (HAMT)** вектори и карти:
+
+```clojure
+(def v (vector 1 2 3))
+(def v2 (conj v 4))
+;; v  => [1 2 3]
+;; v2 => [1 2 3 4]
+;; Structural sharing: O(log₃₂ n) обновления, не O(n) копия
+```
+
+Runtime-ът използва същите алгоритми като Clojure/JVM (32-way branching, path copying, tail optimization), но компилиран до bare metal.
+
+---
+
+## Конкурентност
+
+### Atoms
+
+```clojure
+(def counter (atom 0))
+(swap! counter inc)    ;; => 1
+(reset! counter 100)   ;; => 100
+(deref counter)        ;; => 100
+```
+
+### Agents
+
+```clojure
+(def state (agent 0))
+(send state + 10)
+(await state)
+(deref state)          ;; => 10
+```
+
+### Канали (core.async)
+
+```clojure
+(def ch (chan 10))
+(put! ch 42)
+(take! ch)             ;; => 42
+(close! ch)
+```
+
+Всички примитиви за конкурентност работят както в компилирания runtime, така и в in-memory интерпретатора.
+
+---
+
+## Макроси, които работят
+
+```clojure
+(defmacro unless [condition body]
+  `(if (not ~condition)
+     ~body))
+
+(unless false
+  (println "Това се печата!"))
+```
+
+Threading макроси, `when-let`, `cond`, `doto`, `some->` — всички имплементирани като истински Clojure макроси, разширявани по време на компилация.
+
+---
+
+## Кога да използваш Bara Lang
+
+| Use Case | Clojure/JVM | Bara Lang |
+|----------|-------------|-------------|
+| Големи уеб услуги | ✅ | ⚠️ (ранен етап) |
+| CLI инструменти | ⚠️ (бавен старт) | ✅ (мигновен) |
+| Embedded системи | ❌ | ✅ |
+| WASM / браузър | ClojureScript | ✅ (native WASM) |
+| Споделени библиотеки | ❌ | ✅ |
+| AI agent scripting | ❌ | ✅ (JSON REPL) |
+| Учене на Clojure | ✅ | ✅ (без JVM) |
+
+---
+
+## Допълнително четене
+
+- [Основи](01-fundamentals.md) — Core Clojure концепции (валидни за всички диалекти)
+- [Архитектура](../../docs/bg/02-architecture.md) — Как работи компилаторът вътрешно
+- [AI Интеграция](../../docs/bg/03-ai-integration.md) — Детайли за AI функциите
+- [API Справочник](../../docs/bg/04-api-reference.md) — Спецификация на JSON REPL протокола
+
+---
+
+*Bara Lang е доказателство, че не ти трябва виртуална машина, за да пишеш елегантен, функционален, immutable код. Трябва ти само добър компилатор.*