docs: update documentation for May 12 compiler fixes
- CLJNIM_RECOMMENDATIONS.md: mark all 12 recommendations as implemented - README.md: add --lib-path, first-class functions, multi-arity, rest params - User guides (EN/BG): add sections for docstrings, multi-arity, rest params, keyword-as-function, first-class functions, loop/recur, --lib-path flag - TASKS.md: add Phase 11 with all BRing compiler fixes
This commit is contained in:
+151
-109
@@ -1,171 +1,170 @@
|
||||
# Препоръки към cljnim компилатора
|
||||
|
||||
> Събрани по време на разработката на BRing — Ring-подобна уеб библиотека за Bara Lang.
|
||||
>
|
||||
> **Последно обновяване:** 12 май 2026
|
||||
|
||||
---
|
||||
|
||||
## 1. Поддръжка на docstrings в `defn`
|
||||
## 1. Поддръжка на docstrings в `defn` ✅ Имплементирано
|
||||
|
||||
**Проблем:**
|
||||
**Проблем (преди):**
|
||||
```clojure
|
||||
(defn greet "Says hello" [name]
|
||||
(str "Hello " name))
|
||||
```
|
||||
Гърми с:
|
||||
Гърмеше с:
|
||||
```
|
||||
Error: unhandled exception: defn params must be a vector [EmitterError]
|
||||
```
|
||||
|
||||
**Причина:** `defn` в `emitter.nim` очаква вторият аргумент да е вектор с параметри. Docstring-ът се третира като име на параметър.
|
||||
**Решение:** В `emitSpecialForm` за `defn` сега се проверява дали `items[2]` е стринг (docstring) и ако да — се пропуска и се взема `items[3]` като параметри.
|
||||
|
||||
**Препоръка:** В `emitSpecialForm` за `defn` да се провери дали `items[2]` е стринг (docstring) и ако да — да се пропусне и да се вземе `items[3]` като параметри.
|
||||
|
||||
**Workaround за сега:** Не използвайте docstrings в `defn`. Пишете ги като обикновени коментари `;` преди функцията.
|
||||
**Пример (сега работи):**
|
||||
```clojure
|
||||
(defn greet "Says hello" [name]
|
||||
(str "Hello " name))
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Поддръжка на multi-arity `defn`
|
||||
## 2. Поддръжка на multi-arity `defn` ✅ Имплементирано
|
||||
|
||||
**Проблем:**
|
||||
**Проблем (преди):**
|
||||
```clojure
|
||||
(defn greet
|
||||
([name] (greet name "Hello"))
|
||||
([name greeting] (str greeting " " name)))
|
||||
```
|
||||
Гърми с:
|
||||
Гърмеше с:
|
||||
```
|
||||
Error: unhandled exception: defn params must be a vector [EmitterError]
|
||||
```
|
||||
|
||||
**Причина:** Multi-arity синтаксисът не се разпознава. `items[2]` е списък `([name] ...)`, а не вектор.
|
||||
**Решение:** Multi-arity синтаксисът сега се разпознава. Генерира се dispatch по `args.len` в Nim.
|
||||
|
||||
**Препоръка:** Да се добави логика в `emitSpecialForm` за `defn`, която проверява дали `items[2]` е списък от arity тела. Ако да — да се генерира Nim overload или dispatch по `args.len`.
|
||||
|
||||
**Workaround за сега:** Използвайте отделни функции за всяка arity:
|
||||
**Пример (сега работи):**
|
||||
```clojure
|
||||
(defn greet-default [name]
|
||||
(greet name "Hello"))
|
||||
(defn greet
|
||||
([name] (greet name "Hello"))
|
||||
([name greeting] (str greeting " " name)))
|
||||
|
||||
(defn greet [name greeting]
|
||||
(str greeting " " name))
|
||||
(greet "Alice") ;; => "Hello Alice"
|
||||
(greet "Alice" "Hi") ;; => "Hi Alice"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. `(:key map)` синтаксис (keyword като функция)
|
||||
## 3. `(:key map)` синтаксис (keyword като функция) ✅ Имплементирано
|
||||
|
||||
**Проблем:**
|
||||
**Проблем (преди):**
|
||||
```clojure
|
||||
(:request-method req) ; Clojure стандарт
|
||||
```
|
||||
Генерира:
|
||||
```nim
|
||||
cljApply(cljKeyword("request-method"), cljList(@[req]))
|
||||
```
|
||||
А `cljApply` изисква първият аргумент да е `ckFn` и гърми с:
|
||||
Генерираше `cljApply(...)` вместо `cljGet(...)` и гърмеше с:
|
||||
```
|
||||
apply requires a function
|
||||
```
|
||||
|
||||
**Причина:** Когато първият елемент на списък е `ckKeyword`, `emitSpecialForm` го третира като "user-defined function call" и генерира `cljApply` вместо `cljGet`.
|
||||
**Решение:** В `emitSpecialForm`, когато `items[0].kind == ckKeyword`, сега се генерира `cljGet(args[0], keyword)` вместо `cljApply`.
|
||||
|
||||
**Препоръка:** В `emitSpecialForm`, когато `items[0].kind == ckKeyword`, да се генерира `cljGet(args[0], keyword)` вместо `cljApply`.
|
||||
|
||||
**Workaround за сега:** Пишете явно:
|
||||
**Пример (сега работи):**
|
||||
```clojure
|
||||
(get req :request-method)
|
||||
(def req {:request-method :get :uri "/hello"})
|
||||
(:request-method req) ;; => :get
|
||||
(:uri req) ;; => "/hello"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. `&` rest параметри в `defn`
|
||||
## 4. `&` rest параметри в `defn` ✅ Имплементирано
|
||||
|
||||
**Проблем:**
|
||||
**Проблем (преди):**
|
||||
```clojure
|
||||
(defn greet [name & [greeting]]
|
||||
...)
|
||||
```
|
||||
Гърми с:
|
||||
Гърмеше с:
|
||||
```
|
||||
Error: unhandled exception: defn params must be symbols [EmitterError]
|
||||
```
|
||||
|
||||
**Причина:** `&` не се разпознава като специален символ в параметрите.
|
||||
**Решение:** `&` сега се разпознава като специален символ в параметрите. Генерира се Nim код, който приема `seq[CljVal]` и разпределя аргументите.
|
||||
|
||||
**Препоръка:** Да се добави поддръжка за variadic параметри чрез `&`. Може да се генерира Nim код, който приема `seq[CljVal]` и разпределя аргументите.
|
||||
**Пример (сега работи):**
|
||||
```clojure
|
||||
(defn sum-all [x & rest]
|
||||
(+ x (reduce + rest)))
|
||||
|
||||
**Workaround за сега:** Използвайте фиксиран брой аргументи или подавайте колекции (вектори/map-ове) като един аргумент.
|
||||
(sum-all 1 2 3 4) ;; => 10
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Nim interop — mangle на имената
|
||||
## 5. Nim interop — mangle на имената ✅ Имплементирано
|
||||
|
||||
**Проблем:**
|
||||
**Проблем (преди):**
|
||||
```clojure
|
||||
(nim/bring_http/run-server handler port)
|
||||
```
|
||||
Генерира:
|
||||
Генерираше:
|
||||
```nim
|
||||
run-server(handler, port)
|
||||
```
|
||||
Но `-` не е валиден символ в Nim идентификатори. Гърми при компилация на Nim.
|
||||
А `-` не е валиден символ в Nim идентификатори.
|
||||
|
||||
**Причина:** В `emitSpecialForm` за `nim/` interop:
|
||||
```nim
|
||||
var funcChain = parts[2..^1].join(".")
|
||||
**Решение:** В `emitSpecialForm` за `nim/` interop се прилага `sanitizeNimIdent()`, която заменя `-` с `_` и премахва други невалидни символи за Nim.
|
||||
|
||||
**Пример (сега работи):**
|
||||
```clojure
|
||||
(nim/bring_http/run_server handler port) ;; run_server в Nim
|
||||
(nim/strutils/to_upper "hello") ;; to_upper в Nim
|
||||
```
|
||||
Името се предава директно без mangle.
|
||||
|
||||
**Препоръка:** Да се приложи `mangleName()` или подобна функция върху `funcChain`, която заменя `-` с `_` и премахва други невалидни символи за Nim.
|
||||
|
||||
**Workaround за сега:** В Nim модулите използвайте само `camelCase` или `snake_case` имена без тирета.
|
||||
|
||||
---
|
||||
|
||||
## 6. `getLibPath()` — търсене на `lib/` директория
|
||||
## 6. `getLibPath()` — търсене на `lib/` директория ✅ Имплементирано
|
||||
|
||||
**Проблем:**
|
||||
```nim
|
||||
proc getLibPath(): string =
|
||||
let appDir = getAppDir()
|
||||
let candidate1 = appDir / "lib"
|
||||
let candidate2 = appDir.parentDir / "lib"
|
||||
let candidate3 = getCurrentDir() / "lib"
|
||||
if dirExists(candidate1): return candidate1
|
||||
if dirExists(candidate2): return candidate2
|
||||
if dirExists(candidate3): return candidate3
|
||||
```
|
||||
**Проблем (преди):** `getLibPath()` винаги връщаше `appDir/lib`, което правеше невъзможно проекти от други директории да използват свои `lib/` пътища.
|
||||
|
||||
Когато `cljnim` е инсталиран в `/home/ziko/lispnim/`, `candidate1` винаги е `/home/ziko/lispnim/lib` и връща това. Проекти от други директории не могат да добавят свои `lib/` пътища.
|
||||
**Решение:**
|
||||
- Добавен `--lib-path <dir>` глобален CLI флаг.
|
||||
- `getLibPath()` сега проверява в следния ред:
|
||||
1. CLI `--lib-path` override
|
||||
2. `CLJNIM_LIB_PATH` environment variable
|
||||
3. Текуща директория `lib/`
|
||||
4. Приложение `lib/`
|
||||
|
||||
**Препоръка:** Да се поддържа `CLJNIM_LIB_PATH` environment variable или `--lib-path` CLI флаг. Алтернативно, `candidate3` (текущата директория) да се проверява първи, преди `appDir`.
|
||||
|
||||
**Workaround за сега:** Символна връзка на Nim модулите в `cljnim/lib/`:
|
||||
**Пример:**
|
||||
```bash
|
||||
ln -s /path/to/project/lib/my_module.nim /home/ziko/lispnim/lib/my_module.nim
|
||||
# Със собствена lib директория
|
||||
./cljnim --lib-path ./my_project/lib run app.clj
|
||||
|
||||
# С environment variable
|
||||
export CLJNIM_LIB_PATH=./my_project/lib
|
||||
./cljnim run app.clj
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Поддръжка на `:paths` в `deps.edn`
|
||||
## 7. Поддръжка на `:paths` в `deps.edn` ✅ Имплементирано
|
||||
|
||||
**Проблем:** `deps.nim` парсира само `:deps` от `deps.edn`, но не и `:paths`.
|
||||
**Проблем (преди):** `deps.nim` парсираше само `:deps` от `deps.edn`, но не и `:paths`.
|
||||
|
||||
**Причина:**
|
||||
```nim
|
||||
proc parseDepsMap(depsMap: CljVal): seq[Dependency] =
|
||||
# Парсира само :deps
|
||||
**Решение:** Добавен е парсинг на `:paths` от `deps.edn` и се включват в `searchPaths` при компилация.
|
||||
|
||||
**Пример (сега работи):**
|
||||
```clojure
|
||||
;; deps.edn
|
||||
{:paths ["src" "lib"]
|
||||
:deps {org.clojure/core.async {:mvn/version "1.6.681"}}}
|
||||
```
|
||||
|
||||
**Препоръка:** Да се добави парсинг на `:paths` и да се включват в `searchPaths` при компилация.
|
||||
|
||||
**Workaround за сега:** Clojure файловете трябва да са в структура, която съвпада с namespace имената, относително към текущата директория.
|
||||
|
||||
---
|
||||
|
||||
## 8. `loop` с `if/else` — проблеми с `discard`
|
||||
## 8. `loop` с `if/else` — проблеми с `discard` ✅ Имплементирано
|
||||
|
||||
**Проблем:**
|
||||
**Проблем (преди):**
|
||||
```clojure
|
||||
(loop [pairs (seq headers)]
|
||||
(if (empty? pairs)
|
||||
@@ -175,71 +174,114 @@ proc parseDepsMap(depsMap: CljVal): seq[Dependency] =
|
||||
v
|
||||
(recur (rest pairs))))))
|
||||
```
|
||||
|
||||
Генерира код, в който `cljNil()` в `else` клона не е discard-нат правилно и Nim гърми с:
|
||||
Гърмеше с:
|
||||
```
|
||||
expression 'cljNil()' is of type 'CljVal' and has to be used (or discarded)
|
||||
```
|
||||
|
||||
**Причина:** `emitSpecialForm` за `loop` добавя `break` след тялото, но `if/else` вътре в `while true:` блок не винаги връща стойност във всички клонове.
|
||||
**Решение:**
|
||||
- Добавен е `loopResult` променлива, която събира резултата.
|
||||
- Подобрено е генерирането на `loop` така, че всички клонове на `if` вътре да връщат стойност правилно.
|
||||
- Добавена е `needsValue` логика — `loop` се wrap-ва в IIFE `(proc(): CljVal = ...)()` когато е в expression context (напр. като аргумент на функция, в `let` RHS, или като последна стойност в програма).
|
||||
|
||||
**Препоръка:** Да се подобри генерирането на `loop` така, че всички клонове на `if` вътре да връщат стойност или да се използва `result = ...` pattern.
|
||||
**Пример (сега работи):**
|
||||
```clojure
|
||||
(defn find-header [headers name]
|
||||
(loop [pairs (seq headers)]
|
||||
(if (empty? pairs)
|
||||
nil
|
||||
(let [[k v] (first pairs)]
|
||||
(if (= k name)
|
||||
v
|
||||
(recur (rest pairs)))))))
|
||||
|
||||
**Workaround за сега:** Използвайте `filter` + `first` вместо ръчен `loop`/`recur`.
|
||||
(find-header [[:content-type "text/html"] [:accept "*/*"]] :accept)
|
||||
;; => "*/*"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Конфликти на имена между Clojure и Nim
|
||||
## 9. Конфликти на имена между Clojure и Nim ✅ Имплементирано
|
||||
|
||||
**Проблем:** Nim е case-insensitive за първата буква и игнорира `_`. Значи:
|
||||
- `parseQueryString` ≡ `parse_query_string` ≡ `parsequerystring`
|
||||
|
||||
Ако cljnim генерира `proc parse_query_string` и съществува `proc parseQueryString` в импортиран модул, Nim ги третира като едно и също име. Това води до:
|
||||
- Презаписване на функцията
|
||||
- Безкрайна рекурсия, ако едната извиква другата
|
||||
Ако cljnim генерира `proc parse_query_string` и съществува `proc parseQueryString` в импортиран модул, Nim ги третира като едно и също име.
|
||||
|
||||
**Препоръка:** Да се добави prefix към всички генерирани Nim процедури, например `clj_`:
|
||||
**Решение:** Добавен е `clj_` prefix към всички генерирани Nim процедури от Clojure код:
|
||||
```nim
|
||||
proc clj_parse_query_string(...) ; вместо parse_query_string
|
||||
```
|
||||
|
||||
**Workaround за сега:** В Nim runtime модулите използвайте уникални имена с префикс (напр. `bringParseQueryString`).
|
||||
За `nim/` interop се използва `sanitizeNimIdent()` без prefix, така че native Nim имената да не се чупят.
|
||||
|
||||
---
|
||||
|
||||
## 10. `when isMainModule` в генерирания код
|
||||
## 10. `when isMainModule` в генерирания код ✅ Имплементирано
|
||||
|
||||
**Проблем:** `when isMainModule` в края на генерирания Nim файл означава, че ако файлът се импортира от друг Nim модул, `main` кодът няма да се изпълни. Това прави невъзможно създаването на "библиотечни" Clojure файлове, които съдържат и дефиниции, и изпълним код.
|
||||
**Проблем (преди):** `when isMainModule` в края на генерирания Nim файл означаваше, че ако файлът се импортира от друг Nim модул, `main` кодът няма да се изпълни.
|
||||
|
||||
**Препоръка:** Да се добави флаг `--lib` или подобен, който да генерира код без `when isMainModule` за библиотечни файлове.
|
||||
|
||||
**Workaround за сега:** Използвайте `cljnim compile file.clj output.nim` и после ръчно `nim c output.nim`.
|
||||
**Решение:** `emitProgramLib` сега skip-ва `when isMainModule` guard, което позволява генерирането на "библиотечни" Clojure файлове.
|
||||
|
||||
---
|
||||
|
||||
## 11. Поддръжка на `try`/`catch`/`finally`
|
||||
## 11. Поддръжка на `try`/`catch`/`finally` ✅ Имплементирано
|
||||
|
||||
**Статус:** Изглежда се поддържа, но не беше тествана обстойно по време на разработката на BRing.
|
||||
**Решение:**
|
||||
- `finally` блок сега правилно discard-ва expression резултатите.
|
||||
- `catch` handler използва оригиналното име за scope tracking.
|
||||
|
||||
**Препоръка:** Да се добавят тестове за exception handling в HTTP контекст (грешки при парсиране, мрежови грешки).
|
||||
**Пример (сега работи):**
|
||||
```clojure
|
||||
(try
|
||||
(risky-operation)
|
||||
(catch Exception e
|
||||
(println "Error:" (:message e)))
|
||||
(finally
|
||||
(cleanup)))
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 12. First-class функции (defn като стойности) ✅ Имплементирано
|
||||
|
||||
**Проблем (преди):** User-defined `defn` функции не можеха да се подават като стойности на други функции (напр. `map`, `filter`, `apply`).
|
||||
|
||||
**Решение:**
|
||||
- Проследяват се арностите на функциите в `definedFnArities` таблица.
|
||||
- Когато символ на `defn` се използва като стойност, се генерира `cljFn` wrapper:
|
||||
- Multi-arity / rest: `cljFn(procName)` (вече е `seq[CljVal]`)
|
||||
- Single-arity: `cljFn(proc(args): procName(args[0], ...))`
|
||||
- Директни извиквания остават непроменени (fast path).
|
||||
|
||||
**Пример (сега работи):**
|
||||
```clojure
|
||||
(defn square [x] (* x x))
|
||||
|
||||
(map square [1 2 3 4]) ;; => [1 4 9 16]
|
||||
(filter odd? [1 2 3 4]) ;; => [1 3]
|
||||
(apply + [1 2 3]) ;; => 6
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Обобщена таблица
|
||||
|
||||
| # | Проблем | Трудност | Приоритет |
|
||||
|---|---------|----------|-----------|
|
||||
| 1 | Docstrings в `defn` | Лесно | Висок |
|
||||
| 2 | Multi-arity `defn` | Средно | Висок |
|
||||
| 3 | `(:key map)` синтаксис | Лесно | Висок |
|
||||
| 4 | `&` rest параметри | Средно | Среден |
|
||||
| 5 | Nim interop mangle | Лесно | Висок |
|
||||
| 6 | `getLibPath()` | Лесно | Среден |
|
||||
| 7 | `:paths` в deps.edn | Средно | Среден |
|
||||
| 8 | `loop` + `if/else` | Средно | Среден |
|
||||
| 9 | Конфликти на имена | Средно | Висок |
|
||||
| 10 | `when isMainModule` | Лесно | Нисък |
|
||||
| # | Проблем | Статус | Commit |
|
||||
|---|---------|--------|--------|
|
||||
| 1 | Docstrings в `defn` | ✅ Готово | e36bf4e |
|
||||
| 2 | Multi-arity `defn` | ✅ Готово | e36bf4e |
|
||||
| 3 | `(:key map)` синтаксис | ✅ Готово | e36bf4e |
|
||||
| 4 | `&` rest параметри | ✅ Готово | e36bf4e |
|
||||
| 5 | Nim interop mangle | ✅ Готово | e36bf4e, 3aaf3c0 |
|
||||
| 6 | `getLibPath()` / `--lib-path` | ✅ Готово | e36bf4e, 9a8519d |
|
||||
| 7 | `:paths` в deps.edn | ✅ Готово | e36bf4e |
|
||||
| 8 | `loop` + `if/else` discard | ✅ Готово | e36bf4e, a1a65f1 |
|
||||
| 9 | Конфликти на имена (`clj_` prefix) | ✅ Готово | fb8928e, 3aaf3c0 |
|
||||
| 10 | `when isMainModule` | ✅ Готово | e36bf4e |
|
||||
| 11 | `try`/`catch`/`finally` | ✅ Готово | fb8928e |
|
||||
| 12 | First-class `defn` функции | ✅ Готово | aac39a0 |
|
||||
|
||||
---
|
||||
|
||||
*Документът е съставен по време на разработката на [BRing](https://github.com/) — нативна Clojure уеб библиотека за cljnim.*
|
||||
*Последно обновяване: 12 май 2026*
|
||||
|
||||
Reference in New Issue
Block a user