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)
|
||||
|
||||
Reference in New Issue
Block a user