Add bilingual documentation (EN + BG) in docs/
This commit is contained in:
-194
@@ -1,194 +0,0 @@
|
|||||||
# AI-First Clojure/Nim
|
|
||||||
|
|
||||||
## Философия
|
|
||||||
|
|
||||||
Този проект не е за човешки програмисти с Emacs/VS Code. Този проект е за **AI агенти**, които работят през терминал.
|
|
||||||
|
|
||||||
### Защо AI-First?
|
|
||||||
|
|
||||||
- AI не може да клика в GUI. AI работи с текст, команди и структурирани данни.
|
|
||||||
- AI не се нуждае от syntax highlighting. AI се нуждае от **структуриран изход**.
|
|
||||||
- AI не иска REPL с цветни prompt-ове. AI иска **EDN/JSON отговори** с метаданни.
|
|
||||||
- AI commit-ва кода автоматично. Нуждаем се от **git-aware REPL**.
|
|
||||||
|
|
||||||
## Архитектура на AI REPL
|
|
||||||
|
|
||||||
```
|
|
||||||
┌─────────────┐ EDN/JSON ┌─────────────────┐
|
|
||||||
│ AI Agent │ ◄────────────────► │ cljnim repl │
|
|
||||||
│ (терминал) │ structured I/O │ (structured) │
|
|
||||||
└─────────────┘ └────────┬────────┘
|
|
||||||
│
|
|
||||||
┌──────▼──────┐
|
|
||||||
│ Compiler │
|
|
||||||
│ + Eval │
|
|
||||||
└──────┬──────┘
|
|
||||||
│
|
|
||||||
┌──────▼──────┐
|
|
||||||
│ Git Ops │
|
|
||||||
│ (вградени) │
|
|
||||||
└─────────────┘
|
|
||||||
```
|
|
||||||
|
|
||||||
## Принципи
|
|
||||||
|
|
||||||
### 1. Структуриран I/O
|
|
||||||
|
|
||||||
Всеки вход и изход е структуриран:
|
|
||||||
|
|
||||||
```edn
|
|
||||||
;; AI изпраща:
|
|
||||||
{:op :eval
|
|
||||||
:form "(+ 1 2 3)"
|
|
||||||
:ns "user"
|
|
||||||
:request-id "uuid-1234"}
|
|
||||||
|
|
||||||
;; REPL връща:
|
|
||||||
{:status :ok
|
|
||||||
:request-id "uuid-1234"
|
|
||||||
:result {:type :int
|
|
||||||
:value 6
|
|
||||||
:printed "6"}
|
|
||||||
:meta {:ms 0.003
|
|
||||||
:form "(+ 1 2 3)"
|
|
||||||
:ns "user"}}
|
|
||||||
|
|
||||||
;; Грешка:
|
|
||||||
{:status :error
|
|
||||||
:request-id "uuid-1234"
|
|
||||||
:error {:type :compiler/unknown-symbol
|
|
||||||
:symbol "unknwon-fn"
|
|
||||||
:line 1
|
|
||||||
:column 5
|
|
||||||
:message "Unknown symbol: unknwon-fn"
|
|
||||||
:trace []}}
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. Batch Evaluation
|
|
||||||
|
|
||||||
AI може да изпрати множество форми наведнъж:
|
|
||||||
|
|
||||||
```edn
|
|
||||||
{:op :eval-batch
|
|
||||||
:forms ["(defn add [a b] (+ a b))"
|
|
||||||
"(add 10 20)"
|
|
||||||
"(def data {:x 1 :y 2})"]
|
|
||||||
:mode :compile}
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. Git-Aware REPL
|
|
||||||
|
|
||||||
Вградени git операции без напускане на REPL:
|
|
||||||
|
|
||||||
```clojure
|
|
||||||
;; Clojure форми, които управляват git:
|
|
||||||
(git/status)
|
|
||||||
;; => {:branch "main" :untracked ["src/new.clj"] :modified []}
|
|
||||||
|
|
||||||
(git/diff)
|
|
||||||
;; => {:files [{:path "src/core.clj" :added 5 :removed 2}]}
|
|
||||||
|
|
||||||
(git/commit "Add factorial" {:push true})
|
|
||||||
;; => {:sha "a1b2c3d" :pushed true}
|
|
||||||
```
|
|
||||||
|
|
||||||
### 4. Self-Describing Система
|
|
||||||
|
|
||||||
AI винаги може да попита системата какво може:
|
|
||||||
|
|
||||||
```clojure
|
|
||||||
(apropos "map")
|
|
||||||
;; => [{:name "map" :ns "clojure.core" :type :function}
|
|
||||||
;; {:name "map?" :ns "clojure.core" :type :function}
|
|
||||||
;; {:name "mapv" :ns "clojure.core" :type :function}]
|
|
||||||
|
|
||||||
(doc map)
|
|
||||||
;; => {:name "map"
|
|
||||||
;; :ns "clojure.core"
|
|
||||||
;; :doc "Returns a lazy sequence..."
|
|
||||||
;; :args [["f" "coll"] ["f" "c1" "c2" "& colls"]]
|
|
||||||
;; :source "(defn map [f coll] ...)"}
|
|
||||||
```
|
|
||||||
|
|
||||||
### 5. File Operations през REPL
|
|
||||||
|
|
||||||
AI не отваря редактор. AI манипулира файлове през Clojure:
|
|
||||||
|
|
||||||
```clojure
|
|
||||||
(file/read "src/core.clj")
|
|
||||||
;; => "(ns core)..."
|
|
||||||
|
|
||||||
(file/write "src/new.clj" "(ns new)")
|
|
||||||
;; => {:bytes-written 8 :path "src/new.clj"}
|
|
||||||
|
|
||||||
(file/ls "src")
|
|
||||||
;; => ["types.nim" "reader.nim" "emitter.nim"]
|
|
||||||
```
|
|
||||||
|
|
||||||
### 6. Tool-Call Формат
|
|
||||||
|
|
||||||
REPL може да работи в `tool-call` режим за директна интеграция с AI frameworks:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"tool": "cljnim/eval",
|
|
||||||
"arguments": {
|
|
||||||
"code": "(defn fib [n] (if (< n 2) n (+ (fib (- n 1)) (fib (- n 2)))))",
|
|
||||||
"mode": "compile"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Режими на REPL
|
|
||||||
|
|
||||||
### Човешки режим (default)
|
|
||||||
```
|
|
||||||
cljnim> (+ 1 2)
|
|
||||||
3
|
|
||||||
cljnim> (defn square [x] (* x x))
|
|
||||||
#'user/square
|
|
||||||
```
|
|
||||||
|
|
||||||
### AI режим (`--ai` или `--json`)
|
|
||||||
```bash
|
|
||||||
$ cljnim repl --json
|
|
||||||
{"status":"ready","ns":"user"}
|
|
||||||
> (defn add [a b] (+ a b))
|
|
||||||
{"status":"ok","result":{"type":"var","name":"add","ns":"user"}}
|
|
||||||
> (add 10 20)
|
|
||||||
{"status":"ok","result":{"type":"int","value":30,"printed":"30"},"meta":{"ms":0.001}}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Batch режим
|
|
||||||
```bash
|
|
||||||
$ cljnim run-batch script.clj --format json
|
|
||||||
[{"form":"(defn f [x] x)","status":"ok","result":"#'user/f"}
|
|
||||||
{"form":"(f 42)","status":"ok","result":{"type":"int","value":42}}]
|
|
||||||
```
|
|
||||||
|
|
||||||
## Интеграция с AI Workflow
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 1. AI клонира репото
|
|
||||||
git clone git@gitlab.com:balvatar/lisp-nim.git
|
|
||||||
cd lisp-nim
|
|
||||||
|
|
||||||
# 2. AI стартира REPL в JSON режим
|
|
||||||
cljnim repl --json
|
|
||||||
|
|
||||||
# 3. AI изпраща форми, получава структурирани отговори
|
|
||||||
# 4. AI пише файлове през (file/write ...)
|
|
||||||
# 5. AI commit-ва през (git/commit ...)
|
|
||||||
# 6. AI push-ва през (git/push)
|
|
||||||
```
|
|
||||||
|
|
||||||
## Защо това е бъдещето?
|
|
||||||
|
|
||||||
| Аспект | Човешки IDE | AI Terminal |
|
|
||||||
|---|---|---|
|
|
||||||
| Интерфейс | GUI + мишка | Текст + команды |
|
|
||||||
| Навигация | Кликване | `(apropos ...)`, `(doc ...)` |
|
|
||||||
| Рефакториране | Ръчно | Batch eval + git diff |
|
|
||||||
| Тестване | Run button | `(run-tests)` структуриран отговор |
|
|
||||||
| Commit | GUI диалог | `(git/commit "msg")` |
|
|
||||||
| Context | Отворени файлове | REPL ns + `:context` |
|
|
||||||
-169
@@ -1,169 +0,0 @@
|
|||||||
# Архитектура: Истински Clojure върху Nim
|
|
||||||
|
|
||||||
## Философия
|
|
||||||
|
|
||||||
Това не е "Clojure-подобен" език. Това е **Clojure диалект**, който компилира към Nim.
|
|
||||||
Макросите, структурите от данни и семантиката са съвместими с Clojure (JVM).
|
|
||||||
|
|
||||||
### Защо истински Clojure?
|
|
||||||
|
|
||||||
| Аспект | Clojure-inspired Lisp | Истински Clojure диалект |
|
|
||||||
|---|---|---|
|
|
||||||
| **Библиотеки** | Пишеш всичко на ново | Можеш да пренесеш `clojure.core`, `clojure.string`, `clojure.set` |
|
|
||||||
| **Разработчици** | Учат нов език | Всеки Clojure програмист може да го ползва веднага |
|
|
||||||
| **Инструменти** | Собствени | Работи с `clojure-mode`, CIDER, Calva (с някои адаптации) |
|
|
||||||
| **Финтех/Indустрия** | Не е опция | Може да се ползва за реални проекти |
|
|
||||||
|
|
||||||
### Който го е правил успешно
|
|
||||||
|
|
||||||
- **ClojureScript** — компилира Clojure до JS. Използва Google Closure. Пълна съвместимост.
|
|
||||||
- **Babashka** — GraalVM native image на Clojure. Бърз старт, скриптове, портативен.
|
|
||||||
- **Ferret** — Clojure → C++11 за embedded системи. Работи на 2KB RAM.
|
|
||||||
- **ClojErl** — Clojure върху BEAM. Жертва част от performance заради семантиката.
|
|
||||||
|
|
||||||
## Архитектура на Компилатора
|
|
||||||
|
|
||||||
```
|
|
||||||
┌─────────────────┐
|
|
||||||
│ .clj Файл │ ← Стандартен Clojure код
|
|
||||||
└────────┬────────┘
|
|
||||||
│
|
|
||||||
┌────▼────┐
|
|
||||||
│ Reader │ ← EDN парсер, Clojure symbols, quoted forms
|
|
||||||
└────┬────┘
|
|
||||||
│
|
|
||||||
┌────▼────┐
|
|
||||||
│ Macro │ ← defmacro, syntax-quote, unquote, unquote-splicing
|
|
||||||
│ Expansion│ (работи върху Clojure структури)
|
|
||||||
└────┬────┘
|
|
||||||
│
|
|
||||||
┌────▼────┐
|
|
||||||
│ Analyzer│ ← Специални форми, locals, recur targets,
|
|
||||||
│ │ closures, type hints
|
|
||||||
└────┬────┘
|
|
||||||
│
|
|
||||||
┌────▼────┐
|
|
||||||
│ Emitter │ ← Генерира Nim AST (не Nim текст!)
|
|
||||||
│ (Nim) │ Използва Nim макроси за компилация
|
|
||||||
└────┬────┘
|
|
||||||
│
|
|
||||||
┌────▼────┐
|
|
||||||
│ Nim │ ← C код, после машинен код
|
|
||||||
│Compiler │ оптимизация, tree-shaking, LTO
|
|
||||||
└────┬────┘
|
|
||||||
│
|
|
||||||
┌────▼────┐
|
|
||||||
│ Бинарен │ ← Единичен файл, < 10MB, бърз старт
|
|
||||||
│ Файл │
|
|
||||||
└─────────┘
|
|
||||||
```
|
|
||||||
|
|
||||||
## Ключови Решения
|
|
||||||
|
|
||||||
### 1. Компилатор, не Интерпретатор
|
|
||||||
|
|
||||||
Изборът е **AOT компилатор**, подобно на ClojureScript. Няма да пишем интерпретатор в Nim.
|
|
||||||
|
|
||||||
- **Предимство:** Бърз runtime, малък footprint, компилира до C.
|
|
||||||
- **Недостатък:** REPL е по-труден (но не невъзможен — виж ClojureScript self-hosted).
|
|
||||||
- **Урок от calcit-runner:** Те започнаха с интерпретатор в Nim и се провалиха. Ние директно компилираме.
|
|
||||||
|
|
||||||
### 2. Clojure Макроси на Clojure Структури
|
|
||||||
|
|
||||||
```clojure
|
|
||||||
;; Това трябва да работи без промяна:
|
|
||||||
(defmacro unless [condition & body]
|
|
||||||
`(if (not ~condition)
|
|
||||||
(do ~@body)))
|
|
||||||
|
|
||||||
(unless false
|
|
||||||
(println "Работи!"))
|
|
||||||
```
|
|
||||||
|
|
||||||
Макросите се разширяват **преди** да стигнем до Nim. Nim никога не вижда Clojure макрос.
|
|
||||||
|
|
||||||
### 3. Persistent Структури от Данни в Nim
|
|
||||||
|
|
||||||
Clojure's Hash Array Mapped Trie (HAMT) трябва да се имплементира в Nim:
|
|
||||||
|
|
||||||
```nim
|
|
||||||
# Nim runtime за Clojure Vector
|
|
||||||
type
|
|
||||||
NodeKind = enum nkLeaf, nkInternal
|
|
||||||
Node[T] = ref object
|
|
||||||
case kind: NodeKind
|
|
||||||
of nkLeaf: values: seq[T]
|
|
||||||
of nkInternal: children: array[32, Node[T]]
|
|
||||||
|
|
||||||
PersistentVector[T] = object
|
|
||||||
root: Node[T]
|
|
||||||
tail: seq[T]
|
|
||||||
count: int
|
|
||||||
```
|
|
||||||
|
|
||||||
- `conj`, `assoc`, `dissoc` — O(log₃₂ n)
|
|
||||||
- `nth`, `get` — O(log₃₂ n)
|
|
||||||
- `count` — O(1)
|
|
||||||
|
|
||||||
### 4. Nim Interop (вместо Java Interop)
|
|
||||||
|
|
||||||
Тъй като нямаме JVM, interop-ът е с Nim:
|
|
||||||
|
|
||||||
```clojure
|
|
||||||
;; Извикване на Nim функция
|
|
||||||
(nim/strutils.join ", " ["a" "b" "c"])
|
|
||||||
|
|
||||||
;; Достъп до Nim тип
|
|
||||||
(nim/times.DateTime)
|
|
||||||
|
|
||||||
;; FFI към C библиотека
|
|
||||||
(nim/ffi.import "math.h" :functions [["sin" :double [:double]]])
|
|
||||||
```
|
|
||||||
|
|
||||||
### 5. Симулация на Clojure Runtime
|
|
||||||
|
|
||||||
| Clojure JVM | Нашата Имплементация |
|
|
||||||
|---|---|
|
|
||||||
| `Var` | Глобални Nim променливи с atomic CAS |
|
|
||||||
| `Namespace` | Nim модул + хеш таблица със символи |
|
|
||||||
| `Atom` | `ref` тип с compare-and-swap |
|
|
||||||
| `Agent` | Channel + Worker thread |
|
|
||||||
| `Ref/STM` | Software transactional memory в Nim |
|
|
||||||
| `Multimethod` | Диспач таблица + `isa?` проверка |
|
|
||||||
| `Protocol` | Nim concepts + dispatch таблица |
|
|
||||||
|
|
||||||
## Фази с Индустриален Фокус
|
|
||||||
|
|
||||||
### Phase 1: Компилатор (не REPL!)
|
|
||||||
Фокус: AOT компилация на прости Clojure файлове към Nim.
|
|
||||||
|
|
||||||
### Phase 2: Core Библиотека
|
|
||||||
Фокус: Пренасяне на `clojure.core` функции. Тестове с реални Clojure тестове.
|
|
||||||
|
|
||||||
### Phase 3: Nim Interop + FFI
|
|
||||||
Фокус: Извикване на Nim/C библиотеки. Това е нашето "убийствено" предимство.
|
|
||||||
|
|
||||||
### Phase 4: REPL (Self-hosted)
|
|
||||||
Фокус: REPL като ClojureScript (компилира в паметта).
|
|
||||||
|
|
||||||
### Phase 5: Инструменти
|
|
||||||
Фокус: nREPL съвместимост, LSP, пакетен мениджър (Nimble интеграция).
|
|
||||||
|
|
||||||
## Изисквания за Съвместимост
|
|
||||||
|
|
||||||
- `clojure.core` namespace трябва да е наличен
|
|
||||||
- `defn`, `let`, `if`, `do`, `recur`, `loop` — точна семантика
|
|
||||||
- `->`, `->>`, `cond->` — макроси
|
|
||||||
- Persistent Vector, Map, Set — стандартни операции
|
|
||||||
- Keywords (`:name`) и Symbols (`'sym`) — interned
|
|
||||||
|
|
||||||
## Разлики от JVM Clojure (приемливи)
|
|
||||||
|
|
||||||
| JVM Clojure | Clojure/Nim |
|
|
||||||
|---|---|
|
|
||||||
| Java interop | Nim interop |
|
|
||||||
| JVM threads | Nim threads (no GIL!) |
|
|
||||||
| Dynamic classloading | AOT компилация |
|
|
||||||
| `gen-class` | `gen-nim` (генериране на Nim типове) |
|
|
||||||
| Reflection | Compile-time метаданни |
|
|
||||||
| Big ecosystem | Достъп до Nim + C ecosystem |
|
|
||||||
@@ -1,114 +1,197 @@
|
|||||||
# Clojure/Nim
|
# Clojure/Nim
|
||||||
|
|
||||||
> Реализация на Clojure върху Nim-lang
|
> A Clojure dialect that compiles to Nim, then to C, then to native binaries.
|
||||||
|
|
||||||
## Какво е това?
|
## What is this?
|
||||||
|
|
||||||
Clojure/Nim е проект, целящ да предостави Clojure език и runtime върху Nim. Вдъхновен е от ClojureScript и Babashka, но вместо JavaScript или JVM, целта е компилация към Nim код и използване на Nim runtime.
|
Clojure/Nim is an **AI-first** implementation of the Clojure language targeting the Nim ecosystem. Instead of running on the JVM or JavaScript, it compiles Clojure code directly to Nim source, which then compiles to C and finally to a native binary.
|
||||||
|
|
||||||
## Защо?
|
### Why?
|
||||||
|
|
||||||
- **Единен AST**: Nim предлага мощна макро система и AST манипулация
|
- **Native Performance**: Compiles to C via Nim. No JVM warmup, no GC pauses.
|
||||||
- **Производителност**: Компилиран към C, Nim дава C-подобна скорост с Lisp-удобство
|
- **Tiny Binaries**: Single-file executables, often under 1MB.
|
||||||
- **Размер**: Минимален runtime footprint в сравнение с JVM
|
- **Nim Ecosystem**: Direct access to Nim and C libraries via FFI.
|
||||||
- **Метапрограмиране**: Съчетание на Clojure макроси и Nim макроси
|
- **AI-Native**: Built for AI agents working in terminals — structured JSON REPL, batch evaluation, git integration.
|
||||||
|
|
||||||
## Архитектура
|
## Quick Start
|
||||||
|
|
||||||
```
|
|
||||||
Clojure Изходен Код (.clj)
|
|
||||||
↓
|
|
||||||
Clojure Reader (Clojure → Clojure Data)
|
|
||||||
↓
|
|
||||||
Макро Разширение (Clojure Macros)
|
|
||||||
↓
|
|
||||||
AST Транслатор (Clojure AST → Nim AST)
|
|
||||||
↓
|
|
||||||
Nim Компилатор
|
|
||||||
↓
|
|
||||||
C Код → Машинен Код
|
|
||||||
```
|
|
||||||
|
|
||||||
## Статус
|
|
||||||
|
|
||||||
> ⚠️ **Ранен етап** — Проектът е във фаза на планиране и базова имплементация.
|
|
||||||
|
|
||||||
Виж [ROADMAP.md](ROADMAP.md) за текущия прогрес.
|
|
||||||
|
|
||||||
## Бърз Старт
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Клониране
|
# Clone
|
||||||
git clone <repo-url>
|
git clone https://gitlab.com/balvatar/lisp-nim.git
|
||||||
cd clojure-nim
|
cd lisp-nim
|
||||||
|
|
||||||
# Изграждане
|
# Build
|
||||||
make build
|
make build
|
||||||
|
|
||||||
# REPL
|
# Run a file
|
||||||
./cljnim
|
|
||||||
|
|
||||||
# Изпълнение на файл
|
|
||||||
./cljnim run examples/hello.clj
|
./cljnim run examples/hello.clj
|
||||||
|
|
||||||
|
# Start human REPL
|
||||||
|
./cljnim repl
|
||||||
|
|
||||||
|
# Start AI REPL (JSON mode)
|
||||||
|
./cljnim repl --json
|
||||||
```
|
```
|
||||||
|
|
||||||
## Примери
|
## Examples
|
||||||
|
|
||||||
|
### Hello World
|
||||||
```clojure
|
```clojure
|
||||||
;; hello.clj
|
;; examples/hello.clj
|
||||||
(ns hello)
|
(println "Hello, Nim world!")
|
||||||
|
(println (+ 1 2 3))
|
||||||
|
```
|
||||||
|
|
||||||
(println "Здравей, Nim свят!")
|
```bash
|
||||||
|
$ ./cljnim run examples/hello.clj
|
||||||
|
Hello, Nim world!
|
||||||
|
6
|
||||||
|
```
|
||||||
|
|
||||||
(defn факториел [n]
|
### Functions & Recursion
|
||||||
(if (<= n 1)
|
```clojure
|
||||||
|
;; examples/math.clj
|
||||||
|
(defn square [x]
|
||||||
|
(* x x))
|
||||||
|
|
||||||
|
(defn factorial [n]
|
||||||
|
(if (= n 0)
|
||||||
1
|
1
|
||||||
(* n (факториел (- n 1)))))
|
(* n (factorial (- n 1)))))
|
||||||
|
|
||||||
(println "5! =" (факториел 5))
|
(let [a 5]
|
||||||
|
(println (square a))
|
||||||
|
(println (factorial a)))
|
||||||
```
|
```
|
||||||
|
|
||||||
```clojure
|
```bash
|
||||||
;; Работа със структури от данни
|
$ ./cljnim run examples/math.clj
|
||||||
(def данни
|
25
|
||||||
{:име "Иван"
|
120
|
||||||
:възраст 30
|
|
||||||
:езици ["Clojure" "Nim" "C"]})
|
|
||||||
|
|
||||||
(println (get-in данни [:езици 0]))
|
|
||||||
;; => "Clojure"
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Структура на Проекта
|
## AI-First REPL
|
||||||
|
|
||||||
|
Clojure/Nim is built for AI agents. The JSON REPL provides structured I/O perfect for programmatic interaction.
|
||||||
|
|
||||||
|
```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}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Supported REPL Operations
|
||||||
|
|
||||||
|
| Operation | Description |
|
||||||
|
|---|---|
|
||||||
|
| `eval` | Evaluate a single Clojure form |
|
||||||
|
| `eval-batch` | Evaluate multiple forms at once |
|
||||||
|
| `get-defs` | List all defined vars in current session |
|
||||||
|
| `clear` | Clear all session definitions |
|
||||||
|
| `quit` | Exit the REPL |
|
||||||
|
|
||||||
|
See [`docs/AI_FIRST.md`](docs/AI_FIRST.md) for the full AI integration design.
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
```
|
||||||
|
Clojure Source (.clj)
|
||||||
|
↓
|
||||||
|
Reader (EDN parser)
|
||||||
|
↓
|
||||||
|
Macro Expansion (Clojure macros)
|
||||||
|
↓
|
||||||
|
Analyzer (special forms, locals)
|
||||||
|
↓
|
||||||
|
Emitter (Clojure AST → Nim AST)
|
||||||
|
↓
|
||||||
|
Nim Compiler → C Code
|
||||||
|
↓
|
||||||
|
C Compiler → Native Binary
|
||||||
|
```
|
||||||
|
|
||||||
|
See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for details.
|
||||||
|
|
||||||
|
## Project Structure
|
||||||
|
|
||||||
```
|
```
|
||||||
├── src/
|
├── src/
|
||||||
│ ├── reader/ # Clojure reader (EDN парсер)
|
│ ├── cljnim.nim # CLI entry point
|
||||||
│ ├── analyzer/ # Semantic анализатор
|
│ ├── reader.nim # Clojure reader / EDN parser
|
||||||
│ ├── macros/ # Core macros (defn, let, if, и т.н.)
|
│ ├── emitter.nim # Nim code generator
|
||||||
│ ├── emitter/ # Генератор на Nim код
|
│ ├── repl.nim # Human & AI REPL
|
||||||
│ ├── runtime/ # Clojure runtime в Nim
|
│ ├── types.nim # Clojure value types
|
||||||
│ └── repl/ # Интерактивна обвивка
|
│ ├── macros.nim # Macro expansion engine
|
||||||
|
│ └── runtime.nim # Runtime implementation
|
||||||
├── lib/
|
├── lib/
|
||||||
│ └── core.clj # Clojure core библиотека
|
│ └── cljnim_runtime.nim # Clojure runtime in Nim
|
||||||
├── tests/ # Тестове
|
├── examples/
|
||||||
├── examples/ # Примери
|
│ ├── hello.clj
|
||||||
|
│ └── math.clj
|
||||||
|
├── docs/ # Documentation (EN + BG)
|
||||||
|
├── tests/
|
||||||
├── Makefile
|
├── Makefile
|
||||||
└── README.md
|
└── cljnim.nimble
|
||||||
```
|
```
|
||||||
|
|
||||||
## Изисквания
|
## Supported Features
|
||||||
|
|
||||||
|
### Working Now ✅
|
||||||
|
- Reader: numbers, strings, symbols, keywords, lists `()`, vectors `[]`
|
||||||
|
- Special forms: `def`, `defn`, `fn`, `let`, `if`, `do`, `quote`
|
||||||
|
- Arithmetic: `+`, `-`, `*`, `/`, `=`, `<`, `>`
|
||||||
|
- Functions: `println`
|
||||||
|
- Human REPL and JSON REPL
|
||||||
|
- AOT compilation to native binaries
|
||||||
|
|
||||||
|
### In Progress 🔄
|
||||||
|
- Persistent data structures (Vector, Map, Set)
|
||||||
|
- `defmacro` system
|
||||||
|
- Nim/C interop
|
||||||
|
- File operations from REPL
|
||||||
|
- Git operations from REPL
|
||||||
|
|
||||||
|
See [`docs/ROADMAP.md`](docs/ROADMAP.md) for the full roadmap.
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
- Nim >= 2.0
|
- Nim >= 2.0
|
||||||
- GCC или Clang
|
- GCC or Clang
|
||||||
- make
|
- make
|
||||||
|
|
||||||
## Лиценз
|
## Documentation
|
||||||
|
|
||||||
MIT License — виж [LICENSE](LICENSE).
|
| Document | Description |
|
||||||
|
|---|---|
|
||||||
|
| [`docs/README.bg.md`](docs/README.bg.md) | Българско README |
|
||||||
|
| [`docs/GUIDE.md`](docs/GUIDE.md) | User guide (English) |
|
||||||
|
| [`docs/GUIDE.bg.md`](docs/GUIDE.bg.md) | Ръководство за потребителя |
|
||||||
|
| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Architecture & design |
|
||||||
|
| [`docs/ARCHITECTURE.bg.md`](docs/ARCHITECTURE.bg.md) | Архитектура и дизайн |
|
||||||
|
| [`docs/AI_FIRST.md`](docs/AI_FIRST.md) | AI-first design philosophy |
|
||||||
|
| [`docs/AI_FIRST.bg.md`](docs/AI_FIRST.bg.md) | AI-first философия |
|
||||||
|
| [`docs/API.md`](docs/API.md) | REPL API reference |
|
||||||
|
| [`docs/API.bg.md`](docs/API.bg.md) | REPL API референция |
|
||||||
|
| [`docs/ROADMAP.md`](docs/ROADMAP.md) | Development roadmap |
|
||||||
|
| [`docs/ROADMAP.bg.md`](docs/ROADMAP.bg.md) | Пътна карта |
|
||||||
|
|
||||||
## Благодарности
|
## License
|
||||||
|
|
||||||
- [Clojure](https://clojure.org/) — Rich Hickey и екипът
|
MIT License — see [LICENSE](LICENSE).
|
||||||
- [Nim](https://nim-lang.org/) — Andreas Rumpf и общността
|
|
||||||
- Вдъхновено от ClojureScript, Babashka и Clojerl
|
## Acknowledgments
|
||||||
|
|
||||||
|
- [Clojure](https://clojure.org/) — Rich Hickey and team
|
||||||
|
- [Nim](https://nim-lang.org/) — Andreas Rumpf and community
|
||||||
|
- Inspired by ClojureScript, Babashka, Ferret, and Pixie
|
||||||
|
|||||||
-108
@@ -1,108 +0,0 @@
|
|||||||
# Пътна Карта: Clojure/Nim (AI-First Edition)
|
|
||||||
|
|
||||||
## Фаза 0: Компилаторно Ядро ✅
|
|
||||||
|
|
||||||
- [x] Clojure Reader (EDN парсер)
|
|
||||||
- [x] AST → Nim Emitter
|
|
||||||
- [x] CLI (`compile`, `run`, `read`)
|
|
||||||
- [x] Специални форми: `def`, `defn`, `fn`, `let`, `if`, `do`, `quote`
|
|
||||||
- [x] Оператори: `+`, `-`, `*`, `/`, `=`, `<`, `>`
|
|
||||||
- [x] Функции: `println` → `echo`
|
|
||||||
- [x] Примери: `hello.clj`, `math.clj` (факториел)
|
|
||||||
|
|
||||||
## Фаза 1: AI-First REPL 🔄
|
|
||||||
|
|
||||||
**Цел:** REPL, който AI може да ползва през терминал без редактор.
|
|
||||||
|
|
||||||
### 1.1 Структуриран REPL
|
|
||||||
- [ ] JSON/EDN режим (`cljnim repl --json`)
|
|
||||||
- [ ] Batch evaluation (`cljnim run-batch script.clj --format json`)
|
|
||||||
- [ ] Структурирани грешки (line, column, type, message, trace)
|
|
||||||
- [ ] Метаданни в отговора (ms, ns, form, type)
|
|
||||||
|
|
||||||
### 1.2 Self-Describing Система
|
|
||||||
- [ ] `(doc fn)` — връща структурирани метаданни
|
|
||||||
- [ ] `(apropos "str")` — търсене на функции
|
|
||||||
- [ ] `(source fn)` — изходен код на функция
|
|
||||||
- [ ] `(ns-publics 'clojure.core)` — листване на публични символи
|
|
||||||
|
|
||||||
### 1.3 File Operations
|
|
||||||
- [ ] `(file/read "path")` — четене на файл
|
|
||||||
- [ ] `(file/write "path" "content")` — запис на файл
|
|
||||||
- [ ] `(file/append "path" "content")` — добавяне
|
|
||||||
- [ ] `(file/ls "dir")` — листване на директория
|
|
||||||
- [ ] `(file/exists? "path")` — проверка
|
|
||||||
|
|
||||||
### 1.4 Git Operations (вградени)
|
|
||||||
- [ ] `(git/status)` — текущ статус
|
|
||||||
- [ ] `(git/diff)` — разлики
|
|
||||||
- [ ] `(git/add "file")` — stage
|
|
||||||
- [ ] `(git/commit "msg")` — commit
|
|
||||||
- [ ] `(git/push)` — push
|
|
||||||
- [ ] `(git/log)` — история
|
|
||||||
|
|
||||||
## Фаза 2: Persistent Структури от Данни
|
|
||||||
|
|
||||||
**Цел:** Истински Clojure immutable структури.
|
|
||||||
|
|
||||||
- [ ] **Persistent Vector** (Hash Array Mapped Trie)
|
|
||||||
- [ ] **Persistent Map** (HAMT)
|
|
||||||
- [ ] **Persistent Set**
|
|
||||||
- [ ] `conj`, `assoc`, `dissoc`, `get`, `get-in`
|
|
||||||
- [ ] `nth`, `first`, `rest`, `last`, `count`
|
|
||||||
|
|
||||||
## Фаза 3: Clojure Core Библиотека
|
|
||||||
|
|
||||||
**Цел:** Достатъчно функции за реални скриптове.
|
|
||||||
|
|
||||||
### 3.1 Seq функции
|
|
||||||
- [ ] `map`, `filter`, `reduce`
|
|
||||||
- [ ] `take`, `drop`, `partition`
|
|
||||||
- [ ] `concat`, `interleave`
|
|
||||||
- [ ] `range`
|
|
||||||
|
|
||||||
### 3.2 Низове и IO
|
|
||||||
- [ ] `str`, `pr-str`, `println`, `prn`
|
|
||||||
- [ ] `slurp`, `spit`
|
|
||||||
- [ ] `read-line`
|
|
||||||
|
|
||||||
### 3.3 Мета
|
|
||||||
- [ ] `meta`, `with-meta`, `vary-meta`
|
|
||||||
- [ ] `type`, `instance?`
|
|
||||||
|
|
||||||
## Фаза 4: Макро Система
|
|
||||||
|
|
||||||
**Цел:** `defmacro` да работи.
|
|
||||||
|
|
||||||
- [ ] `macroexpand`, `macroexpand-1`
|
|
||||||
- [ ] `syntax-quote`, `unquote`, `unquote-splicing`
|
|
||||||
- [ ] `gensym`
|
|
||||||
- [ ] Core макроси: `->`, `->>`, `and`, `or`, `when`, `cond`
|
|
||||||
|
|
||||||
## Фаза 5: Nim Interop
|
|
||||||
|
|
||||||
**Цел:** Достъп до целия Nim ecosystem.
|
|
||||||
|
|
||||||
- [ ] `(nim/import "strutils")` — import на Nim модул
|
|
||||||
- [ ] `(nim/ffi "math.h" :functions [["sin" :double [:double]]])` — C FFI
|
|
||||||
- [ ] `(nim/call "strutils.join" ", " ["a" "b"])` — извикване
|
|
||||||
|
|
||||||
## Фаза 6: AOT Компилация + REPL
|
|
||||||
|
|
||||||
**Цел:** Бързо стартиране на скриптове.
|
|
||||||
|
|
||||||
- [ ] AOT компилация на цели проекти
|
|
||||||
- [ ] Кеширане на компилирани модули
|
|
||||||
- [ ] REPL в self-hosted режим (като ClojureScript)
|
|
||||||
|
|
||||||
## Фаза 7: Многонишковост
|
|
||||||
|
|
||||||
- [ ] **Atoms** (CAS)
|
|
||||||
- [ ] **Agents**
|
|
||||||
- [ ] **core.async** channels (упростен вариант)
|
|
||||||
|
|
||||||
## Текущ Фокус
|
|
||||||
|
|
||||||
**Фаза 1 — AI-First REPL**
|
|
||||||
|
|
||||||
Следваща задача: `cljnim repl --json` с batch evaluation и структурирани отговори.
|
|
||||||
@@ -0,0 +1,107 @@
|
|||||||
|
# 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,107 @@
|
|||||||
|
# AI-First Design Philosophy
|
||||||
|
|
||||||
|
## Why AI-First?
|
||||||
|
|
||||||
|
Modern software development is increasingly done by **AI agents** operating in terminal environments. These agents do not use GUIs, IDEs, or syntax highlighting. They need:
|
||||||
|
|
||||||
|
1. **Structured I/O** — JSON/EDN, not plain text
|
||||||
|
2. **Programmatic Control** — Every operation must be scriptable
|
||||||
|
3. **Self-Describing Systems** — AI can discover capabilities at runtime
|
||||||
|
4. **Git Integration** — Version control as part of the workflow
|
||||||
|
|
||||||
|
## Principles
|
||||||
|
|
||||||
|
### 1. Structured I/O
|
||||||
|
|
||||||
|
All REPL communication uses JSON:
|
||||||
|
|
||||||
|
```json
|
||||||
|
// Input
|
||||||
|
{"op": "eval", "form": "(+ 1 2)", "request-id": "uuid"}
|
||||||
|
|
||||||
|
// Output
|
||||||
|
{
|
||||||
|
"status": "ok",
|
||||||
|
"request-id": "uuid",
|
||||||
|
"result": {"type": "int", "value": 3, "printed": "3"},
|
||||||
|
"meta": {"ms": 0.5, "ns": "user"}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Batch Operations
|
||||||
|
|
||||||
|
AI agents evaluate multiple forms at once:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"op": "eval-batch",
|
||||||
|
"forms": [
|
||||||
|
"(defn add [a b] (+ a b))",
|
||||||
|
"(add 10 20)"
|
||||||
|
]}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Session Persistence
|
||||||
|
|
||||||
|
Definitions persist within a REPL session, allowing incremental development:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"op": "eval", "form": "(defn square [x] (* x x))"}
|
||||||
|
{"op": "eval", "form": "(square 5)"}
|
||||||
|
{"op": "get-defs"}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Error Recovery
|
||||||
|
|
||||||
|
All errors are structured with type, message, and context:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": "error",
|
||||||
|
"error": {
|
||||||
|
"type": "compiler/unknown-symbol",
|
||||||
|
"symbol": "unknwon-fn",
|
||||||
|
"message": "Unknown symbol: unknwon-fn",
|
||||||
|
"form": "(unknwon-fn 1 2)"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## AI Workflow
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. Clone repo
|
||||||
|
git clone git@gitlab.com:balvatar/lisp-nim.git
|
||||||
|
cd lisp-nim
|
||||||
|
|
||||||
|
# 2. Start AI REPL
|
||||||
|
cljnim repl --json
|
||||||
|
|
||||||
|
# 3. AI evaluates forms, gets structured responses
|
||||||
|
# 4. AI writes files via (file/write ...) [future]
|
||||||
|
# 5. AI commits via (git/commit ...) [future]
|
||||||
|
# 6. AI pushes via (git/push) [future]
|
||||||
|
```
|
||||||
|
|
||||||
|
## Comparison
|
||||||
|
|
||||||
|
| Aspect | Human IDE | AI Terminal |
|
||||||
|
|---|---|---|
|
||||||
|
| Interface | GUI + mouse | Text + commands |
|
||||||
|
| Navigation | Clicking | `(apropos ...)`, `(doc ...)` |
|
||||||
|
| Refactoring | Manual | Batch eval + git diff |
|
||||||
|
| Testing | Run button | `(run-tests)` structured response |
|
||||||
|
| Commit | GUI dialog | `(git/commit "msg")` |
|
||||||
|
|
||||||
|
## Future: Tool-Call Format
|
||||||
|
|
||||||
|
Direct integration with AI frameworks:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"tool": "cljnim/eval",
|
||||||
|
"arguments": {
|
||||||
|
"code": "(defn fib [n] ...)",
|
||||||
|
"mode": "compile"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
+155
@@ -0,0 +1,155 @@
|
|||||||
|
# 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` — Както при успех
|
||||||
|
|
||||||
|
## Команди в Човешки REPL
|
||||||
|
|
||||||
|
В човешки режим (`cljnim repl`):
|
||||||
|
|
||||||
|
| Команда | Описание |
|
||||||
|
|---|---|
|
||||||
|
| `:quit`, `:q` | Изход от REPL |
|
||||||
|
| `:help`, `:h` | Показване на помощ |
|
||||||
|
| `:defs` | Листване на дефинирани променливи |
|
||||||
|
| `:clear` | Изчистване на дефинициите |
|
||||||
|
| `:ns` | Показване на текущото namespace |
|
||||||
+155
@@ -0,0 +1,155 @@
|
|||||||
|
# REPL API Reference
|
||||||
|
|
||||||
|
## JSON REPL Protocol
|
||||||
|
|
||||||
|
Start the JSON REPL:
|
||||||
|
```bash
|
||||||
|
cljnim repl --json
|
||||||
|
```
|
||||||
|
|
||||||
|
The REPL reads one JSON object per line and responds with one JSON object per line.
|
||||||
|
|
||||||
|
## Operations
|
||||||
|
|
||||||
|
### `eval`
|
||||||
|
Evaluate a single Clojure form.
|
||||||
|
|
||||||
|
**Request:**
|
||||||
|
```json
|
||||||
|
{"op": "eval", "form": "(+ 1 2 3)"}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response (success):**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": "ok",
|
||||||
|
"result": {
|
||||||
|
"type": "unknown",
|
||||||
|
"value": "6",
|
||||||
|
"printed": "6"
|
||||||
|
},
|
||||||
|
"meta": {
|
||||||
|
"ns": "user",
|
||||||
|
"ms": 861.5,
|
||||||
|
"form": "(+ 1 2 3)"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response (error):**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": "error",
|
||||||
|
"error": {
|
||||||
|
"type": "reader/error",
|
||||||
|
"message": "Unterminated list",
|
||||||
|
"form": "( + 1 2"
|
||||||
|
},
|
||||||
|
"meta": {
|
||||||
|
"ns": "user",
|
||||||
|
"ms": 0.1
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Optional fields:**
|
||||||
|
- `request-id` — Correlation ID, echoed in the response
|
||||||
|
- `ns` — Target namespace (default: `"user"`)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### `eval-batch`
|
||||||
|
Evaluate multiple forms in sequence.
|
||||||
|
|
||||||
|
**Request:**
|
||||||
|
```json
|
||||||
|
{"op": "eval-batch", "forms": ["(defn f [x] x)", "(f 42)"]}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": "ok",
|
||||||
|
"results": [
|
||||||
|
{"status": "ok", "result": {"type": "var", "name": "f", ...}},
|
||||||
|
{"status": "ok", "result": {"printed": "42"}, ...}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### `get-defs`
|
||||||
|
List all vars defined in the current session.
|
||||||
|
|
||||||
|
**Request:**
|
||||||
|
```json
|
||||||
|
{"op": "get-defs"}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{"status": "ok", "defs": ["add", "square"], "ns": "user"}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### `clear`
|
||||||
|
Clear all session definitions.
|
||||||
|
|
||||||
|
**Request:**
|
||||||
|
```json
|
||||||
|
{"op": "clear"}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{"status": "ok", "cleared": true}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### `quit`
|
||||||
|
Exit the REPL.
|
||||||
|
|
||||||
|
**Request:**
|
||||||
|
```json
|
||||||
|
{"op": "quit"}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{"status": "ok", "bye": true}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Response Schema
|
||||||
|
|
||||||
|
All responses contain:
|
||||||
|
- `status` — `"ok"` or `"error"`
|
||||||
|
|
||||||
|
On success:
|
||||||
|
- `result` — Evaluation result object
|
||||||
|
- `type` — `"var"`, `"unknown"`, etc.
|
||||||
|
- `printed` — String representation of the result
|
||||||
|
- `meta` — Metadata
|
||||||
|
- `ns` — Current namespace
|
||||||
|
- `ms` — Execution time in milliseconds
|
||||||
|
- `form` — Original form (if `eval`)
|
||||||
|
|
||||||
|
On error:
|
||||||
|
- `error` — Error object
|
||||||
|
- `type` — Error category
|
||||||
|
- `message` — Human-readable message
|
||||||
|
- `meta` — Same as success
|
||||||
|
|
||||||
|
## Human REPL Commands
|
||||||
|
|
||||||
|
In human mode (`cljnim repl`):
|
||||||
|
|
||||||
|
| Command | Description |
|
||||||
|
|---|---|
|
||||||
|
| `:quit`, `:q` | Exit REPL |
|
||||||
|
| `:help`, `:h` | Show help |
|
||||||
|
| `:defs` | List defined vars |
|
||||||
|
| `:clear` | Clear definitions |
|
||||||
|
| `:ns` | Show current namespace |
|
||||||
@@ -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 структури от данни използват структурно споделяне
|
||||||
@@ -0,0 +1,94 @@
|
|||||||
|
# Clojure/Nim Architecture
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Clojure/Nim is a **compiler**, not an interpreter. It follows the model of ClojureScript: Clojure source is read, macro-expanded, analyzed, and emitted as Nim source code, which then compiles to C and finally to a native binary.
|
||||||
|
|
||||||
|
## Compilation Pipeline
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────┐
|
||||||
|
│ .clj File │
|
||||||
|
└──────┬──────┘
|
||||||
|
│
|
||||||
|
┌────▼────┐
|
||||||
|
│ Reader │ ← EDN parser. Produces Clojure data structures.
|
||||||
|
└────┬────┘
|
||||||
|
│
|
||||||
|
┌────▼────┐
|
||||||
|
│ Macros │ ← defmacro expansion. Operates on Clojure data.
|
||||||
|
└────┬────┘
|
||||||
|
│
|
||||||
|
┌────▼────┐
|
||||||
|
│ Analyzer│ ← Special forms, locals, closure analysis.
|
||||||
|
└────┬────┘
|
||||||
|
│
|
||||||
|
┌────▼────┐
|
||||||
|
│ Emitter │ ← Generates Nim AST / source code.
|
||||||
|
└────┬────┘
|
||||||
|
│
|
||||||
|
┌────▼────┐
|
||||||
|
│ Nim CC │ ← Nim → C compilation.
|
||||||
|
└────┬────┘
|
||||||
|
│
|
||||||
|
┌────▼────┐
|
||||||
|
│ C CC │ ← C → machine code (GCC/Clang).
|
||||||
|
└────┬────┘
|
||||||
|
│
|
||||||
|
┌────▼────┐
|
||||||
|
│ Binary │ ← Single native executable.
|
||||||
|
└─────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
## Key Design Decisions
|
||||||
|
|
||||||
|
### 1. AOT Compiler
|
||||||
|
We compile ahead-of-time, like ClojureScript. This gives us:
|
||||||
|
- Fast runtime execution (C speed)
|
||||||
|
- Small binary size
|
||||||
|
- No interpreter overhead
|
||||||
|
|
||||||
|
The trade-off is that REPL compilation is slower (each form is compiled individually).
|
||||||
|
|
||||||
|
### 2. Clojure Macros on Clojure Data
|
||||||
|
Macro expansion happens **before** reaching Nim. Nim never sees Clojure macros:
|
||||||
|
|
||||||
|
```clojure
|
||||||
|
(defmacro unless [condition & body]
|
||||||
|
`(if (not ~condition)
|
||||||
|
(do ~@body)))
|
||||||
|
```
|
||||||
|
|
||||||
|
This macro operates on `CljVal` objects (Clojure lists, symbols), not Nim AST.
|
||||||
|
|
||||||
|
### 3. Runtime in Nim
|
||||||
|
The `lib/cljnim_runtime.nim` module provides:
|
||||||
|
- `CljVal` — tagged union representing all Clojure values
|
||||||
|
- `cljAdd`, `cljMul`, etc. — polymorphic arithmetic
|
||||||
|
- `cljRepr` — string representation
|
||||||
|
|
||||||
|
### 4. Nim Interop (Future)
|
||||||
|
Instead of Java interop, we will have Nim interop:
|
||||||
|
|
||||||
|
```clojure
|
||||||
|
(nim/import "strutils")
|
||||||
|
(nim/call "strutils.join" ", " ["a" "b"])
|
||||||
|
```
|
||||||
|
|
||||||
|
## Module Responsibilities
|
||||||
|
|
||||||
|
| Module | Role |
|
||||||
|
|---|---|
|
||||||
|
| `src/reader.nim` | Parses `.clj` text into `CljVal` AST |
|
||||||
|
| `src/emitter.nim` | Transforms `CljVal` AST into Nim source |
|
||||||
|
| `src/repl.nim` | Human and AI REPL implementation |
|
||||||
|
| `src/types.nim` | AST node types (used by reader/emitter) |
|
||||||
|
| `src/macros.nim` | Macro expansion engine |
|
||||||
|
| `src/runtime.nim` | Additional runtime helpers |
|
||||||
|
| `lib/cljnim_runtime.nim` | Core runtime library |
|
||||||
|
|
||||||
|
## Memory Model
|
||||||
|
|
||||||
|
- Uses Nim's ORC garbage collector
|
||||||
|
- `CljVal` is a `ref object` (heap-allocated)
|
||||||
|
- Future: persistent data structures use structural sharing
|
||||||
@@ -0,0 +1,150 @@
|
|||||||
|
# Ръководство за Потребителя — 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) са в разработка.
|
||||||
|
```
|
||||||
|
|
||||||
|
### Рекурсия
|
||||||
|
```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 изцяло машинно-четим.
|
||||||
+150
@@ -0,0 +1,150 @@
|
|||||||
|
# Clojure/Nim User Guide
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
### Prerequisites
|
||||||
|
- Nim >= 2.0
|
||||||
|
- GCC or Clang
|
||||||
|
- make
|
||||||
|
|
||||||
|
### Build from Source
|
||||||
|
```bash
|
||||||
|
git clone https://gitlab.com/balvatar/lisp-nim.git
|
||||||
|
cd lisp-nim
|
||||||
|
make build
|
||||||
|
```
|
||||||
|
|
||||||
|
## CLI Commands
|
||||||
|
|
||||||
|
### `compile` — Compile to Nim
|
||||||
|
```bash
|
||||||
|
./cljnim compile input.clj output.nim
|
||||||
|
```
|
||||||
|
Generates a `.nim` file from Clojure source.
|
||||||
|
|
||||||
|
### `run` — Compile and Execute
|
||||||
|
```bash
|
||||||
|
./cljnim run examples/hello.clj
|
||||||
|
```
|
||||||
|
Compiles to Nim, then to C, then to a binary, and runs it.
|
||||||
|
|
||||||
|
### `read` — Parse and Print AST
|
||||||
|
```bash
|
||||||
|
./cljnim read examples/hello.clj
|
||||||
|
```
|
||||||
|
Shows the Clojure AST as S-expressions.
|
||||||
|
|
||||||
|
### `repl` — Interactive REPL
|
||||||
|
```bash
|
||||||
|
# Human-friendly mode
|
||||||
|
./cljnim repl
|
||||||
|
|
||||||
|
# AI mode (structured JSON)
|
||||||
|
./cljnim repl --json
|
||||||
|
```
|
||||||
|
|
||||||
|
## Writing Clojure/Nim Programs
|
||||||
|
|
||||||
|
### Basic Syntax
|
||||||
|
```clojure
|
||||||
|
; Comments start with semicolon
|
||||||
|
|
||||||
|
; Define a variable
|
||||||
|
(def x 42)
|
||||||
|
|
||||||
|
; Define a function
|
||||||
|
(defn greet [name]
|
||||||
|
(println "Hello, " name))
|
||||||
|
|
||||||
|
; Call a function
|
||||||
|
(greet "World")
|
||||||
|
|
||||||
|
; Arithmetic
|
||||||
|
(+ 1 2 3) ; => 6
|
||||||
|
(* 10 20) ; => 200
|
||||||
|
(/ 100 4) ; => 25
|
||||||
|
|
||||||
|
; Conditionals
|
||||||
|
(if (> x 0)
|
||||||
|
"positive"
|
||||||
|
"non-positive")
|
||||||
|
|
||||||
|
; Local bindings
|
||||||
|
(let [a 10
|
||||||
|
b 20]
|
||||||
|
(+ a b)) ; => 30
|
||||||
|
```
|
||||||
|
|
||||||
|
### Working with Data
|
||||||
|
```clojure
|
||||||
|
; Vectors (use Nim seq internally)
|
||||||
|
(def nums [1 2 3 4 5])
|
||||||
|
|
||||||
|
; Keywords
|
||||||
|
(def person {:name "Alice" :age 30})
|
||||||
|
|
||||||
|
; Currently, maps and sets are limited. Full persistent
|
||||||
|
; data structures (HAMT) are in development.
|
||||||
|
```
|
||||||
|
|
||||||
|
### Recursion
|
||||||
|
```clojure
|
||||||
|
(defn factorial [n]
|
||||||
|
(if (= n 0)
|
||||||
|
1
|
||||||
|
(* n (factorial (- n 1)))))
|
||||||
|
|
||||||
|
(println (factorial 5)) ; => 120
|
||||||
|
```
|
||||||
|
|
||||||
|
## AI REPL Guide
|
||||||
|
|
||||||
|
The JSON REPL is designed for programmatic interaction.
|
||||||
|
|
||||||
|
### Start AI REPL
|
||||||
|
```bash
|
||||||
|
./cljnim repl --json
|
||||||
|
```
|
||||||
|
|
||||||
|
### Evaluate a Form
|
||||||
|
```json
|
||||||
|
{"op": "eval", "form": "(+ 1 2 3)"}
|
||||||
|
```
|
||||||
|
Response:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": "ok",
|
||||||
|
"result": {"printed": "6"},
|
||||||
|
"meta": {"ns": "user", "ms": 861, "form": "(+ 1 2 3)"}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Batch Evaluation
|
||||||
|
```json
|
||||||
|
{"op": "eval-batch", "forms": ["(defn f [x] x)", "(f 42)"]}
|
||||||
|
```
|
||||||
|
|
||||||
|
### List Definitions
|
||||||
|
```json
|
||||||
|
{"op": "get-defs"}
|
||||||
|
```
|
||||||
|
Response:
|
||||||
|
```json
|
||||||
|
{"status": "ok", "defs": ["f"], "ns": "user"}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Clear Session
|
||||||
|
```json
|
||||||
|
{"op": "clear"}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Exit
|
||||||
|
```json
|
||||||
|
{"op": "quit"}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Tips
|
||||||
|
|
||||||
|
- Use `:help` in human REPL for available commands.
|
||||||
|
- Definitions in REPL persist across evaluations in the same session.
|
||||||
|
- The `--json` flag makes the REPL fully machine-readable.
|
||||||
@@ -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).
|
||||||
@@ -0,0 +1,51 @@
|
|||||||
|
# Пътна Карта за Разработка
|
||||||
|
|
||||||
|
## Фаза 0: Компилаторно Ядро ✅
|
||||||
|
- [x] Clojure Reader (EDN парсер)
|
||||||
|
- [x] AST → Nim Генератор
|
||||||
|
- [x] CLI (`compile`, `run`, `read`)
|
||||||
|
- [x] Специални форми: `def`, `defn`, `fn`, `let`, `if`, `do`, `quote`
|
||||||
|
- [x] Аритметични оператори
|
||||||
|
- [x] Човешки и JSON REPL
|
||||||
|
- [x] AOT компилация до native бинарни файлове
|
||||||
|
|
||||||
|
## Фаза 1: AI-Native Инструменти 🔄
|
||||||
|
- [x] JSON REPL режим
|
||||||
|
- [x] Batch оценка
|
||||||
|
- [x] Структурирани грешки
|
||||||
|
- [ ] Файлови операции (`file/read`, `file/write`)
|
||||||
|
- [ ] Git операции (`git/commit`, `git/push`)
|
||||||
|
- [ ] nREPL протокол съвместимост
|
||||||
|
|
||||||
|
## Фаза 2: Persistent Структури от Данни
|
||||||
|
- [ ] Persistent Vector (HAMT)
|
||||||
|
- [ ] Persistent Map (HAMT)
|
||||||
|
- [ ] Persistent Set
|
||||||
|
- [ ] `conj`, `assoc`, `dissoc`, `get`, `get-in`
|
||||||
|
- [ ] `nth`, `first`, `rest`, `last`, `count`
|
||||||
|
|
||||||
|
## Фаза 3: Clojure Core Библиотека
|
||||||
|
- [ ] Seq функции: `map`, `filter`, `reduce`, `range`
|
||||||
|
- [ ] Низови функции: `str`, `pr-str`, `slurp`, `spit`
|
||||||
|
- [ ] Мета: `meta`, `with-meta`, `type`
|
||||||
|
|
||||||
|
## Фаза 4: Макро Система
|
||||||
|
- [ ] `defmacro`
|
||||||
|
- [ ] `syntax-quote`, `unquote`, `unquote-splicing`
|
||||||
|
- [ ] `gensym`
|
||||||
|
- [ ] Core макроси: `->`, `->>`, `and`, `or`, `when`, `cond`
|
||||||
|
|
||||||
|
## Фаза 5: Nim Interop
|
||||||
|
- [ ] `nim/import` — Импорт на Nim модули
|
||||||
|
- [ ] `nim/call` — Извикване на Nim функции
|
||||||
|
- [ ] C FFI декларации
|
||||||
|
|
||||||
|
## Фаза 6: Оптимизация
|
||||||
|
- [ ] AOT компилация на цели проекти
|
||||||
|
- [ ] Кеширане на компилирани модули
|
||||||
|
- [ ] Self-hosted REPL (компилация в паметта)
|
||||||
|
|
||||||
|
## Фаза 7: Конкурентност
|
||||||
|
- [ ] Atoms (CAS)
|
||||||
|
- [ ] Agents
|
||||||
|
- [ ] core.async channels (упростен вариант)
|
||||||
@@ -0,0 +1,50 @@
|
|||||||
|
# Development Roadmap
|
||||||
|
|
||||||
|
## Phase 0: Compiler Core ✅
|
||||||
|
- [x] Clojure Reader (EDN parser)
|
||||||
|
- [x] AST → Nim Emitter
|
||||||
|
- [x] CLI (`compile`, `run`, `read`)
|
||||||
|
- [x] Special forms: `def`, `defn`, `fn`, `let`, `if`, `do`, `quote`
|
||||||
|
- [x] Arithmetic operators
|
||||||
|
- [x] Human and JSON REPL
|
||||||
|
|
||||||
|
## Phase 1: AI-Native Tooling 🔄
|
||||||
|
- [x] JSON REPL mode
|
||||||
|
- [x] Batch evaluation
|
||||||
|
- [x] Structured errors
|
||||||
|
- [ ] File operations (`file/read`, `file/write`)
|
||||||
|
- [ ] Git operations (`git/commit`, `git/push`)
|
||||||
|
- [ ] nREPL protocol compatibility
|
||||||
|
|
||||||
|
## Phase 2: Persistent Data Structures
|
||||||
|
- [ ] Persistent Vector (HAMT)
|
||||||
|
- [ ] Persistent Map (HAMT)
|
||||||
|
- [ ] Persistent Set
|
||||||
|
- [ ] `conj`, `assoc`, `dissoc`, `get`, `get-in`
|
||||||
|
- [ ] `nth`, `first`, `rest`, `last`, `count`
|
||||||
|
|
||||||
|
## Phase 3: Clojure Core Library
|
||||||
|
- [ ] Seq functions: `map`, `filter`, `reduce`, `range`
|
||||||
|
- [ ] String functions: `str`, `pr-str`, `slurp`, `spit`
|
||||||
|
- [ ] Meta: `meta`, `with-meta`, `type`
|
||||||
|
|
||||||
|
## Phase 4: Macro System
|
||||||
|
- [ ] `defmacro`
|
||||||
|
- [ ] `syntax-quote`, `unquote`, `unquote-splicing`
|
||||||
|
- [ ] `gensym`
|
||||||
|
- [ ] Core macros: `->`, `->>`, `and`, `or`, `when`, `cond`
|
||||||
|
|
||||||
|
## Phase 5: Nim Interop
|
||||||
|
- [ ] `nim/import` — Import Nim modules
|
||||||
|
- [ ] `nim/call` — Call Nim functions
|
||||||
|
- [ ] C FFI declarations
|
||||||
|
|
||||||
|
## Phase 6: Optimization
|
||||||
|
- [ ] AOT project compilation
|
||||||
|
- [ ] Module caching
|
||||||
|
- [ ] Self-hosted REPL (compile in memory)
|
||||||
|
|
||||||
|
## Phase 7: Concurrency
|
||||||
|
- [ ] Atoms (CAS)
|
||||||
|
- [ ] Agents
|
||||||
|
- [ ] core.async channels (simplified)
|
||||||
Reference in New Issue
Block a user