bara-lang/ROADMAP.md

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

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

• Определяне на цели и архитектура
• Избор на подход (изходен Nim код vs директен C)
• Създаване на структура на проекта
• 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.