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-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 манипулация
|
||||
- **Производителност**: Компилиран към C, Nim дава C-подобна скорост с Lisp-удобство
|
||||
- **Размер**: Минимален runtime footprint в сравнение с JVM
|
||||
- **Метапрограмиране**: Съчетание на Clojure макроси и Nim макроси
|
||||
- **Native Performance**: Compiles to C via Nim. No JVM warmup, no GC pauses.
|
||||
- **Tiny Binaries**: Single-file executables, often under 1MB.
|
||||
- **Nim Ecosystem**: Direct access to Nim and C libraries via FFI.
|
||||
- **AI-Native**: Built for AI agents working in terminals — structured JSON REPL, batch evaluation, git integration.
|
||||
|
||||
## Архитектура
|
||||
|
||||
```
|
||||
Clojure Изходен Код (.clj)
|
||||
↓
|
||||
Clojure Reader (Clojure → Clojure Data)
|
||||
↓
|
||||
Макро Разширение (Clojure Macros)
|
||||
↓
|
||||
AST Транслатор (Clojure AST → Nim AST)
|
||||
↓
|
||||
Nim Компилатор
|
||||
↓
|
||||
C Код → Машинен Код
|
||||
```
|
||||
|
||||
## Статус
|
||||
|
||||
> ⚠️ **Ранен етап** — Проектът е във фаза на планиране и базова имплементация.
|
||||
|
||||
Виж [ROADMAP.md](ROADMAP.md) за текущия прогрес.
|
||||
|
||||
## Бърз Старт
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Клониране
|
||||
git clone <repo-url>
|
||||
cd clojure-nim
|
||||
# Clone
|
||||
git clone https://gitlab.com/balvatar/lisp-nim.git
|
||||
cd lisp-nim
|
||||
|
||||
# Изграждане
|
||||
# Build
|
||||
make build
|
||||
|
||||
# REPL
|
||||
./cljnim
|
||||
|
||||
# Изпълнение на файл
|
||||
# Run a file
|
||||
./cljnim run examples/hello.clj
|
||||
|
||||
# Start human REPL
|
||||
./cljnim repl
|
||||
|
||||
# Start AI REPL (JSON mode)
|
||||
./cljnim repl --json
|
||||
```
|
||||
|
||||
## Примери
|
||||
## Examples
|
||||
|
||||
### Hello World
|
||||
```clojure
|
||||
;; hello.clj
|
||||
(ns hello)
|
||||
;; examples/hello.clj
|
||||
(println "Hello, Nim world!")
|
||||
(println (+ 1 2 3))
|
||||
```
|
||||
|
||||
(println "Здравей, Nim свят!")
|
||||
```bash
|
||||
$ ./cljnim run examples/hello.clj
|
||||
Hello, Nim world!
|
||||
6
|
||||
```
|
||||
|
||||
(defn факториел [n]
|
||||
(if (<= n 1)
|
||||
### Functions & Recursion
|
||||
```clojure
|
||||
;; examples/math.clj
|
||||
(defn square [x]
|
||||
(* x x))
|
||||
|
||||
(defn factorial [n]
|
||||
(if (= n 0)
|
||||
1
|
||||
(* n (факториел (- n 1)))))
|
||||
(* n (factorial (- n 1)))))
|
||||
|
||||
(println "5! =" (факториел 5))
|
||||
(let [a 5]
|
||||
(println (square a))
|
||||
(println (factorial a)))
|
||||
```
|
||||
|
||||
```clojure
|
||||
;; Работа със структури от данни
|
||||
(def данни
|
||||
{:име "Иван"
|
||||
:възраст 30
|
||||
:езици ["Clojure" "Nim" "C"]})
|
||||
|
||||
(println (get-in данни [:езици 0]))
|
||||
;; => "Clojure"
|
||||
```bash
|
||||
$ ./cljnim run examples/math.clj
|
||||
25
|
||||
120
|
||||
```
|
||||
|
||||
## Структура на Проекта
|
||||
## 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/
|
||||
│ ├── reader/ # Clojure reader (EDN парсер)
|
||||
│ ├── analyzer/ # Semantic анализатор
|
||||
│ ├── macros/ # Core macros (defn, let, if, и т.н.)
|
||||
│ ├── emitter/ # Генератор на Nim код
|
||||
│ ├── runtime/ # Clojure runtime в Nim
|
||||
│ └── repl/ # Интерактивна обвивка
|
||||
│ ├── cljnim.nim # CLI entry point
|
||||
│ ├── reader.nim # Clojure reader / EDN parser
|
||||
│ ├── emitter.nim # Nim code generator
|
||||
│ ├── repl.nim # Human & AI REPL
|
||||
│ ├── types.nim # Clojure value types
|
||||
│ ├── macros.nim # Macro expansion engine
|
||||
│ └── runtime.nim # Runtime implementation
|
||||
├── lib/
|
||||
│ └── core.clj # Clojure core библиотека
|
||||
├── tests/ # Тестове
|
||||
├── examples/ # Примери
|
||||
│ └── cljnim_runtime.nim # Clojure runtime in Nim
|
||||
├── examples/
|
||||
│ ├── hello.clj
|
||||
│ └── math.clj
|
||||
├── docs/ # Documentation (EN + BG)
|
||||
├── tests/
|
||||
├── 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
|
||||
- GCC или Clang
|
||||
- GCC or Clang
|
||||
- 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 и екипът
|
||||
- [Nim](https://nim-lang.org/) — Andreas Rumpf и общността
|
||||
- Вдъхновено от ClojureScript, Babashka и Clojerl
|
||||
MIT License — see [LICENSE](LICENSE).
|
||||
|
||||
## 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