bara-lang/README.md

# Clojure/Nim

> A Clojure dialect that compiles to Nim, then to C, then to 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
./cljnim run examples/hello.clj

# Start human REPL
./cljnim repl

# Start AI REPL (JSON mode)
./cljnim repl --json
```

## 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
;; 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 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/
│   ├── 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/
│   └── cljnim_runtime.nim   # Clojure runtime in Nim
├── examples/
│   ├── hello.clj
│   └── math.clj
├── docs/                    # Documentation (EN + BG)
├── tests/
├── Makefile
└── 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 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) | Пътна карта |

## 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