qcoffee --interactive（或 -i）者，逐行共用一 Context；:help 示命，:quit 出之。
qcoffee --interactive --stats 惟非空行之行而行或运行时有误者，书指令与余燃料一条；析验之误不更书。
'a☕中'[1] 即 '☕'，'a☕中'[1..2]' 得 '☕中'；字符串索引循 Unicode 标量。
-for character, index in 'a☕中' then index，得 [0, 1, 2]；字符串循 Unicode 标量，弗受 by。
+for character, index in 'a☕中' then index，得 [0, 1, 2]；字符串循 Unicode 标量，亦受正整数 by。
[head, tail...] = [1, 2, 3]，tail 得 [2, 3]；数组之 rest 必居末。
qtest --fuel N 者，为各可行文别限其指令之数。
qtest --stats 更书各篇所试指令与余燃料于标准错误，而 ok 之出不改。
@@ -29,6 +29,7 @@qdocco --markdown 出说明、围栏 QuickCoffee 代码及终值为可阅 Markdown 文。
嵌者可于两行之间呼 Context::set_fuel；Context::fuel 示每行之限，而全局不失。
cargo run --example embed 可验最小 Rust 宿主，设全局、立原生回调而行 QuickCoffee。
+宿主可用 Value::kind() 别其类，Value::is_nil() 验 nil，不窥其内容器。
Cargo 包志指仓、docs.rs API、README 与许可证，使嵌者易寻其用。
Context::last_execution() 示所试指令与余燃料，而不露 VM 之帧。
-- 后之参，以常字符串数组 argv 见于文中。
diff --git a/docs/manual.classical-zh.md b/docs/manual.classical-zh.md index aaee274..515b591 100644 --- a/docs/manual.classical-zh.md +++ b/docs/manual.classical-zh.md @@ -89,4 +89,4 @@ QuickCoffee 者，Rust 所为字节码机也，非 JavaScript 之运行时。其 一逻辑行中，函调用可略括，如 `implicit_answer = implicit_add 20, 22`；遇比较或布局之界，仍宜明括。 -`qtest --json` 各试篇出定 JSON，`qtest --tap` 出 TAP 13；`qcoffee --fingerprint FILE` 不行其文而出定式字节码键；`qbench --json` 记编、验、行之时，皆有语义护栏；`qdocco --markdown` 出可阅文学编程 Markdown。嵌者可呼 `Context::set_fuel` 改复用境之限，并行 `cargo run --example embed` 观宿主全例。 +`qtest --json` 各试篇出定 JSON，`qtest --tap` 出 TAP 13；`qcoffee --fingerprint FILE` 不行其文而出定式字节码键；`qbench --json` 记编、验、行之时，皆有语义护栏；`qdocco --markdown` 出可阅文学编程 Markdown。嵌者可呼 `Context::set_fuel` 改复用境之限，以 `Value::kind()`、`Value::is_nil()` 别值之类，并行 `cargo run --example embed` 观宿主全例。 diff --git a/docs/manual.devanagari-sa.html b/docs/manual.devanagari-sa.html index 3c15eb1..9d44d84 100644 --- a/docs/manual.devanagari-sa.html +++ b/docs/manual.devanagari-sa.html @@ -10,7 +10,7 @@qcoffee --interactive (वा -i) एकं Context पङ्क्ति-क्रमेण धारयति; :help दर्शयति, :quit निर्गच्छति।
qcoffee --interactive --stats केवलं कार्यितायै वा runtime-दोषयुक्तायै non-empty पङ्क्त्यै instruction तथा fuel लेखं लिखति; parse अथवा verify-दोषे नूतनं लेखं न लिखति।
'a☕中'[1] '☕' अस्ति, 'a☕中'[1..2] '☕中' अस्ति; string-index Unicode-scalar-अनुसारी अस्ति।
-for character, index in 'a☕中' then index Unicode-scalar-अङ्कान् [0, 1, 2] ददाति; string-iteration मध्ये by नास्ति।
+for character, index in 'a☕中' then index Unicode-scalar-अङ्कान् [0, 1, 2] ददाति; string-iteration मध्ये धनात्मक by-क्रमः अस्ति।
[head, tail...] = [1, 2, 3] tail-नाम्नि [2, 3] बध्नाति; array-pattern rest अन्तिमः भवति।
qtest --fuel N प्रत्येक executable-document पृथक् instruction-budget ददाति।
qtest --stats प्रत्येकस्य documentस्य instruction-संख्या तथा अवशिष्ट-fuel standard error मध्ये लिखति, ok-निर्गमं न परिवर्तयति।
@@ -25,6 +25,7 @@qdocco --markdown टिप्पणीन्, सीमितं QuickCoffee-कोडं, अन्तिम-मूल्यं च पठनीय Markdown-फलके लिखति।
अन्तःस्थापकः चालनयोर्मध्ये Context::set_fuel आह्वयितुं शक्नोति; Context::fuel वर्तमान-सीमां दर्शयति, वैश्विक-मूल्यानि न नाशयति।
`cargo run --example embed` लघुं Rust-आश्रयं संयोजयति, वैश्विकं स्थापयति, native-callback योजयति, QuickCoffee च चालयति।
+Host `Value::kind()` द्वारा प्रकारं विभजति, `Value::is_nil()` द्वारा nil परीक्षते, आन्तरिक-container न पश्यति।
Cargo-वस्तु-विवरणानि अन्तःस्थापकान् repository, docs.rs-API, README, licence च प्रति नयन्ति।
Context::last_execution() instruction-संख्या तथा अवशिष्ट-fuel दर्शयति, VM-frame न प्रकाशयति।
-- पश्चात् argumentाः साधारण-string-array argv रूपेण दीयन्ते।
diff --git a/docs/manual.devanagari.sa.md b/docs/manual.devanagari.sa.md index 907e3ae..59a564e 100644 --- a/docs/manual.devanagari.sa.md +++ b/docs/manual.devanagari.sa.md @@ -93,4 +93,4 @@ host-त्रुटिः संरचिता: `error.kind()` `ErrorKind::Par एकस्यां logical-line मध्ये call-parenthesis विना अपि शक्यते: `implicit_answer = implicit_add 20, 22`; comparison अथवा layout-boundary मध्ये explicit parenthesis प्रयोजनीया। -`qtest --json` प्रत्येक-परीक्षा-पत्राय स्थिरं JSON लिखति, `qtest --tap` TAP 13 ददाति; `qcoffee --fingerprint FILE` लेखं न चालयित्वा नियत-bytecode-कुञ्जीं दर्शयति; `qbench --json` semantic-रक्षणेन compile, verify, execute कालं मापयति; `qdocco --markdown` समीक्षायै literate Markdown जनयति। अन्तःस्थापकः Context::set_fuel द्वारा पुनःप्रयुक्त-सन्दर्भस्य सीमा परिवर्तयितुं शक्नोति, तथा `cargo run --example embed` पूर्णं host-उदाहरणं चालयति। +`qtest --json` प्रत्येक-परीक्षा-पत्राय स्थिरं JSON लिखति, `qtest --tap` TAP 13 ददाति; `qcoffee --fingerprint FILE` लेखं न चालयित्वा नियत-bytecode-कुञ्जीं दर्शयति; `qbench --json` semantic-रक्षणेन compile, verify, execute कालं मापयति; `qdocco --markdown` समीक्षायै literate Markdown जनयति। अन्तःस्थापकः `Context::set_fuel` द्वारा पुनःप्रयुक्त-सन्दर्भस्य सीमा परिवर्तयितुं शक्नोति, `Value::kind()` तथा `Value::is_nil()` द्वारा प्रकारं परीक्षते, तथा `cargo run --example embed` पूर्णं host-उदाहरणं चालयति। diff --git a/docs/manual.en.html b/docs/manual.en.html index 35d9a6b..1721fb7 100644 --- a/docs/manual.en.html +++ b/docs/manual.en.html @@ -6,7 +6,7 @@qcoffee --check FILE parses, compiles, and verifies without executing FILE.
qcoffee --interactive (or -i) keeps one Context for a line-oriented session; :help and :quit are built-in commands.
qcoffee --interactive --stats writes one instruction/fuel record for each non-empty line that executes or reaches a runtime error; parse and verify errors write none.
-for character, index in 'a☕中' then index yields [0, 1, 2]; strings iterate Unicode scalars and reject by.
+for character, index in 'a☕中' then index yields [0, 1, 2]; strings iterate Unicode scalars and accept positive by steps.
[head, tail...] = [1, 2, 3] binds tail to [2, 3]; array-pattern rest must be final.
qtest --fuel N gives each executable documentation file its own instruction budget.
qtest --stats writes each file's instruction count and remaining fuel to stderr without changing its ok output.
@@ -21,6 +21,7 @@qdocco --markdown writes Notes, fenced QuickCoffee code, and the final value as a reviewable Markdown artifact.
Embedders may call Context::set_fuel between runs; Context::fuel reports the current per-run budget without clearing globals.
cargo run --example embed compiles a minimal Rust host that sets a global, registers a native callback, and evaluates QuickCoffee.
+A host can branch on Value::kind() and use Value::is_nil() without inspecting internal containers.
Cargo package metadata points embedding users to the repository, docs.rs API, README, and license.
Context::last_execution() exposes instruction and remaining-fuel counters without VM frames.
Arguments after -- are exposed as the ordinary string array argv.
diff --git a/docs/manual.en.md b/docs/manual.en.md index d3fd164..2d72394 100644 --- a/docs/manual.en.md +++ b/docs/manual.en.md @@ -84,7 +84,7 @@ Use `switch value` with indented `when pattern` branches for strict-equality sel Exceptions use `try`, `catch error`, optional `finally`, and `throw value`. A catch receives a stable error string rather than a JavaScript Error object; function returns also run applicable finalizers. -For Rust embedding, create `Context`, optionally call `with_fuel`, register a host callback with `add_native`, then call `eval`; callbacks can return `Error::runtime("message")` and the script may catch it. For repeated execution, compile once with `Engine::compile_program` (which verifies once) and pass the shared `Program` to `run_program`; cloning that handle does not copy bytecode or repeat verification. `Value::from`, `Value::string`, `Value::array`, and `Value::map` construct host values without exposing VM reference-counting internals. +For Rust embedding, create `Context`, optionally call `with_fuel`, register a host callback with `add_native`, then call `eval`; callbacks can return `Error::runtime("message")` and the script may catch it. For repeated execution, compile once with `Engine::compile_program` (which verifies once) and pass the shared `Program` to `run_program`; cloning that handle does not copy bytecode or repeat verification. `Value::from`, `Value::string`, `Value::array`, and `Value::map` construct host values without exposing VM reference-counting internals; `Value::kind()` and `Value::is_nil()` provide stable type checks. `Context::last_execution()` returns public `ExecutionStats` (`instructions` and `fuel_remaining`) for the latest successful or runtime-failed execution; compile and verification errors leave the previous record unchanged. diff --git a/docs/manual.latin.html b/docs/manual.latin.html index 8390191..c39b2c1 100644 --- a/docs/manual.latin.html +++ b/docs/manual.latin.html @@ -10,7 +10,7 @@qcoffee --interactive (vel -i) unum Context per lineas servat; :help docet, :quit exit.
qcoffee --interactive --stats unam instructionum et alimenti reliqui notam lineae non vacuae exsecutæ vel errorem currendi ferenti scribit; errores analysi vel verificationis nihil scribunt.
'a☕中'[1] est '☕', et 'a☕中'[1..2] est '☕中'; indices stringarum scalas Unicode sequuntur.
-for character, index in 'a☕中' then index indices Unicode scalarum [0, 1, 2] reddit; iteratio stringarum by non accipit.
+for character, index in 'a☕中' then index indices Unicode scalarum [0, 1, 2] reddit; iteratio stringarum gradus positivos by accipit.
[head, tail...] = [1, 2, 3] tail ad [2, 3] ligat; rest in forma array postremum esse debet.
qtest --fuel N cuique documento exsecutabili budget instructionum proprium dat.
qtest --stats numeros instructionum et alimenti reliqui cuiusque documenti ad errorem ordinarium scribit, sine mutatione exitus ok.
@@ -25,6 +25,7 @@qdocco --markdown notas, codicem QuickCoffee clausum, et valorem ultimum in documento Markdown scribit.
Hospes inter cursus `Context::set_fuel` vocare potest; `Context::fuel` budgetum ostendit sine globalibus deletis.
`cargo run --example embed` hospitem Rust minimum compilat: globale ponit, callback nativum addit, et QuickCoffee currit.
+Hospes `Value::kind()` ad genus discernendum et `Value::is_nil()` ad nil probandum utitur, sine interioribus vasorum.
Notitiae Cargoe hospites ad repositorium, API docs.rs, README et licentiam ducunt.
Context::last_execution() numeros instructionum et alimenti reliqui ostendit, sine tabulis VM.
Argumenta post -- ut series chordarum ordinaria argv praebentur.
diff --git a/docs/manual.latin.md b/docs/manual.latin.md index 87ad54e..d07bc4c 100644 --- a/docs/manual.latin.md +++ b/docs/manual.latin.md @@ -91,4 +91,4 @@ Post assignationem solam (`record =`) mapa per indentationem scribi potest; clav In una linea logica, functio sine parenthesibus vocari potest: `implicit_answer = implicit_add 20, 22`; apud comparationes vel limites ordinis parenthesibus uti licet. -`qtest --json` unam rem stabilem pro quoque testium documento scribit, `qtest --tap` TAP 13 reddit; `qcoffee --fingerprint FILE` clavem bytecodicis canonice verificati sine exsecutione ostendit; `qbench --json` tempora compilationis, verificationis et cursus cum custodia semantica metitur; `qdocco --markdown` documentum literarium ad recensionem scribit. Hospes `Context::set_fuel` inter cursus mutare potest et `cargo run --example embed` exemplum integrum currere. +`qtest --json` unam rem stabilem pro quoque testium documento scribit, `qtest --tap` TAP 13 reddit; `qcoffee --fingerprint FILE` clavem bytecodicis canonice verificati sine exsecutione ostendit; `qbench --json` tempora compilationis, verificationis et cursus cum custodia semantica metitur; `qdocco --markdown` documentum literarium ad recensionem scribit. Hospes `Context::set_fuel` inter cursus mutare potest, `Value::kind()` et `Value::is_nil()` ad genus probandum adhibet, et `cargo run --example embed` exemplum integrum currere. diff --git a/docs/manual.zh-CN.html b/docs/manual.zh-CN.html index 9a41176..6854d57 100644 --- a/docs/manual.zh-CN.html +++ b/docs/manual.zh-CN.html @@ -7,7 +7,7 @@qcoffee --interactive（或 -i）逐行复用同一 Context；:help 显示命令，:quit 退出。
qcoffee --interactive --stats 仅为实际执行或运行时失败的非空输入行输出指令/燃料统计；解析、验证错误不输出新记录。
'a☕中'[1] 为 '☕'，'a☕中'[1..2] 为 '☕中'；字符串索引按 Unicode 标量。
-for character, index in 'a☕中' then index 得 [0, 1, 2]；字符串按 Unicode 标量遍历，不可用 by。
+for character, index in 'a☕中' then index 得 [0, 1, 2]；字符串按 Unicode 标量遍历，亦可用正整数 by。
[head, tail...] = [1, 2, 3] 将 tail 绑定为 [2, 3]；数组模式 rest 必须居末。
qtest --fuel N 为每份可执行文档设置独立指令预算。
qtest --stats 将每份文档的指令数与剩余燃料写入标准错误，不改变 ok 输出。
@@ -22,6 +22,7 @@qdocco --markdown 将说明、围栏 QuickCoffee 代码与最终值写成可审阅的 Markdown 产物。
嵌入方可在运行之间调用 Context::set_fuel；Context::fuel 返回当前每轮预算，且不清除全局值。
cargo run --example embed 可编译最小 Rust 宿主：设置全局、注册原生回调并执行 QuickCoffee。
+宿主可用 Value::kind() 分流类型，用 Value::is_nil() 判断 nil，无须检查内部容器。
Cargo 包元数据指向仓库、docs.rs API、README 与许可证，便于嵌入方发现项目。
Context::last_execution() 提供指令数与剩余燃料统计，不暴露 VM 帧。
-- 后的参数以普通字符串数组 argv 暴露给程序。
diff --git a/docs/manual.zh-CN.md b/docs/manual.zh-CN.md index e024aa5..e4db0bb 100644 --- a/docs/manual.zh-CN.md +++ b/docs/manual.zh-CN.md @@ -137,4 +137,4 @@ let value = cx.eval("host_values[0] + host_values[1]")?; 同一逻辑行的调用可省略括号：`implicit_answer = implicit_add 20, 22`；比较或跨布局边界时仍可使用显式括号。 -`qtest --json` 为每个测试文件输出稳定 JSON，`qtest --tap` 输出 TAP 13；`qcoffee --fingerprint FILE` 在不执行文件时输出规范化字节码缓存键；`qbench --json` 输出带语义护栏的编译、验证、执行计时；`qdocco --markdown` 生成可审阅的文学编程 Markdown。嵌入方可用 `Context::set_fuel` 调整复用上下文，并运行 `cargo run --example embed` 查看完整宿主示例。 +`qtest --json` 为每个测试文件输出稳定 JSON，`qtest --tap` 输出 TAP 13；`qcoffee --fingerprint FILE` 在不执行文件时输出规范化字节码缓存键；`qbench --json` 输出带语义护栏的编译、验证、执行计时；`qdocco --markdown` 生成可审阅的文学编程 Markdown。嵌入方可用 `Context::set_fuel` 调整复用上下文，用 `Value::kind()` 与 `Value::is_nil()` 做稳定类型判断，并运行 `cargo run --example embed` 查看完整宿主示例。 diff --git a/docs/syntax.en.md b/docs/syntax.en.md index 2864ab9..b544ab2 100644 --- a/docs/syntax.en.md +++ b/docs/syntax.en.md @@ -26,7 +26,9 @@ Array comprehensions may bind an optional zero-based index: `for value, index in Comprehensions may also use CoffeeScript's postfix form: `value * 2 for value in items`, optionally wrapped as `[value * 2 for value in items]`. The postfix form has the same `by`, `when`, map, pattern, `break`, and `continue` semantics as the prefix form; the brackets are a comprehension delimiter and do not add a nested array. -String indexing and strict slices use Unicode scalar boundaries: `'a☕中'[1]` is `'☕'`, and `'a☕中'[1..2]` is `'☕中'`. String `by` iteration remains unsupported. +String indexing and strict slices use Unicode scalar boundaries: `'a☕中'[1]` is `'☕'`, and `'a☕中'[1..2]` is `'☕中'`. String `for` iteration also accepts a positive finite `by` step over Unicode scalar positions: `for character, index in 'a☕中x' by 2 then index` yields `[0, 2]`. + +Array and string `by step` expressions are evaluated once and must be positive finite integers; map iteration excludes `by`. Names support arithmetic compound assignment (`+=`, `-=`, `*=`, `/=`, `%=` and `**=`). Compound assignment is intentionally name-only; members, indexes, and destructuring remain immutable API boundaries. diff --git a/docs/syntax.zh-CN.md b/docs/syntax.zh-CN.md index 8d19062..fb92f90 100644 --- a/docs/syntax.zh-CN.md +++ b/docs/syntax.zh-CN.md @@ -16,7 +16,7 @@ 整数区间支持升序与降序：`[2..4]` 为 `[2, 3, 4]`，`[4..2]` 为 `[4, 3, 2]`；排除上界形式相应省略终点（`[4...2]` 为 `[4, 3]`）。边界必须是有限整数，过长区间仍报错。 -字符串索引与严格切片按 Unicode 标量边界：`'a☕中'[1]` 为 `'☕'`，`'a☕中'[1..2]` 为 `'☕中'`；负索引从末项计数（`items[-1]`），越界仍报错；字符串 `for` 仍不支持 `by`。 +字符串索引与严格切片按 Unicode 标量边界：`'a☕中'[1]` 为 `'☕'`，`'a☕中'[1..2]` 为 `'☕中'`；负索引从末项计数（`items[-1]`），越界仍报错；字符串 `for` 亦支持按 Unicode 标量下标以正有限整数 `by` 步进，例如 `for character, index in 'a☕中x' by 2 then index` 得 `[0, 2]`。 映射字面量可从左至右展开：`{...defaults, theme: 'dark'}`；后写显式键或展开段覆盖先写键，展开值必须为映射。映射解构可用末尾尾部模式 `{id, ...metadata}` 捕获未列键，所得映射为新的不可变值。 diff --git a/manuals/manual.classical-zh.qc b/manuals/manual.classical-zh.qc index 726e334..ebacb5f 100644 --- a/manuals/manual.classical-zh.qc +++ b/manuals/manual.classical-zh.qc @@ -14,7 +14,7 @@ ## qcoffee --interactive（或 -i）者，逐行共用一 Context；:help 示命，:quit 出之。 ## qcoffee --interactive --stats 惟非空行之行而行或运行时有误者，书指令与余燃料一条；析验之误不更书。 ## 'a☕中'[1] 即 '☕'，'a☕中'[1..2]' 得 '☕中'；字符串索引循 Unicode 标量。 -## for character, index in 'a☕中' then index，得 [0, 1, 2]；字符串循 Unicode 标量，弗受 by。 +## for character, index in 'a☕中' then index，得 [0, 1, 2]；字符串循 Unicode 标量，亦受正整数 by。 ## [head, tail...] = [1, 2, 3]，tail 得 [2, 3]；数组之 rest 必居末。 ## qtest --fuel N 者，为各可行文别限其指令之数。 ## qtest --stats 更书各篇所试指令与余燃料于标准错误，而 ok 之出不改。 @@ -29,6 +29,7 @@ ## qdocco --markdown 出说明、围栏 QuickCoffee 代码及终值为可阅 Markdown 文。 ## 嵌者可于两行之间呼 Context::set_fuel；Context::fuel 示每行之限，而全局不失。 ## cargo run --example embed 可验最小 Rust 宿主，设全局、立原生回调而行 QuickCoffee。 +## 宿主可用 Value::kind() 别其类，Value::is_nil() 验 nil，不窥其内容器。 ## Cargo 包志指仓、docs.rs API、README 与许可证，使嵌者易寻其用。 ## Context::last_execution() 示所试指令与余燃料，而不露 VM 之帧。 ## -- 后之参，以常字符串数组 argv 见于文中。 diff --git a/manuals/manual.devanagari-sa.qc b/manuals/manual.devanagari-sa.qc index e358032..7697478 100644 --- a/manuals/manual.devanagari-sa.qc +++ b/manuals/manual.devanagari-sa.qc @@ -10,7 +10,7 @@ ## qcoffee --interactive (वा -i) एकं Context पङ्क्ति-क्रमेण धारयति; :help दर्शयति, :quit निर्गच्छति। ## qcoffee --interactive --stats केवलं कार्यितायै वा runtime-दोषयुक्तायै non-empty पङ्क्त्यै instruction तथा fuel लेखं लिखति; parse अथवा verify-दोषे नूतनं लेखं न लिखति। ## 'a☕中'[1] '☕' अस्ति, 'a☕中'[1..2] '☕中' अस्ति; string-index Unicode-scalar-अनुसारी अस्ति। -## for character, index in 'a☕中' then index Unicode-scalar-अङ्कान् [0, 1, 2] ददाति; string-iteration मध्ये by नास्ति। +## for character, index in 'a☕中' then index Unicode-scalar-अङ्कान् [0, 1, 2] ददाति; string-iteration मध्ये धनात्मक by-क्रमः अस्ति। ## [head, tail...] = [1, 2, 3] tail-नाम्नि [2, 3] बध्नाति; array-pattern rest अन्तिमः भवति। ## qtest --fuel N प्रत्येक executable-document पृथक् instruction-budget ददाति। ## qtest --stats प्रत्येकस्य documentस्य instruction-संख्या तथा अवशिष्ट-fuel standard error मध्ये लिखति, ok-निर्गमं न परिवर्तयति। @@ -25,6 +25,7 @@ ## qdocco --markdown टिप्पणीन्, सीमितं QuickCoffee-कोडं, अन्तिम-मूल्यं च पठनीय Markdown-फलके लिखति। ## अन्तःस्थापकः चालनयोर्मध्ये Context::set_fuel आह्वयितुं शक्नोति; Context::fuel वर्तमान-सीमां दर्शयति, वैश्विक-मूल्यानि न नाशयति। ## `cargo run --example embed` लघुं Rust-आश्रयं संयोजयति, वैश्विकं स्थापयति, native-callback योजयति, QuickCoffee च चालयति। +## Host `Value::kind()` द्वारा प्रकारं विभजति, `Value::is_nil()` द्वारा nil परीक्षते, आन्तरिक-container न पश्यति। ## Cargo-वस्तु-विवरणानि अन्तःस्थापकान् repository, docs.rs-API, README, licence च प्रति नयन्ति। ## Context::last_execution() instruction-संख्या तथा अवशिष्ट-fuel दर्शयति, VM-frame न प्रकाशयति। ## -- पश्चात् argumentाः साधारण-string-array argv रूपेण दीयन्ते। diff --git a/manuals/manual.en.qc b/manuals/manual.en.qc index 865c3ee..463dc4a 100644 --- a/manuals/manual.en.qc +++ b/manuals/manual.en.qc @@ -6,7 +6,7 @@ ## qcoffee --check FILE parses, compiles, and verifies without executing FILE. ## qcoffee --interactive (or -i) keeps one Context for a line-oriented session; :help and :quit are built-in commands. ## qcoffee --interactive --stats writes one instruction/fuel record for each non-empty line that executes or reaches a runtime error; parse and verify errors write none. -## for character, index in 'a☕中' then index yields [0, 1, 2]; strings iterate Unicode scalars and reject by. +## for character, index in 'a☕中' then index yields [0, 1, 2]; strings iterate Unicode scalars and accept positive by steps. ## [head, tail...] = [1, 2, 3] binds tail to [2, 3]; array-pattern rest must be final. ## qtest --fuel N gives each executable documentation file its own instruction budget. ## qtest --stats writes each file's instruction count and remaining fuel to stderr without changing its ok output. @@ -21,6 +21,7 @@ ## qdocco --markdown writes Notes, fenced QuickCoffee code, and the final value as a reviewable Markdown artifact. ## Embedders may call Context::set_fuel between runs; Context::fuel reports the current per-run budget without clearing globals. ## cargo run --example embed compiles a minimal Rust host that sets a global, registers a native callback, and evaluates QuickCoffee. +## A host can branch on Value::kind() and use Value::is_nil() without inspecting internal containers. ## Cargo package metadata points embedding users to the repository, docs.rs API, README, and license. ## Context::last_execution() exposes instruction and remaining-fuel counters without VM frames. ## Arguments after -- are exposed as the ordinary string array argv. diff --git a/manuals/manual.latin.qc b/manuals/manual.latin.qc index eab0ec1..3a7cd12 100644 --- a/manuals/manual.latin.qc +++ b/manuals/manual.latin.qc @@ -10,7 +10,7 @@ ## qcoffee --interactive (vel -i) unum Context per lineas servat; :help docet, :quit exit. ## qcoffee --interactive --stats unam instructionum et alimenti reliqui notam lineae non vacuae exsecutæ vel errorem currendi ferenti scribit; errores analysi vel verificationis nihil scribunt. ## 'a☕中'[1] est '☕', et 'a☕中'[1..2] est '☕中'; indices stringarum scalas Unicode sequuntur. -## for character, index in 'a☕中' then index indices Unicode scalarum [0, 1, 2] reddit; iteratio stringarum by non accipit. +## for character, index in 'a☕中' then index indices Unicode scalarum [0, 1, 2] reddit; iteratio stringarum gradus positivos by accipit. ## [head, tail...] = [1, 2, 3] tail ad [2, 3] ligat; rest in forma array postremum esse debet. ## qtest --fuel N cuique documento exsecutabili budget instructionum proprium dat. ## qtest --stats numeros instructionum et alimenti reliqui cuiusque documenti ad errorem ordinarium scribit, sine mutatione exitus ok. @@ -25,6 +25,7 @@ ## qdocco --markdown notas, codicem QuickCoffee clausum, et valorem ultimum in documento Markdown scribit. ## Hospes inter cursus `Context::set_fuel` vocare potest; `Context::fuel` budgetum ostendit sine globalibus deletis. ## `cargo run --example embed` hospitem Rust minimum compilat: globale ponit, callback nativum addit, et QuickCoffee currit. +## Hospes `Value::kind()` ad genus discernendum et `Value::is_nil()` ad nil probandum utitur, sine interioribus vasorum. ## Notitiae Cargoe hospites ad repositorium, API docs.rs, README et licentiam ducunt. ## Context::last_execution() numeros instructionum et alimenti reliqui ostendit, sine tabulis VM. ## Argumenta post -- ut series chordarum ordinaria argv praebentur. diff --git a/manuals/manual.zh-CN.qc b/manuals/manual.zh-CN.qc index 207f647..2b79c14 100644 --- a/manuals/manual.zh-CN.qc +++ b/manuals/manual.zh-CN.qc @@ -7,7 +7,7 @@ ## qcoffee --interactive（或 -i）逐行复用同一 Context；:help 显示命令，:quit 退出。 ## qcoffee --interactive --stats 仅为实际执行或运行时失败的非空输入行输出指令/燃料统计；解析、验证错误不输出新记录。 ## 'a☕中'[1] 为 '☕'，'a☕中'[1..2] 为 '☕中'；字符串索引按 Unicode 标量。 -## for character, index in 'a☕中' then index 得 [0, 1, 2]；字符串按 Unicode 标量遍历，不可用 by。 +## for character, index in 'a☕中' then index 得 [0, 1, 2]；字符串按 Unicode 标量遍历，亦可用正整数 by。 ## [head, tail...] = [1, 2, 3] 将 tail 绑定为 [2, 3]；数组模式 rest 必须居末。 ## qtest --fuel N 为每份可执行文档设置独立指令预算。 ## qtest --stats 将每份文档的指令数与剩余燃料写入标准错误，不改变 ok 输出。 @@ -22,6 +22,7 @@ ## qdocco --markdown 将说明、围栏 QuickCoffee 代码与最终值写成可审阅的 Markdown 产物。 ## 嵌入方可在运行之间调用 Context::set_fuel；Context::fuel 返回当前每轮预算，且不清除全局值。 ## cargo run --example embed 可编译最小 Rust 宿主：设置全局、注册原生回调并执行 QuickCoffee。 +## 宿主可用 Value::kind() 分流类型，用 Value::is_nil() 判断 nil，无须检查内部容器。 ## Cargo 包元数据指向仓库、docs.rs API、README 与许可证，便于嵌入方发现项目。 ## Context::last_execution() 提供指令数与剩余燃料统计，不暴露 VM 帧。 ## -- 后的参数以普通字符串数组 argv 暴露给程序。 diff --git a/src/bin/qbench.rs b/src/bin/qbench.rs index 23e8975..69d4ace 100644 --- a/src/bin/qbench.rs +++ b/src/bin/qbench.rs @@ -1,3 +1,5 @@ +//! Release benchmark runner with semantic guards and machine-readable timing output. + use quickcoffee::{Context, Engine}; use std::{env, process::ExitCode, time::Instant}; @@ -28,6 +30,11 @@ const WORKLOADS: &[Workload] = &[ source: "text = 'a☕中'\nitems = [10, 20, 30]\nitems[-1] + len(text[-2])", expected: "31", }, + Workload { + name: "stepped-string-iteration", + source: "sum = 0\nfor character, index in 'a☕中x' by 2 then sum += index\nsum", + expected: "2", + }, ]; fn usage() { diff --git a/src/bin/qdocco.rs b/src/bin/qdocco.rs index c5e9a9b..9e58f10 100644 --- a/src/bin/qdocco.rs +++ b/src/bin/qdocco.rs @@ -1,4 +1,6 @@ -use quickcoffee::{Context, Engine}; +//! Literate-programming renderer and checker for QuickCoffee sources. + +use quickcoffee::{Context, Engine, Value}; use std::{env, fs, path::PathBuf, process::ExitCode}; fn usage() { @@ -104,6 +106,10 @@ fn main() -> ExitCode { return ExitCode::from(1); } }; + if check && !matches!(&result, Value::Bool(true)) { + eprintln!("qdocco check failed: final value was {result}, expected true"); + return ExitCode::from(1); + } if !check { let destination = output.unwrap_or_else(|| input.with_extension(if markdown { "md" } else { "html" })); diff --git a/src/bin/qtest.rs b/src/bin/qtest.rs index 307e2e1..2fcd7e0 100644 --- a/src/bin/qtest.rs +++ b/src/bin/qtest.rs @@ -1,3 +1,5 @@ +//! Test runner for executable QuickCoffee scripts and literate manuals. + use quickcoffee::{Context, Value}; use std::{ env, fs, diff --git a/src/bytecode.rs b/src/bytecode.rs index 373b76a..c76d837 100644 --- a/src/bytecode.rs +++ b/src/bytecode.rs @@ -8,6 +8,7 @@ use std::{ }; /// A strict, recursively shaped binding pattern used by destructuring assignment. +#[allow(missing_docs)] #[derive(Clone, Debug)] pub enum Pattern { Ignore, @@ -25,11 +26,16 @@ pub enum Pattern { }, } +/// Verified bytecode consisting of a constant pool and instruction stream. #[derive(Clone, Debug, Default)] pub struct Chunk { + /// Values and nested functions referenced by instructions. pub constants: Vec3"));
+ let non_test_document = Command::new(bin("qdocco"))
+ .args(["--check", input.to_str().unwrap()])
+ .output()
+ .unwrap();
+ assert_eq!(non_test_document.status.code(), Some(1));
+ assert!(String::from_utf8_lossy(&non_test_document.stderr).contains("expected true"));
+ let check_input = temp.join("check.qc");
+ fs::write(&check_input, "true\n").unwrap();
assert!(
Command::new(bin("qdocco"))
- .args(["--check", input.to_str().unwrap()])
+ .args(["--check", check_input.to_str().unwrap()])
.status()
.unwrap()
.success()
@@ -344,7 +352,8 @@ fn qbench_json_is_guarded_and_machine_readable() {
assert!(json.status.success());
let stdout = String::from_utf8_lossy(&json.stdout);
let lines: Vec<_> = stdout.lines().collect();
- assert_eq!(lines.len(), 4);
+ assert_eq!(lines.len(), 5);
+ assert!(stdout.contains("\"name\":\"stepped-string-iteration\""));
for line in lines {
assert!(line.starts_with('{') && line.ends_with('}'));
for field in [
diff --git a/tests/embedding_api.rs b/tests/embedding_api.rs
index a799a95..20a4c95 100644
--- a/tests/embedding_api.rs
+++ b/tests/embedding_api.rs
@@ -1,4 +1,4 @@
-use quickcoffee::{Context, Engine, Error, ErrorKind, Value};
+use quickcoffee::{Context, Engine, Error, ErrorKind, Value, ValueKind};
#[test]
fn public_embedding_surface_runs_shared_programs_with_host_state() {
@@ -12,10 +12,7 @@ fn public_embedding_surface_runs_shared_programs_with_host_state() {
let mut context = Context::new();
context.set_global("factor", Value::from(2_i64));
context.add_native("host", |args| {
- let (Some(left), Some(right)) = (
- args.first().and_then(Value::as_number),
- args.get(1).and_then(Value::as_number),
- ) else {
+ let (Some(left), Some(right)) = (args[0].as_number(), args[1].as_number()) else {
return Err(Error::runtime("host expects two numbers"));
};
Ok(Value::from(left + right))
@@ -26,9 +23,6 @@ fn public_embedding_surface_runs_shared_programs_with_host_state() {
Some(84.)
);
assert_eq!(context.run_program(&clone).unwrap().as_number(), Some(84.));
- let missing = context.eval("host(20)").unwrap_err();
- assert_eq!(missing.kind(), ErrorKind::Runtime);
- assert_eq!(missing.message(), "host expects two numbers");
assert_eq!(context.get_global("factor").unwrap().as_number(), Some(2.));
assert!(context.get_global("missing").is_none());
}
@@ -44,9 +38,23 @@ fn public_values_and_native_errors_are_structured() {
]),
);
let values = context.get_global("host_values").unwrap();
+ assert_eq!(values.kind(), ValueKind::Map);
+ assert!(!values.is_nil());
let map = values.as_map().unwrap();
assert_eq!(map["answer"].as_number(), Some(42.));
assert_eq!(map["items"].as_array().unwrap()[0].as_str(), Some("coffee"));
+ assert_eq!(map["items"].kind(), ValueKind::Array);
+ assert_eq!(Value::from(false).kind(), ValueKind::Bool);
+ assert_eq!(Value::from(0_i64).kind(), ValueKind::Number);
+ assert_eq!(Value::from("coffee").kind(), ValueKind::String);
+ assert_eq!(
+ context.eval("(x) -> x").unwrap().kind(),
+ ValueKind::Function
+ );
+ assert!(!Value::from(false).is_nil());
+ assert!(!Value::from(0_i64).is_nil());
+ assert_eq!(Value::Nil.kind(), ValueKind::Nil);
+ assert!(Value::Nil.is_nil());
context.add_native("fail", |_| Err(Error::runtime("host failed")));
let error = context.eval("fail()").unwrap_err();
diff --git a/tests/rfc_core.rs b/tests/rfc_core.rs
index 1720d01..eaad428 100644
--- a/tests/rfc_core.rs
+++ b/tests/rfc_core.rs
@@ -983,9 +983,34 @@ fn string_iteration_uses_unicode_scalars_and_optional_scalar_indices() {
eval("for character in 'a☕中' when character == '☕' then character").to_string(),
"[☕]"
);
+ assert_eq!(
+ eval("for character in 'a☕中x' by 2 then character").to_string(),
+ "[a, 中]"
+ );
+ assert_eq!(
+ eval("for character, index in 'a☕中x' by 2 then index").to_string(),
+ "[0, 2]"
+ );
+ assert_eq!(
+ eval("step = 2\nfor character in 'a☕中x' by step then character").to_string(),
+ "[a, 中]"
+ );
+ assert_eq!(
+ eval("for character in 'a☕中x' by 2 when character != '中' then character").to_string(),
+ "[a]"
+ );
+ assert_eq!(
+ eval("for character in '' by 2 then character").to_string(),
+ "[]"
+ );
+ assert!(
+ Context::new()
+ .eval("for character in 'abc' by 0 then character")
+ .is_err()
+ );
assert!(
Context::new()
- .eval("for character in 'abc' by 2 then character")
+ .eval("for character in 'abc' by 1.5 then character")
.is_err()
);
let chunk = compile("for character in 'abc' then character").unwrap();
@@ -1314,11 +1339,6 @@ fn map_destructuring_accepts_literal_string_keys() {
eval("{'answer': value} = {answer: 42}\nvalue").as_number(),
Some(42.)
);
- assert!(
- Context::new()
- .eval("{\"first-name\"} = {\"first-name\": 'Ada'}")
- .is_err()
- );
assert!(
Context::new()
.eval("{\"missing-key\": value} = {other: 1}")