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