docs: reorganize into en/ and bg/ subfolders with numbered indices
- New docs/index.md with language selector - docs/en/ — 01-getting-started, 02-architecture, 03-ai-integration, 04-api-reference, 05-user-guide, 06-roadmap - docs/bg/ — same structure in Bulgarian - Root README.md trimmed to quick-start + links to docs/ - Removed old flat docs/ files (ARCHITECTURE.md, AI_FIRST.md, etc.) - Added swap!/reset! examples to getting-started guides
This commit is contained in:
@@ -1,259 +1,76 @@
|
||||
# Clojure/Nim
|
||||
|
||||
> A Clojure dialect that compiles to Nim, then to C, then to native binaries.
|
||||
> A Clojure dialect that compiles to Nim → C → native binaries.
|
||||
|
||||
## What is this?
|
||||
|
||||
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?
|
||||
|
||||
- **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.
|
||||
[]() []() []()
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Clone
|
||||
git clone https://gitlab.com/balvatar/lisp-nim.git
|
||||
cd lisp-nim
|
||||
|
||||
# Build
|
||||
make build
|
||||
|
||||
# Run a file
|
||||
make check
|
||||
./cljnim run examples/hello.clj
|
||||
|
||||
# Start human REPL
|
||||
./cljnim repl
|
||||
|
||||
# Start AI REPL (JSON mode)
|
||||
./cljnim repl --json
|
||||
```
|
||||
|
||||
## Examples
|
||||
## Documentation
|
||||
|
||||
### Hello World
|
||||
```clojure
|
||||
;; examples/hello.clj
|
||||
(println "Hello, Nim world!")
|
||||
(println (+ 1 2 3))
|
||||
```
|
||||
- **[English](docs/en/index.md)** — Getting started, architecture, AI integration, API reference
|
||||
- **[Български](docs/bg/index.md)** — Първи стъпки, архитектура, AI интеграция, API справочник
|
||||
|
||||
```bash
|
||||
$ ./cljnim run examples/hello.clj
|
||||
Hello, Nim world!
|
||||
6
|
||||
```
|
||||
## What is this?
|
||||
|
||||
Clojure/Nim is an **AI-first** Clojure implementation targeting the Nim ecosystem. It compiles Clojure source directly to Nim, then to C, and finally to a native binary.
|
||||
|
||||
### Why?
|
||||
|
||||
- **Native Performance** — 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** — JSON REPL, batch evaluation, AI-assisted error messages and code generation
|
||||
|
||||
## Key Features
|
||||
|
||||
| Feature | Status |
|
||||
|---------|--------|
|
||||
| Compiler (Clojure → Nim → C → native) | ✅ |
|
||||
| REPL with JSON protocol | ✅ |
|
||||
| Macro system (`defmacro`, `syntax-quote`, `->`, `->>`) | ✅ |
|
||||
| Persistent data structures (HAMT vector/map) | ✅ |
|
||||
| Atoms, Agents, Channels | ✅ |
|
||||
| `loop`/`recur` | ✅ |
|
||||
| `try`/`catch`/`finally` | ✅ |
|
||||
| AI integration (DeepSeek, OpenAI, MiMo) | ✅ |
|
||||
| Cross-compilation targets (JS, WASM, shared libs) | ✅ |
|
||||
| 276+ tests | ✅ |
|
||||
|
||||
## Example
|
||||
|
||||
### Functions & Recursion
|
||||
```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)))
|
||||
(println (factorial 5)) ;; => 120
|
||||
```
|
||||
|
||||
```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.
|
||||
## AI-Powered Development
|
||||
|
||||
```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.
|
||||
|
||||
## AI-Powered Assistance
|
||||
|
||||
Clojure/Nim can use paid AI APIs (DeepSeek, OpenAI, Xiaomi MiMo) to help you write and debug code.
|
||||
|
||||
### Setup
|
||||
|
||||
Set one of these environment variables:
|
||||
|
||||
```bash
|
||||
# DeepSeek (recommended, fast & cheap)
|
||||
export DEEPSEEK_API_KEY="sk-..."
|
||||
|
||||
# OpenAI / OpenRouter
|
||||
export OPENAI_API_KEY="sk-..."
|
||||
|
||||
# Xiaomi MiMo
|
||||
export MIMO_API_KEY="..."
|
||||
./cljnim ai "function that sums a list using loop/recur"
|
||||
```
|
||||
|
||||
### Features
|
||||
|
||||
**Auto-error explanation** — When compilation fails, the compiler automatically asks AI for a fix:
|
||||
```bash
|
||||
$ ./cljnim run broken.clj
|
||||
Compilation failed
|
||||
Error: type mismatch: got <int> but expected <string>
|
||||
💡 AI Suggestion:
|
||||
The function `greet` expects a string but you passed an integer.
|
||||
Fix: (defn greet [name] (str "Hello " name))
|
||||
```
|
||||
|
||||
**REPL AI command** — Generate code interactively:
|
||||
```bash
|
||||
$ ./cljnim repl
|
||||
user> :ai function that calculates fibonacci using loop/recur
|
||||
🤖 Thinking...
|
||||
💡 AI Suggestion:
|
||||
(defn fib [n]
|
||||
(loop [a 0 b 1 i n]
|
||||
(if (= i 0)
|
||||
a
|
||||
(recur b (+ a b) (dec i)))))
|
||||
```
|
||||
|
||||
**CLI code generation** — Generate code from terminal:
|
||||
```bash
|
||||
$ ./cljnim ai "function that reads a file line by line"
|
||||
(defn read-lines [filename]
|
||||
(let [content (slurp filename)]
|
||||
(clojure.string/split-lines content)))
|
||||
```
|
||||
|
||||
## 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/
|
||||
│ ├── cljnim.nim # CLI entry point
|
||||
│ ├── reader.nim # Clojure reader / EDN parser
|
||||
│ ├── emitter.nim # Nim code generator
|
||||
│ ├── repl.nim # Human & AI REPL
|
||||
│ ├── eval.nim # Tree-walking interpreter
|
||||
│ ├── deps.nim # Dependency resolution
|
||||
│ ├── core.nim # Core runtime functions
|
||||
│ ├── types.nim # Clojure value types
|
||||
│ ├── macros.nim # Macro expansion engine
|
||||
│ └── runtime.nim # Runtime implementation
|
||||
├── lib/
|
||||
│ ├── cljnim_runtime.nim # Clojure runtime in Nim
|
||||
│ ├── cljnim_pvec.nim # Persistent Vector (HAMT)
|
||||
│ ├── cljnim_pmap.nim # Persistent Map (HAMT)
|
||||
│ └── cljnim_async.nim # core.async channels
|
||||
├── examples/
|
||||
│ ├── hello.clj
|
||||
│ ├── math.clj
|
||||
│ ├── core.clj
|
||||
│ ├── macros.clj
|
||||
│ ├── ffi.clj
|
||||
│ ├── interop.clj
|
||||
│ └── ai_tools.clj
|
||||
├── docs/ # Documentation (EN + BG)
|
||||
├── tests/
|
||||
├── Makefile
|
||||
└── cljnim.nimble
|
||||
```
|
||||
|
||||
## Supported Features
|
||||
|
||||
### Working Now ✅
|
||||
- Reader: numbers, strings, symbols, keywords, lists `()`, vectors `[]`, maps `{}`
|
||||
- Special forms: `def`, `defn`, `fn`, `let`, `if`, `do`, `quote`
|
||||
- Arithmetic: `+`, `-`, `*`, `/`, `=`, `<`, `>`
|
||||
- Functions: `println`, `map`, `filter`, `reduce`
|
||||
- Human REPL and JSON REPL
|
||||
- AOT compilation to native binaries
|
||||
- Persistent data structures (Vector, Map, Set) via HAMT
|
||||
- Macro system (`defmacro`, `->`, `->>`, `and`, `or`, `when`, `cond`)
|
||||
- Nim/C interop
|
||||
- File and Git operations from REPL
|
||||
- Tree-walking interpreter for fast REPL eval
|
||||
- Atoms, Agents, and core.async channels
|
||||
|
||||
See [`docs/ROADMAP.md`](docs/ROADMAP.md) for the full roadmap.
|
||||
|
||||
## Requirements
|
||||
|
||||
- Nim >= 2.0
|
||||
- GCC or Clang
|
||||
- make
|
||||
|
||||
## Documentation
|
||||
|
||||
| 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) | Пътна карта |
|
||||
See [docs/en/03-ai-integration.md](docs/en/03-ai-integration.md) for details.
|
||||
|
||||
## License
|
||||
|
||||
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
|
||||
MIT — see [LICENSE](LICENSE)
|
||||
|
||||
@@ -1,71 +0,0 @@
|
||||
# Phase 5: HAMT Persistent Vector
|
||||
|
||||
## Status: COMPLETE
|
||||
|
||||
### What was implemented
|
||||
|
||||
**Hash Array Mapped Trie (HAMT) Persistent Vector** — 32-way branching trie with path-copying structural sharing, matching Clojure's `PersistentVector` semantics.
|
||||
|
||||
- `lib/cljnim_pvec.nim` — Core implementation
|
||||
- `PersistentVector[T]` — root pointer + count + shift + tail
|
||||
- `pvecConj` — O(log₃₂ N) append with structural sharing
|
||||
- `pvecNth` — O(log₃₂ N) random access
|
||||
- `pvecAssoc` — O(log₃₂ N) update with path copying
|
||||
- `pvecPop` — O(log₃₂ N) remove last
|
||||
- `newPersistentVector` — builder from `seq[T]`
|
||||
- `toSeq` — convert back to `seq[T]`
|
||||
- `len`, `[]` overloads for seq-like interface
|
||||
|
||||
**Integration into Runtime**
|
||||
- `lib/cljnim_runtime.nim`: `ckVector` now stores `PersistentVector[CljVal]`
|
||||
- All 51 `vecData` references migrated to use `pvecNth`/`toSeq`/`count`
|
||||
- `cljVector` constructor builds from `seq[CljVal]` via `newPersistentVector`
|
||||
|
||||
### Architecture Decisions
|
||||
|
||||
1. **Tail optimization**: Like Clojure, maintains a 32-element tail buffer for fast append of recent items
|
||||
2. **Lazy tree growth**: Root promotion only happens when tree is full (`needsNewRoot` check)
|
||||
3. **Path copying**: Every `conj`/`assoc` copies only the nodes along the path to the changed leaf
|
||||
4. **Seq compatibility**: Added `len` and `[]` overloads so `mapIt`, `join`, `items` iterator work transparently
|
||||
|
||||
### Bug fixes during implementation
|
||||
|
||||
- **Recursive `pushLeaf` bug**: When `child.isNil` and `shift != BRANCHING_BITS`, was creating empty internal nodes without recursing to place the leaf. Fixed by calling `pushLeaf(newInternalNode(), index, shift-5, val)` instead of just `newInternalNode()`.
|
||||
|
||||
### Tests
|
||||
|
||||
- `tests/test_pvec.nim` — 14 tests covering:
|
||||
- Empty vector, single element, few elements
|
||||
- `conj` one-by-one (100 elements)
|
||||
- `conj` across tail boundary (32)
|
||||
- `conj` across second level (1024)
|
||||
- `conj` large (10000)
|
||||
- `assoc` in tail and tree
|
||||
- `assoc` preserves old vector (structural sharing)
|
||||
- `pop` from tail, across boundary, to empty
|
||||
|
||||
### Performance Characteristics
|
||||
|
||||
| Operation | Complexity | Notes |
|
||||
|-----------|-----------|-------|
|
||||
| `conj` | O(log₃₂ N) | ~1-3 node copies |
|
||||
| `nth` | O(log₃₂ N) | ~3-5 pointer hops |
|
||||
| `assoc` | O(log₃₂ N) | ~1-3 node copies |
|
||||
| `pop` | O(log₃₂ N) | May pull leaf into tail |
|
||||
| `toSeq` | O(N) | Full traversal |
|
||||
|
||||
For N ≤ 1M, depth ≤ 3 (shift ≤ 15), making operations effectively constant-time.
|
||||
|
||||
### Migration Guide for Other AIs
|
||||
|
||||
If you need to work with vectors in `cljnim_runtime.nim`:
|
||||
|
||||
```nim
|
||||
# Instead of:
|
||||
v.vecData.len # Use: v.vecData.count
|
||||
v.vecData[0] # Use: pvecNth(v.vecData, 0)
|
||||
v.vecData[1..^1] # Use: toSeq(v.vecData)[1..^1]
|
||||
for item in v.vecData: # Use: for item in v.vecData.items:
|
||||
```
|
||||
|
||||
`mapIt` from `sequtils` works transparently thanks to `len` + `items` iterator overloads.
|
||||
@@ -1,106 +0,0 @@
|
||||
# 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,127 @@
|
||||
|
||||
[← Към индекса](index.md)
|
||||
|
||||
---
|
||||
|
||||
# Първи стъпки
|
||||
|
||||
> Диалект на Clojure, който се компилира до Nim → C → нативен бинарен файл.
|
||||
|
||||
## Изисквания
|
||||
|
||||
- **Nim** >= 2.0.0
|
||||
- **GCC** или **Clang**
|
||||
- **make**
|
||||
- **curl** (за AI функциите, незадължително)
|
||||
|
||||
## Инсталация
|
||||
|
||||
```bash
|
||||
git clone https://gitlab.com/balvatar/lisp-nim.git
|
||||
cd lisp-nim
|
||||
make build
|
||||
```
|
||||
|
||||
## Проверка
|
||||
|
||||
```bash
|
||||
make check # компилация + 276+ теста + всички примери
|
||||
```
|
||||
|
||||
## CLI Команди
|
||||
|
||||
| Команда | Описание |
|
||||
|---------|----------|
|
||||
| `./cljnim compile <file.clj>` | Компилиране до Nim изходен код |
|
||||
| `./cljnim compile-lib <file.clj>` | Компилиране с експортирани функции (`*`) |
|
||||
| `./cljnim run <file.clj>` | Компилиране и изпълнение |
|
||||
| `./cljnim read <file.clj>` | Парсиране и печат на AST |
|
||||
| `./cljnim repl` | Стартиране на човешки REPL |
|
||||
| `./cljnim repl --json` | JSON REPL (за AI агенти) |
|
||||
| `./cljnim deps` | Разрешаване на зависимости от `deps.edn` |
|
||||
| `./cljnim -e '<код>'` | Оценка на израз |
|
||||
| `./cljnim ai '<описание>'` | Генериране на Clojure код с AI |
|
||||
|
||||
## Бързи примери
|
||||
|
||||
### Hello World
|
||||
```clojure
|
||||
;; examples/hello.clj
|
||||
(println "Hello, Nim world!")
|
||||
(println (+ 1 2 3))
|
||||
```
|
||||
|
||||
```bash
|
||||
$ ./cljnim run examples/hello.clj
|
||||
Hello, Nim world!
|
||||
6
|
||||
```
|
||||
|
||||
### Функции и рекурсия
|
||||
```clojure
|
||||
(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)))
|
||||
```
|
||||
|
||||
### loop/recur
|
||||
```clojure
|
||||
(defn sum [n]
|
||||
(loop [acc 0 i 1]
|
||||
(if (> i n)
|
||||
acc
|
||||
(recur (+ acc i) (inc i)))))
|
||||
(println (sum 10)) ;; => 55
|
||||
```
|
||||
|
||||
### Atoms (REPL)
|
||||
```clojure
|
||||
user> (def a (atom 0))
|
||||
user> (swap! a inc)
|
||||
1
|
||||
user> (reset! a 42)
|
||||
42
|
||||
user> (deref a)
|
||||
42
|
||||
```
|
||||
|
||||
## AI Настройка (незадължително)
|
||||
|
||||
```bash
|
||||
export DEEPSEEK_API_KEY="sk-..."
|
||||
# или OPENAI_API_KEY, или MIMO_API_KEY
|
||||
```
|
||||
|
||||
Виж [03-ai-integration.md](03-ai-integration.md) за пълна AI документация.
|
||||
|
||||
## Структура на проекта
|
||||
|
||||
```
|
||||
├── src/ # Изходен код на компилатора
|
||||
│ ├── cljnim.nim # CLI входна точка
|
||||
│ ├── reader.nim # EDN парсер
|
||||
│ ├── emitter.nim # Clojure AST → Nim
|
||||
│ ├── eval.nim # Интерпретатор (REPL бърз път)
|
||||
│ └── ai_assist.nim # AI API интеграция
|
||||
├── lib/ # Runtime библиотеки
|
||||
│ ├── cljnim_runtime.nim # Нативен runtime
|
||||
│ └── cljnim_runtime_js.nim # JS runtime
|
||||
├── tests/ # Тестове (8 файла, 276+ теста)
|
||||
├── examples/ # Примери .clj
|
||||
├── benchmarks/ # Бенчмаркове
|
||||
├── docs/ # Документация
|
||||
└── experiments/ # Web, WASM, native-lib target-и
|
||||
```
|
||||
|
||||
## Следващи стъпки
|
||||
|
||||
- [02-architecture.md](02-architecture.md) — Как работи компилаторът
|
||||
- [03-ai-integration.md](03-ai-integration.md) — AI-асистирана разработка
|
||||
- [04-api-reference.md](04-api-reference.md) — JSON REPL протокол
|
||||
- [05-user-guide.md](05-user-guide.md) — Макроси, interop, напреднали шаблони
|
||||
@@ -1,3 +1,8 @@
|
||||
|
||||
[← Към индекса](index.md)
|
||||
|
||||
---
|
||||
|
||||
# Архитектура на Clojure/Nim
|
||||
|
||||
## Общ Преглед
|
||||
@@ -67,14 +72,16 @@ Clojure/Nim е **компилатор**, не интерпретатор. Сле
|
||||
- `cljAdd`, `cljMul`, и т.н. — полиморфна аритметика
|
||||
- `cljRepr` — текстово представяне
|
||||
|
||||
### 4. Nim Interop (Бъдеще)
|
||||
Вместо Java interop, ще имаме Nim interop:
|
||||
### 4. Nim Interop
|
||||
Вместо Java interop, имаме директен Nim interop:
|
||||
|
||||
```clojure
|
||||
(nim/import "strutils")
|
||||
(nim/call "strutils.join" ", " ["a" "b"])
|
||||
(nim/math/sin x)
|
||||
(nim/strutils/toUpper s)
|
||||
```
|
||||
|
||||
Nim модулите се импортират автоматично при извикване през `nim/module/fn` шаблона.
|
||||
|
||||
## Отговорности на Модулите
|
||||
|
||||
| Модул | Роля |
|
||||
@@ -82,13 +89,19 @@ Clojure/Nim е **компилатор**, не интерпретатор. Сле
|
||||
| `src/reader.nim` | Парсира `.clj` текст към `CljVal` AST |
|
||||
| `src/emitter.nim` | Трансформира `CljVal` AST в Nim изходен код |
|
||||
| `src/repl.nim` | Имплементация на human и AI REPL |
|
||||
| `src/eval.nim` | Tree-walking interpreter за бързо in-memory eval |
|
||||
| `src/deps.nim` | Резолюция на зависимости (deps.edn формат) |
|
||||
| `src/core.nim` | Core runtime функции (AOT компилирани) |
|
||||
| `src/types.nim` | Типове на AST възли (използват се от reader/emitter) |
|
||||
| `src/macros.nim` | Двигател за разширяване на макроси |
|
||||
| `src/runtime.nim` | Допълнителни runtime помощници |
|
||||
| `lib/cljnim_runtime.nim` | Основна runtime библиотека |
|
||||
| `lib/cljnim_pvec.nim` | Persistent Vector (HAMT имплементация) |
|
||||
| `lib/cljnim_pmap.nim` | Persistent Hash Map (HAMT имплементация) |
|
||||
| `lib/cljnim_async.nim` | core.async channels runtime |
|
||||
|
||||
## Модел на Паметта
|
||||
|
||||
- Използва Nim's ORC garbage collector
|
||||
- `CljVal` е `ref object` (заделя се на heap)
|
||||
- Бъдеще: persistent структури от данни използват структурно споделяне
|
||||
- Persistent структури от данни (Vector, Map, Set) използват структурно споделяне през HAMT
|
||||
@@ -1,3 +1,8 @@
|
||||
|
||||
[← Към индекса](index.md)
|
||||
|
||||
---
|
||||
|
||||
# AI-First Философия на Дизайна
|
||||
|
||||
## Защо AI-First?
|
||||
@@ -1,3 +1,8 @@
|
||||
|
||||
[← Към индекса](index.md)
|
||||
|
||||
---
|
||||
|
||||
# REPL API Референция
|
||||
|
||||
## JSON REPL Протокол
|
||||
@@ -1,3 +1,8 @@
|
||||
|
||||
[← Към индекса](index.md)
|
||||
|
||||
---
|
||||
|
||||
# Ръководство за Потребителя — Clojure/Nim
|
||||
|
||||
## Инсталация
|
||||
@@ -83,8 +88,8 @@ make build
|
||||
; Ключови думи
|
||||
(def person {:name "Алиса" :age 30})
|
||||
|
||||
; В момента картите и множествата са ограничени.
|
||||
; Пълни persistent структури (HAMT) са в разработка.
|
||||
; Картите и множествата използват persistent HAMT структури
|
||||
; със structural sharing и O(log₃₂ n) операции.
|
||||
```
|
||||
|
||||
### Рекурсия
|
||||
@@ -1,3 +1,8 @@
|
||||
|
||||
[← Към индекса](index.md)
|
||||
|
||||
---
|
||||
|
||||
# Пътна Карта за Разработка
|
||||
|
||||
## Фаза 0: Компилаторно Ядро ✅
|
||||
@@ -41,42 +46,41 @@
|
||||
- [x] Файлови операции: `(file/ls "dir")`, `(file/exists? "path")`
|
||||
- [x] Git операции: `(git/status)`, `(git/commit "msg")`, `(git/push)`
|
||||
- [x] Git операции: `(git/diff)`, `(git/log)`
|
||||
- [ ] nREPL протокол съвместимост
|
||||
- [ ] Tool-call формат за интеграция с AI frameworks
|
||||
- [x] nREPL протокол съвместимост (JSON over TCP, `--tcp PORT`)
|
||||
- [x] Tool-call формат за интеграция с AI frameworks
|
||||
|
||||
## Фаза 5: Persistent Структури от Данни
|
||||
- [ ] Persistent Vector (Hash Array Mapped Trie)
|
||||
- [ ] Persistent Map (HAMT)
|
||||
- [ ] Persistent Set
|
||||
- [ ] `conj`, `assoc`, `dissoc`, `get`, `get-in`
|
||||
- [ ] `nth`, `first`, `rest`, `last`, `count` върху persistent колекции
|
||||
- [ ] Transients за batch мутации
|
||||
## Фаза 5: Persistent Структури от Данни ✅ (Завършена)
|
||||
- [x] Persistent Vector (Hash Array Mapped Trie, 32-way branching)
|
||||
- [x] Persistent Map (HAMT) — `pmapAssoc`, `pmapDissoc`, `pmapGet` в O(log₃₂ n)
|
||||
- [x] Persistent Set
|
||||
- [x] `conj`, `assoc`, `dissoc`, `get`, `get-in`
|
||||
- [x] `nth`, `first`, `rest`, `last`, `count` върху persistent колекции
|
||||
- [x] Transients за batch мутации
|
||||
- [x] `conj!`, `assoc!`, `persistent!`
|
||||
|
||||
## Фаза 6: Clojure Core Библиотека
|
||||
- [ ] `range`, `repeat`, `cycle`, `iterate`
|
||||
- [ ] `take`, `drop`, `partition`, `interleave`, `concat`
|
||||
- [ ] `str`, `pr-str`, `println`, `prn`
|
||||
- [ ] `slurp`, `spit`, `read-line`
|
||||
- [ ] `meta`, `with-meta`, `vary-meta`
|
||||
- [ ] `type`, `instance?`, `satisfies?`
|
||||
## Фаза 6: Clojure Core Библиотека ✅ (Завършена)
|
||||
- [x] `range`, `repeat`, `cycle`, `iterate`
|
||||
- [x] `take`, `drop`, `partition`, `interleave`, `concat`
|
||||
- [x] `str`, `pr-str`, `println`, `prn`
|
||||
- [x] `slurp`, `spit`, `read-line`
|
||||
- [x] `meta`, `with-meta`, `vary-meta`
|
||||
- [x] `type`, `instance?`, `satisfies?`
|
||||
|
||||
## Фаза 7: Компилация на Проекти
|
||||
- [ ] Компилиране на цели проекти (не само отделни файлове)
|
||||
- [ ] Система за namespaces (`ns`, `require`, `use`)
|
||||
- [ ] Кеширане на модули за по-бърз REPL старт
|
||||
- [ ] Резолюция на зависимости
|
||||
## Фаза 7: Компилация на Проекти ✅
|
||||
- [x] Компилиране на цели проекти (не само отделни файлове)
|
||||
- [x] Система за namespaces (`ns`, `(:require [lib :as alias])`)
|
||||
- [x] Кеширане на модули за по-бърз REPL старт
|
||||
- [x] Резолюция на зависимости (deps.edn, Git deps към .deps/)
|
||||
|
||||
## Фаза 8: Self-Hosted REPL
|
||||
- [ ] Компилиране на форми в паметта (без temp файлове)
|
||||
- [ ] Бърз REPL старт (< 100ms)
|
||||
- [ ] Hot code reloading
|
||||
## Фаза 8: Self-Hosted REPL ✅
|
||||
- [x] Компилиране на форми в паметта (tree-walking interpreter, <1ms eval)
|
||||
- [x] Бърз REPL старт (~0.02ms на eval спрямо 1133ms компилиран)
|
||||
- [x] Hot code reloading (def/defn обновяват средата незабавно)
|
||||
|
||||
## Фаза 9: Конкурентност
|
||||
- [ ] Atoms (compare-and-swap)
|
||||
- [ ] Agents
|
||||
- [ ] core.async channels (упростен вариант)
|
||||
## Фаза 9: Конкурентност ✅
|
||||
- [x] Atoms (compare-and-swap)
|
||||
- [x] Agents (send, await, deref — sync dispatch в interpreter)
|
||||
- [x] core.async channels (chan, >!, <!, close!, go — interpreter-first)
|
||||
|
||||
## Известни Проблеми
|
||||
- `->>` threading macro с вложени `map`/`reduce` изисква правилен macro expansion контекст
|
||||
- REPL дефинициите се прекомпилират от нулата при всяка оценка (бавно, но коректно)
|
||||
- Няма истински persistent структури от данни (runtime използва Nim seq/tables)
|
||||
@@ -0,0 +1,36 @@
|
||||
|
||||
[← Към индекса](index.md)
|
||||
|
||||
---
|
||||
|
||||
# Clojure/Nim Документация (Български)
|
||||
|
||||
> Диалект на Clojure, който се компилира до Nim → C → нативен бинарен файл.
|
||||
|
||||
## Съдържание
|
||||
|
||||
| # | Документ | Описание |
|
||||
|---|----------|----------|
|
||||
| 01 | [Първи стъпки](01-getting-started.md) | Инсталация, компилация, CLI команди, бързи примери |
|
||||
| 02 | [Архитектура](02-architecture.md) | Компилационен pipeline, дизайн решения, вътрешна структура |
|
||||
| 03 | [AI Интеграция](03-ai-integration.md) | DeepSeek, OpenAI, MiMo — помощ при грешки, генериране на код, оптимизация, дебъг |
|
||||
| 04 | [API Справочник](04-api-reference.md) | JSON REPL протокол, операции, tool-call формат |
|
||||
| 05 | [Ръководство](05-user-guide.md) | Макроси, threading, interop, напреднали шаблони |
|
||||
| 06 | [Пътна карта](06-roadmap.md) | Завършени фази, бъдещи планове, цели за перформанс |
|
||||
|
||||
## Бърз старт
|
||||
|
||||
```bash
|
||||
git clone https://gitlab.com/balvatar/lisp-nim.git
|
||||
cd lisp-nim
|
||||
make build
|
||||
make check # компилация + тестове + примери
|
||||
./cljnim repl # човешки REPL
|
||||
```
|
||||
|
||||
## Статистика
|
||||
|
||||
- **Тестове:** 276+ в 8 suite-а
|
||||
- **Компилатор:** Nim → C → нативен код
|
||||
- **Target-и:** Linux, macOS, Windows, JS, WASM, C shared libraries
|
||||
- **AI Поддръжка:** DeepSeek API, OpenAI-compatible, Xiaomi MiMo
|
||||
@@ -0,0 +1,127 @@
|
||||
|
||||
[← Back to Index](index.md)
|
||||
|
||||
---
|
||||
|
||||
# Getting Started
|
||||
|
||||
> A Clojure dialect that compiles to Nim → C → native binaries.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **Nim** >= 2.0.0
|
||||
- **GCC** or **Clang**
|
||||
- **make**
|
||||
- **curl** (for AI features, optional)
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
git clone https://gitlab.com/balvatar/lisp-nim.git
|
||||
cd lisp-nim
|
||||
make build
|
||||
```
|
||||
|
||||
## Verify Installation
|
||||
|
||||
```bash
|
||||
make check # build + 276+ tests + all examples
|
||||
```
|
||||
|
||||
## CLI Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `./cljnim compile <file.clj>` | Compile to Nim source |
|
||||
| `./cljnim compile-lib <file.clj>` | Compile to Nim with exported functions (`*`) |
|
||||
| `./cljnim run <file.clj>` | Compile and run binary |
|
||||
| `./cljnim read <file.clj>` | Parse and print AST |
|
||||
| `./cljnim repl` | Start human REPL |
|
||||
| `./cljnim repl --json` | Start JSON REPL (for AI agents) |
|
||||
| `./cljnim deps` | Resolve dependencies from `deps.edn` |
|
||||
| `./cljnim -e '<code>'` | Evaluate expression |
|
||||
| `./cljnim ai '<description>'` | Generate Clojure code with AI |
|
||||
|
||||
## Quick Examples
|
||||
|
||||
### Hello World
|
||||
```clojure
|
||||
;; examples/hello.clj
|
||||
(println "Hello, Nim world!")
|
||||
(println (+ 1 2 3))
|
||||
```
|
||||
|
||||
```bash
|
||||
$ ./cljnim run examples/hello.clj
|
||||
Hello, Nim world!
|
||||
6
|
||||
```
|
||||
|
||||
### Functions & Recursion
|
||||
```clojure
|
||||
(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)))
|
||||
```
|
||||
|
||||
### loop/recur
|
||||
```clojure
|
||||
(defn sum [n]
|
||||
(loop [acc 0 i 1]
|
||||
(if (> i n)
|
||||
acc
|
||||
(recur (+ acc i) (inc i)))))
|
||||
(println (sum 10)) ;; => 55
|
||||
```
|
||||
|
||||
### Atoms (REPL)
|
||||
```clojure
|
||||
user> (def a (atom 0))
|
||||
user> (swap! a inc)
|
||||
1
|
||||
user> (reset! a 42)
|
||||
42
|
||||
user> (deref a)
|
||||
42
|
||||
```
|
||||
|
||||
## AI Setup (Optional)
|
||||
|
||||
```bash
|
||||
export DEEPSEEK_API_KEY="sk-..."
|
||||
# or OPENAI_API_KEY, or MIMO_API_KEY
|
||||
```
|
||||
|
||||
See [03-ai-integration.md](03-ai-integration.md) for full AI documentation.
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
├── src/ # Compiler source
|
||||
│ ├── cljnim.nim # CLI entry point
|
||||
│ ├── reader.nim # EDN parser
|
||||
│ ├── emitter.nim # Clojure AST → Nim
|
||||
│ ├── eval.nim # Tree-walking interpreter (REPL fast path)
|
||||
│ └── ai_assist.nim # AI API integration
|
||||
├── lib/ # Runtime libraries
|
||||
│ ├── cljnim_runtime.nim # Native runtime
|
||||
│ └── cljnim_runtime_js.nim # JS runtime
|
||||
├── tests/ # Test suites (8 files, 276+ tests)
|
||||
├── examples/ # Example .clj files
|
||||
├── benchmarks/ # Performance benchmarks
|
||||
├── docs/ # Documentation
|
||||
└── experiments/ # Web, WASM, native-lib targets
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [02-architecture.md](02-architecture.md) — How the compiler works
|
||||
- [03-ai-integration.md](03-ai-integration.md) — AI-powered development
|
||||
- [04-api-reference.md](04-api-reference.md) — JSON REPL protocol
|
||||
- [05-user-guide.md](05-user-guide.md) — Macros, interop, advanced patterns
|
||||
@@ -1,3 +1,8 @@
|
||||
|
||||
[← Back to Index](index.md)
|
||||
|
||||
---
|
||||
|
||||
# Clojure/Nim Architecture
|
||||
|
||||
## Overview
|
||||
@@ -67,14 +72,16 @@ The `lib/cljnim_runtime.nim` module provides:
|
||||
- `cljAdd`, `cljMul`, etc. — polymorphic arithmetic
|
||||
- `cljRepr` — string representation
|
||||
|
||||
### 4. Nim Interop (Future)
|
||||
Instead of Java interop, we will have Nim interop:
|
||||
### 4. Nim Interop
|
||||
Instead of Java interop, we have direct Nim interop:
|
||||
|
||||
```clojure
|
||||
(nim/import "strutils")
|
||||
(nim/call "strutils.join" ", " ["a" "b"])
|
||||
(nim/math/sin x)
|
||||
(nim/strutils/toUpper s)
|
||||
```
|
||||
|
||||
Nim modules are auto-imported when called via the `nim/module/fn` pattern.
|
||||
|
||||
## Module Responsibilities
|
||||
|
||||
| Module | Role |
|
||||
@@ -82,13 +89,19 @@ Instead of Java interop, we will have Nim interop:
|
||||
| `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/eval.nim` | Tree-walking interpreter for fast in-memory eval |
|
||||
| `src/deps.nim` | Dependency resolution (deps.edn format) |
|
||||
| `src/core.nim` | Core runtime functions (AOT compiled) |
|
||||
| `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 |
|
||||
| `lib/cljnim_pvec.nim` | Persistent Vector (HAMT implementation) |
|
||||
| `lib/cljnim_pmap.nim` | Persistent Hash Map (HAMT implementation) |
|
||||
| `lib/cljnim_async.nim` | core.async channels runtime |
|
||||
|
||||
## Memory Model
|
||||
|
||||
- Uses Nim's ORC garbage collector
|
||||
- `CljVal` is a `ref object` (heap-allocated)
|
||||
- Future: persistent data structures use structural sharing
|
||||
- Persistent data structures (Vector, Map, Set) use structural sharing via HAMT
|
||||
@@ -1,3 +1,8 @@
|
||||
|
||||
[← Back to Index](index.md)
|
||||
|
||||
---
|
||||
|
||||
# AI-First Design Philosophy
|
||||
|
||||
## Why AI-First?
|
||||
@@ -1,3 +1,8 @@
|
||||
|
||||
[← Back to Index](index.md)
|
||||
|
||||
---
|
||||
|
||||
# REPL API Reference
|
||||
|
||||
## JSON REPL Protocol
|
||||
@@ -1,3 +1,8 @@
|
||||
|
||||
[← Back to Index](index.md)
|
||||
|
||||
---
|
||||
|
||||
# Clojure/Nim User Guide
|
||||
|
||||
## Installation
|
||||
@@ -83,8 +88,8 @@ Shows the Clojure AST as S-expressions.
|
||||
; Keywords
|
||||
(def person {:name "Alice" :age 30})
|
||||
|
||||
; Currently, maps and sets are limited. Full persistent
|
||||
; data structures (HAMT) are in development.
|
||||
; Maps and sets use persistent HAMT data structures
|
||||
; with structural sharing and O(log₃₂ n) operations.
|
||||
```
|
||||
|
||||
### Recursion
|
||||
@@ -1,3 +1,8 @@
|
||||
|
||||
[← Back to Index](index.md)
|
||||
|
||||
---
|
||||
|
||||
# Development Roadmap
|
||||
|
||||
## Phase 0: Compiler Core ✅
|
||||
@@ -0,0 +1,36 @@
|
||||
|
||||
[← Back to Index](index.md)
|
||||
|
||||
---
|
||||
|
||||
# Clojure/Nim Documentation (English)
|
||||
|
||||
> A Clojure dialect that compiles to Nim → C → native binaries.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
| # | Document | Description |
|
||||
|---|----------|-------------|
|
||||
| 01 | [Getting Started](01-getting-started.md) | Installation, build, CLI commands, quick examples |
|
||||
| 02 | [Architecture](02-architecture.md) | Compiler pipeline, design decisions, internal structure |
|
||||
| 03 | [AI Integration](03-ai-integration.md) | DeepSeek, OpenAI, MiMo — error assistance, code generation, optimization, debugging |
|
||||
| 04 | [API Reference](04-api-reference.md) | JSON REPL protocol, operations, tool-call format |
|
||||
| 05 | [User Guide](05-user-guide.md) | Macros, threading, interop, advanced patterns |
|
||||
| 06 | [Roadmap](06-roadmap.md) | Completed phases, future plans, performance targets |
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
git clone https://gitlab.com/balvatar/lisp-nim.git
|
||||
cd lisp-nim
|
||||
make build
|
||||
make check # build + tests + examples
|
||||
./cljnim repl # human REPL
|
||||
```
|
||||
|
||||
## Stats
|
||||
|
||||
- **Tests:** 276+ across 8 suites
|
||||
- **Compiler:** Nim → C → native
|
||||
- **Targets:** Linux, macOS, Windows, JS, WASM, C shared libraries
|
||||
- **AI Support:** DeepSeek API, OpenAI-compatible, Xiaomi MiMo
|
||||
@@ -0,0 +1,16 @@
|
||||
# Clojure/Nim Documentation
|
||||
|
||||
> A Clojure dialect that compiles to Nim → C → native binaries.
|
||||
|
||||
## Choose Language / Избор на език
|
||||
|
||||
| 🇬🇧 English | 🇧🇬 Български |
|
||||
|------------|-------------|
|
||||
| [English Documentation](en/index.md) | [Българска Документация](bg/index.md) |
|
||||
|
||||
## Quick Links
|
||||
|
||||
- **GitHub/GitLab:** [lisp-nim](https://gitlab.com/balvatar/lisp-nim)
|
||||
- **Build:** `make build && make check`
|
||||
- **Tests:** 276+ tests across 8 test suites
|
||||
- **AI Integration:** DeepSeek API, OpenAI-compatible, Xiaomi MiMo
|
||||
Reference in New Issue
Block a user