Add bilingual documentation (EN + BG) in docs/
This commit is contained in:
@@ -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