simon/jolt
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Phase 4: deftype/defrecord completion

Browse source 
- evaluator.janet: fix set! to handle (.-field obj) shorthand
  Previously only recognized (. obj -field) format
- core.janet: rewrite core-defrecord to emit (deftype ...) instead of
  plain def with array-map constructor
- core.janet: fix core-map? to recognize deftype table instances
  (and returns last truthy, not boolean true — wrap in if)
- core.janet: fix core-count to skip :jolt/deftype key for records
- core.janet: add ->TypeName arrow factory that calls TypeName.
  constructor via Clojure form emission
- 11 new tests: deftype fields/mutation/instance?, defrecord
  construction/map-behavior/fields/factories, record equality
- map->TypeName factory deferred (needs get/symbol resolution fix)
- 317 tests pass, 0 failures
This commit is contained in:
Yogthos 2026-06-02 21:10:33 -04:00
parent fc7f49487b
commit fb66851e06
8 changed files with 204 additions and 284 deletions
Download patch file Download diff file Expand all files Collapse all files

143
.dirge/skills/jolt-dev/SKILL.md
View file

@ -1,9 +1,6 @@
---
name: jolt-dev
description: Jolt development workflow — build, test, special form patterns, Janet gotchas
---
# jolt-dev
# Jolt Development
Jolt development workflow — build, test, special form patterns, Janet gotchas
## Build & Test
@ -12,29 +9,8 @@ cd /Users/yogthos/src/jolt
jpm build # produces build/jolt
jpm test # runs all tests
janet test/foo.janet # run a single test file from project root
janet -k file.janet # check parse without executing (useful for syntax validation)
```
## Python3 batch edits
When the `edit` tool is blocked by syntax checker false positives on complex multi-line replacements, use `python3` for batch text edits:
```bash
python3 << 'PYEOF'
with open('src/jolt/core.janet') as f:
content = f.read()
content = content.replace('old text', 'new text')
with open('src/jolt/core.janet', 'w') as f:
f.write(content)
PYEOF
```
Always run `janet -k file.janet` after to verify syntax.
## Compiler Development
See `jolt-compiler` skill for the Clojure→Janet source-to-source compiler workflow.
## Janet Eval Pipeline (critical)
Janet's `(parse s)` does NOT return a parsed form — it returns `[symbol, error-position]`.
@ -57,66 +33,13 @@ When you need to mutate a local with `set`, use `(var x nil)` not `(def x nil)`.
## Compiler (see also `jolt-compiler` skill)
`src/jolt/compiler.janet` — Clojure→Janet source compiler with macro expansion.
`test/compiler-test.janet` — 11 test groups covering all ops.
Key design decision: **compile-and-eval emits Janet DATA STRUCTURES, not source strings**, because Janet's `eval` doesn't see `use`-imported symbols. `core-fn-values` table resolves Janet names to actual function values at compile time.
## Compiler Development
### Adding a new op to the compiler
1. Add match arm in `analyze-form` — maps Clojure form → AST node
2. Add `emit-*-str` for source-to-source path, then arm in `emit-ast` dispatch
3. Add `emit-*-expr` for data-structure path, then arm in `emit-expr` dispatch
4. Add tests
### Emitter patterns
**String emitter**: `(buffer/push buf "...")` → source text
**Data-structure emitter**: `['keyword val1 val2]` → eval-able tuples
### Janet eval gotchas
- Bare tuples are function calls — always use `['tuple ...]` or `(tuple ...)`
- `eval` scope: symbols from `(use ...)` not available — embed function VALUES
- Janet `try`: `(try body ([err] handler))` — not `(catch sym handler)`
- Core `-` maps to `core-sub` (NOT `core--`)
### Loop compilation
`(loop* [x 0] body-with-recur)` → `(do (var name nil) (set name (fn [x] body)) (name 0))`
Recur rewrites to `(loop-name arg...)` via `:jolt/current-loop` binding.
### Quote: use `raw-form->janet` converter, never re-analyze
### Macro expansion: pass ctx to `analyze-form`, check `resolve-macro`, expand + re-analyze
## Special Form Checklist
To add a new special form to the evaluator AND compiler:
1. Add the name to `special-symbol?` in `src/jolt/evaluator.janet`
2. Add a match arm in `eval-list` (the match on `name`)
3. Add tests in `test/evaluator-test.janet`
The match arm receives `ctx`, `bindings`, and `form` (the full list). Use `(in form 1)` for first arg, etc.
**Non-symbol heads** (keywords, etc.): `eval-list` first checks `(and (struct? first-form) (= :symbol (...)))` before extracting `name`. If not a symbol, falls through to default function application.
### Current special forms (22):
`quote`, `syntax-quote`, `unquote`, `unquote-splicing`, `do`, `if`, `def`, `defmacro`, `fn*`, `let*`, `loop*`, `recur`, `throw`, `try`, `set!`, `var`, `locking`, `instance?`, `defmulti`, `defmethod`, `deftype`, `new`, `.`
## Compiler Development
### Architecture
`src/jolt/compiler.janet` (721 lines). Two emitter paths:
- `compile-form` → `emit-ast` → Janet source string (debug/display)
- `compile-and-eval` → `emit-expr` → Janet data structures (direct eval, resolved fn values)
### Adding a compiled op
1. **analyze-form**: add `match head-name` arm returning `{:op :your-op ...}`
2. **emit-ast**: add str function + `:your-op` case in `set emit-ast` dispatch
3. **emit-expr**: add expr function + `:your-op` case in `set emit-expr` dispatch
1. Add match arm in `analyze-form` — maps Clojure form → AST node
2. Add `emit-*-str` for source-to-source path → arm in `emit-ast` dispatch
3. Add `emit-*-expr` for data-structure path → arm in `emit-expr` dispatch
4. Add tests in `test/compiler-test.janet`
### Emit-expr critical rules
@ -128,45 +51,41 @@ The match arm receives `ctx`, `bindings`, and `form` (the full list). Use `(in f
### Macro expansion
`analyze-form` checks `resolve-macro` first — if head is a macro var, applies fn, re-analyzes expanded form (only when ctx passed).
## Persistent Data Structures
### Loop/recur compilation
`(loop* [x 0] body)` → `(do (var name nil) (set name (fn [x] body)) (name 0))`
Recur rewrites to `(loop-name arg...)` via `:jolt/current-loop` binding.
### PersistentVector
Located in `src/jolt/clojure/lang/persistent_vector.clj`.
Loaded at init time by `load-persistent-structures` in `api.janet`.
32-way branching trie with tail optimization.
## Special Form Checklist
### PersistentHashMap
Located in `src/jolt/phm.janet` — Janet module, NOT a .clj file.
Imported via `(use ./phm)` in `src/jolt/core.janet`.
Bucket-based (8 buckets), each bucket is a flat `[k v k v ...]` array.
PHM is a table with magic type tag: `:jolt/deftype` = `"jolt.lang.persistent-hash-map.PersistentHashMap"`.
Key fields: `:cnt` (entry count), `:buckets` (array of arrays), `:_meta`.
To add a new special form to the evaluator AND compiler:
1. Add the name to `special-symbol?` in `src/jolt/evaluator.janet`
2. Add a match arm in `eval-list` (the match on `name`)
3. Add tests in `test/evaluator-test.janet`
API: `phm-get`, `phm-assoc`, `phm-dissoc`, `phm-contains?`, `phm-entries`, `phm-to-struct`.
`phm-to-struct` converts PHM back to Janet struct for compatibility with `keys`, `deep=`, etc.
The match arm receives `ctx`, `bindings`, and `form`. Use `(in form 1)` for first arg.
**Design decision**: PHM lives in a separate Janet module rather than embedded in core.janet, to avoid forward-reference issues (core-map? calls phm? which wasn't yet defined when core-map? was being compiled).
### Current special forms (29):
`quote`, `syntax-quote`, `unquote`, `unquote-splicing`, `do`, `if`, `def`, `defmacro`, `fn*`, `let*`, `loop*`, `recur`, `throw`, `try`, `set!`, `var`, `locking`, `instance?`, `defmulti`, `defmethod`, `deftype`, `new`, `.`, `var-get`, `var-set`, `var?`, `alter-var-root`, `find-var`, `alter-meta!`, `reset-meta!`, `intern`
**16 core functions updated** with PHM-aware branches: core-map?, core-hash-map, core-get, core-count, core-keys, core-vals, core-contains?, core-empty?, core-seq, core-conj, core-assoc, core-dissoc, core-merge, core-merge-with, core-into, core-=.
## PersistentHashMap (phm.janet)
### Working with PHM in core functions
- Check `(phm? coll)` FIRST, before generic struct/table checks
- Use `phm-get` not `(m key)` — PHM is a table but keys aren't direct properties
- Use `phm-to-struct` when you need Janet-native operations (deep=, keys, etc.)
- PHM equality: `core-=` converts both sides to structs via `phm-to-struct`, then uses `deep=`
`src/jolt/phm.janet` — separate module imported via `(use ./phm)` into `core.janet`.
PHM is a table with `:jolt/deftype` tag. Has `:cnt`, `:buckets` (array of 8 flat `[k v k v ...]` arrays), `:_meta`.
16 core functions updated with `(phm? x)` branches. `phm-to-struct` converts to Janet struct for compatibility.
### Loading persistent structures
Use `{:mutable? true}` in `init` to skip persistent types and use Janet-native structs.
### Janet `break` limitation
Janet `break` cannot be used inside `let` blocks — use `(var found nil)` + `(while ... (if condition (do (set found val) (break))))` pattern.
## Janet Gotchas
### core-binding: use array-map, not hash-map
`core-binding` macro must emit `(array-map ...)` for the binding frame — PHM's get is incompatible with `push-thread-bindings` var-get lookup.
- Bit operations (brshift, brushift, band) use 32-bit signed integers. Hash values can exceed 32-bit range. Use `(band x 0xFFFFFFFF)` before shifting.
- `deftype` creates tables, not structs. `struct?` returns false.
- `(get child :key)` DOES follow table prototype chain — resolved and confirmed working.
- Janet LSP produces many false positives on `.janet` files — safe to ignore.
- `break` can't be used inside `let` blocks — `break` returns from the innermost loop, and a `let` has no loop. Use `(var found nil)` pattern + `(while ... (if cond (do (set found val) (break))))` then check `found` after loop.
- Duplicate function definitions in the same file cause hard-to-diagnose "unknown symbol" errors. Always grep for the fn name before adding.
### core-intern gotcha
Janet does not support Clojure-style multi-arity destructuring `([a b] ...)` in `defn`. Use flat args or wrapper functions.
## Symbol representation
Jolt symbols are `{:jolt/type :symbol :ns <string-or-nil> :name <string>}` as produced by the reader.
Jolt symbols are `{:jolt/type :symbol :ns <string-or-nil> :name <string>}` as produced by the reader.
## Janet LSP
Janet LSP produces many false positives on `.janet` files — safe to ignore.