docs: update README for Option A laziness + vendored test suite
- map/filter/etc. return lazy seqs now: the library example shows (2 3 4), and the "Eager seqs" clojure-test-suite failing-reason bullet is removed (seq?/ vector?/sequential? of their results now match Clojure). - conformance 218/218 (two modes) -> 258/258 across all three execution paths (interpreter, compiler, self-hosted compiler). - clojure-test-suite is a vendored git submodule (vendor/clojure-test-suite), not a ~/src checkout; submodule-update comment and suite count (~3980) updated. - noted that lazy transformers over a non-seqable throw when realized. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
parent
597f76a753
commit
e9f7e29da2
1 changed files with 21 additions and 18 deletions
39
README.md
39
README.md
|
|
@ -9,7 +9,7 @@ A Clojure implementation on [Janet](https://janet-lang.org). Jolt reads Clojure
|
||||||
```bash
|
```bash
|
||||||
git clone https://github.com/jolt-lang/jolt.git
|
git clone https://github.com/jolt-lang/jolt.git
|
||||||
cd jolt
|
cd jolt
|
||||||
git submodule update --init # pulls vendor/sci
|
git submodule update --init # pulls vendor/sci and vendor/clojure-test-suite
|
||||||
jpm build # builds build/jolt and build/jolt-deps
|
jpm build # builds build/jolt and build/jolt-deps
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -54,7 +54,7 @@ hello 42
|
||||||
|
|
||||||
(def ctx (init))
|
(def ctx (init))
|
||||||
(eval-string ctx "(+ 1 2)") # → 3
|
(eval-string ctx "(+ 1 2)") # → 3
|
||||||
(eval-string ctx "(map inc [1 2 3])") # → [2 3 4]
|
(eval-string ctx "(map inc [1 2 3])") # → (2 3 4) ; a lazy seq, like Clojure
|
||||||
```
|
```
|
||||||
|
|
||||||
`(init)` returns a context with `clojure.core` loaded. Each context is isolated; use separate contexts for separate environments.
|
`(init)` returns a context with `clojure.core` loaded. Each context is isolated; use separate contexts for separate environments.
|
||||||
|
|
@ -94,10 +94,11 @@ calls compile to direct Janet calls.
|
||||||
For compute-heavy code the compiled path is dramatically faster than tree-walking,
|
For compute-heavy code the compiled path is dramatically faster than tree-walking,
|
||||||
at native Janet speed.
|
at native Janet speed.
|
||||||
|
|
||||||
**Validated at parity.** The conformance suite passes 218/218 under *both*
|
**Validated at parity.** The conformance suite passes 258/258 under *all three*
|
||||||
interpreter and compiler (`conformance-test.janet` runs both in CI), and the full
|
execution paths — interpreter, compiler, and the self-hosted compiler
|
||||||
clojure-test-suite under compilation matches the interpreter baseline across
|
(`conformance-test.janet` runs all three in CI) — and the full clojure-test-suite
|
||||||
~4.6k assertions — evidence the hybrid path doesn't diverge.
|
matches its baseline across ~4.6k assertions — evidence the hybrid path doesn't
|
||||||
|
diverge.
|
||||||
|
|
||||||
**AOT.** `aot.janet` marshals a compiled namespace to a Janet bytecode image
|
**AOT.** `aot.janet` marshals a compiled namespace to a Janet bytecode image
|
||||||
(`save-ns`) and loads it back into a fresh context (`load-ns-image`), skipping
|
(`save-ns`) and loads it back into a fresh context (`load-ns-image`), skipping
|
||||||
|
|
@ -211,11 +212,12 @@ Tests are organized in three layers:
|
||||||
per public API area) that collectively pin down Jolt's defined behavior. This
|
per public API area) that collectively pin down Jolt's defined behavior. This
|
||||||
is the authoritative description of what Jolt promises.
|
is the authoritative description of what Jolt promises.
|
||||||
- **`test/integration/`** — cross-cutting and regression batteries: the Clojure
|
- **`test/integration/`** — cross-cutting and regression batteries: the Clojure
|
||||||
conformance suite, SCI bootstrap/runtime loading, jank conformance, the
|
conformance suite (run in all three execution modes), SCI bootstrap/runtime
|
||||||
cross-dialect [clojure-test-suite](https://github.com/jank-lang/clojure-test-suite)
|
loading, jank conformance, the cross-dialect
|
||||||
(run via a minimal `clojure.test` shim against `~/src/clojure-test-suite`, if
|
[clojure-test-suite](https://github.com/jank-lang/clojure-test-suite) (a git
|
||||||
present, and baseline-guarded), compile-mode tests, the library API, and a
|
submodule at `vendor/clojure-test-suite`, run via a minimal `clojure.test` shim
|
||||||
broad systematic-coverage net.
|
and baseline-guarded), compile-mode tests, the library API, and a broad
|
||||||
|
systematic-coverage net.
|
||||||
- **`test/unit/`** — white-box tests for individual components (reader,
|
- **`test/unit/`** — white-box tests for individual components (reader,
|
||||||
evaluator, types, persistent collections, regex, compiler).
|
evaluator, types, persistent collections, regex, compiler).
|
||||||
|
|
||||||
|
|
@ -231,11 +233,14 @@ exercises it.
|
||||||
### clojure-test-suite conformance
|
### clojure-test-suite conformance
|
||||||
|
|
||||||
The [clojure-test-suite](https://github.com/jank-lang/clojure-test-suite) battery
|
The [clojure-test-suite](https://github.com/jank-lang/clojure-test-suite) battery
|
||||||
runs ~3900 assertions green. Jolt validates its arguments like Clojure —
|
(vendored as a git submodule) runs ~3980 assertions green. Jolt validates its
|
||||||
arithmetic on non-numbers, comparisons against `nil`, out-of-range indices,
|
arguments like Clojure — arithmetic on non-numbers, comparisons against `nil`,
|
||||||
malformed `conj!`/`assoc!`/`merge`, and non-seqable `first`/`seq`/`vec` all
|
out-of-range indices, malformed `conj!`/`assoc!`/`merge`, non-seqable
|
||||||
throw. The assertions that remain failing are accounted for by the
|
`first`/`seq`/`vec`, and lazy transformers (`map`/`filter`/…) realized over a
|
||||||
platform/design differences above, not by missing behavior:
|
non-seqable all throw. The lazy seq fns return seqs (not vectors), so
|
||||||
|
`seq?`/`vector?`/`sequential?` of their results match Clojure. The assertions
|
||||||
|
that remain failing are accounted for by the platform/design differences above,
|
||||||
|
not by missing behavior:
|
||||||
|
|
||||||
- **No bignum/ratio/BigDecimal** — `bigint`/`numerator`/`denominator`/`bigdec`,
|
- **No bignum/ratio/BigDecimal** — `bigint`/`numerator`/`denominator`/`bigdec`,
|
||||||
the `big-int?`/auto-promotion checks, and the `2N`/`1/2`/`1.0M` literals read
|
the `big-int?`/auto-promotion checks, and the `2N`/`1/2`/`1.0M` literals read
|
||||||
|
|
@ -245,8 +250,6 @@ platform/design differences above, not by missing behavior:
|
||||||
`float?`/`double?` cases can't distinguish them (`(str 0.0)` is `"0"`).
|
`float?`/`double?` cases can't distinguish them (`(str 0.0)` is `"0"`).
|
||||||
- **64-bit integers / Unicode** — `bit-and` etc. on full-width 64-bit constants
|
- **64-bit integers / Unicode** — `bit-and` etc. on full-width 64-bit constants
|
||||||
lose precision (doubles), and `subs`/`count` work on bytes, not code points.
|
lose precision (doubles), and `subs`/`count` work on bytes, not code points.
|
||||||
- **Eager seqs** — `map`/`filter`/`range` return vectors, so `seq?`/`vector?`/
|
|
||||||
`sequential?` of their results differ, and sorts aren't guaranteed stable.
|
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue