# Пътна Карта: Clojure/Nim

## Фаза 0: Инфраструктура и Планиране ✅

- [x] Определяне на цели и архитектура
- [x] Избор на подход (изходен Nim код vs директен C)
- [x] Създаване на структура на проекта
- [ ] CI/CD pipeline
- [ ] Система за тестване

## Фаза 1: Reader (Clojure → Clojure Data Structures)

**Цел:** Правилно парсиране на Clojure синтаксис към Clojure структури от данни.

- [ ] Символи (`sym`, `foo/bar`)
- [ ] Ключови думи (`:key`, `:ns/key`)
- [ ] Числа (integers, floats, ratios, big ints)
- [ ] Низове с escape sequences
- [ ] Коментари (`;`)
- [ ] Колекции:
  - [ ] Списъци `(...)`
  - [ ] Вектори `[...]`
  - [ ] Maps `{...}`
  - [ ] Sets `#{...}`
- [ ] Цитиране (`'`, `` ` ``, `~`, `~@`, `#`)
- [ ] Четене на dispatch macros (`#'`, `#_`, `#{}`, etc.)
- [ ] Reader conditionals (`#?()`)
- [ ] Метаданни (`^`)

## Фаза 2: Runtime Структури от Данни

**Цел:** Имплементиране на Clojure структурите от данни в Nim.

- [ ] **Persistent Vector** (Hash-mapped trie, като Clojure's HMT)
- [ ] **Persistent Map** (Hash-mapped trie)
- [ ] **Persistent Set** (върху Map)
- [ ] **Linked List** (свързан списък за sequences)
- [ ] **Lazy Seq**
- [ ] **Atoms** (STM ще дойде по-късно)
- [ ] **Keywords** (interned)
- [ ] **Symbols**
- [ ] **Vars**
- [ ] **Namespaces**

## Фаза 3: Макро Система и AST

**Цел:** Clojure макроси, които работят върху Clojure структури.

- [ ] **Clojure AST** представяне в Nim
- [ ] **Macro expansion engine**
- [ ] Специални форми:
  - [ ] `def`
  - [ ] `fn` / `defn`
  - [ ] `let` / `letfn`
  - [ ] `if` / `when` / `cond`
  - [ ] `do`
  - [ ] `quote`
  - [ ] `loop` / `recur`
  - [ ] `throw` / `try` / `catch` / `finally`
  - [ ] `var`
  - [ ] `binding` (dynamic vars)
- [ ] Core макроси:
  - [ ] `defmacro`
  - [ ] `->`, `->>`
  - [ ] `and`, `or`
  - [ ] `cond->`, `cond->>`
  - [ ] `doto`
  - [ ] `for`, `doseq`
  - [ ] `lazy-seq`

## Фаза 4: Nim Code Emitter

**Цел:** Транслиране на Clojure AST към Nim код.

- [ ] **Symbol мапинг** (Clojure → Nim naming)
- [ ] **Type inference** (основно)
- [ ] **Emitter за специални форми**:
  - [ ] Функции (`proc` в Nim)
  - [ ] Променливи (`var` / `let` / `const`)
  - [ ] Условни изрази (`if` / `case`)
  - [ ] Цикли
  - [ ] Изключения (`try` / `except`)
- [ ] **Interop**:
  - [ ] Извикване на Nim функции от Clojure
  - [ ] Извикване на C библиотеки
  - [ ] FFI механизъм
- [ ] **Type hints** поддръжка

## Фаза 5: Core Библиотека

**Цел:** Имплементация на Clojure core функции.

### 5.1 Функции за Колекции
- [ ] `map`, `filter`, `reduce`
- [ ] `first`, `rest`, `next`, `last`
- [ ] `conj`, `into`
- [ ] `assoc`, `dissoc`, `get`, `get-in`
- [ ] `update`, `update-in`
- [ ] `keys`, `vals`
- [ ] `count`, `empty?`, `seq`
- [ ] `take`, `drop`, `partition`
- [ ] `concat`, `interleave`

### 5.2 Функции за Низове
- [ ] `str`, `pr-str`, `println`, `prn`
- [ ] `subs`, `clojure.string/` namespace

### 5.3 Функции за IO
- [ ] `slurp`, `spit`
- [ ] `read-line`

### 5.4 Функции за Мета
- [ ] `meta`, `with-meta`, `vary-meta`
- [ ] `type`, `instance?`

## Фаза 6: REPL и Инструменти

**Цел:** Интерактивна среда за разработка.

- [ ] **REPL цикъл** (Read-Eval-Print-Loop)
- [ ] **Hot reloading** на код
- [ ] **Error reporting** с Clojure стек тракове
- [ ] **Auto-completion**
- [ ] **Doc strings** (`doc` функция)
- [ ] **Source** (`source` функция)
- [ ] **AOT компилация**

## Фаза 7: Многонишковост и STM (по-късно)

**Цел:** Clojure's конкурентност модел.

- [ ] **Atoms** (CAS)
- [ ] **Agents**
- [ ] **Refs + Software Transactional Memory**
- [ ] **Futures** / **Promises**
- [ ] **core.async** (channels, go blocks) — голяма задача

## Фаза 8: Оптимизации и Полиране

- [ ] **Protocol имплементация** (като Clojure protocols)
- [ ] **Multimethods**
- [ ] **Records и Types**
- [ ] **Бързо стартиране** (малък runtime)
- [ ] **Малък размер на бинарния файл**
- [ ] **Подобрена производителност** на persistent структурите
- [ ] **Tree shaking** / Dead code elimination

## Бъдещи Идеи

- **GraalVM нативен образ** алтернатива (Clojure/Nim като lighter alternative)
- **Babashka-подобен скриптов инструмент**
- **Nim библиотеки достъпни директно** от Clojure
- **ClojureScript съвместимост** (споделен код)
- **LSP/Language Server** за Clojure/Nim
- **nREPL съвместимост**

---

## Текущ Фокус

Следваща стъпка: **Фаза 1 — Reader**

Ще започнем с имплементация на базов Clojure reader, който може да парсира:
1. Числа и низове
2. Символи и keywords
3. Специални знаци (`'`, `` ` ``, `~`, `@`)
4. Списъци и вектори

Първият milestone е работещ reader, който може да обработи `(+ 1 2)` и да върне правилна Clojure data structure.