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,106 @@
+# Clojure/Nim
+
+> Диалект на Clojure, който се компилира до Nim, после до C, и накрая до native бинарен файл.
+
+## Какво е това?
+
+Clojure/Nim е **AI-first** имплементация на езика Clojure за екосистемата на Nim. Вместо да работи върху JVM или JavaScript, компилира Clojure код директно до Nim, оттам до C, и накрая до native бинарен файл.
+
+### Защо?
+
+- **Native Performance**: Компилира се до C през Nim. Без JVM warmup, без GC паузи.
+- **Малки Бинарни Файлове**: Единични изпълними файлове, често под 1MB.
+- **Nim Ecosystem**: Директен достъп до Nim и C библиотеки през FFI.
+- **AI-Native**: Построен за AI агенти, работещи в терминал — структуриран JSON REPL, batch evaluation, git интеграция.
+
+## Бърз Старт
+
+```bash
+# Клониране
+git clone https://gitlab.com/balvatar/lisp-nim.git
+cd lisp-nim
+
+# Изграждане
+make build
+
+# Изпълнение на файл
+./cljnim run examples/hello.clj
+
+# Човешки REPL
+./cljnim repl
+
+# AI REPL (JSON режим)
+./cljnim repl --json
+```
+
+## Примери
+
+### Hello World
+```clojure
+;; examples/hello.clj
+(println "Здравей, Nim свят!")
+(println (+ 1 2 3))
+```
+
+```bash
+$ ./cljnim run examples/hello.clj
+Здравей, Nim свят!
+6
+```
+
+### Функции и Рекурсия
+```clojure
+;; examples/math.clj
+(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)))
+```
+
+```bash
+$ ./cljnim run examples/math.clj
+25
+120
+```
+
+## AI-First REPL
+
+Clojure/Nim е построен за AI агенти. JSON REPL предоставя структуриран I/O, идеален за програмно взаимодействие.
+
+```bash
+$ ./cljnim repl --json
+{"status":"ready","ns":"user","mode":"json"}
+
+> {"op":"eval","form":"(+ 1 2 3)"}
+{"status":"ok","result":{"printed":"6"},"meta":{"ms":861}}
+
+> {"op":"eval","form":"(defn square [x] (* x x))"}
+{"status":"ok","result":{"type":"var","name":"square"}}
+
+> {"op":"eval","form":"(square 5)"}
+{"status":"ok","result":{"printed":"25"}}
+
+> {"op":"quit"}
+{"status":"ok","bye":true}
+```
+
+## Документация
+
+| Документ | Описание |
+|---|---|
+| [`GUIDE.bg.md`](GUIDE.bg.md) | Ръководство за потребителя |
+| [`ARCHITECTURE.bg.md`](ARCHITECTURE.bg.md) | Архитектура и дизайн |
+| [`AI_FIRST.bg.md`](AI_FIRST.bg.md) | AI-first философия |
+| [`API.bg.md`](API.bg.md) | REPL API референция |
+| [`ROADMAP.bg.md`](ROADMAP.bg.md) | Пътна карта за разработка |
+
+## Лиценз
+
+MIT License — вижте [LICENSE](../LICENSE).