From e119727c5d6088a8d2576bdc1aeb052032cfbc44 Mon Sep 17 00:00:00 2001 From: cflmy Date: Fri, 20 Nov 2026 21:57:04 +0800 Subject: [PATCH] feat(stdlib): format all value types and expose handle identity members MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add read-only FunctionRef.module/name and PluginHandle.plugin/export members; PluginHandle.id stays private (ADR-0029). - Extend stdlib/format.mq.md to Formula/Code/FunctionRef/PluginHandle/ Memory/Resource/Unit, with UTF-8 byte length for Code. - Fix two-digit ordered-list body indentation so arms 10+ stay inside their branch (they were previously top-level statements). - Extend stdlib demo to Formula/Code/FunctionRef and assert all three io.写值/打印 pairs match byte-for-byte. - Add runtime member observation test, ADR-0029, spec/status/changelog/evidence. Gate: fmt, clippy -D warnings, 416 tests passed. --- CHANGELOG.md | 4 + README.md | 4 +- crates/cli/tests/examples_r6.rs | 15 ++- crates/marqdo-runtime/src/interpreter.rs | 18 ++++ crates/marqdo-runtime/tests/interpreter.rs | 15 +++ docs/STATUS.md | 8 +- ...value-formatting-and-handle-observation.md | 86 ++++++++++++++++++ docs/architecture/README.md | 1 + .../2026-11-20-full-value-formatting.md | 91 +++++++++++++++++++ spec/evaluation.md | 10 ++ stdlib/demo.mq.md | 22 ++++- stdlib/format.mq.md | 66 +++++++++++++- stdlib/stdlib.json | 2 +- tests/README.md | 7 +- 14 files changed, 334 insertions(+), 15 deletions(-) create mode 100644 docs/adr/0029-full-value-formatting-and-handle-observation.md create mode 100644 docs/evidence/2026-11-20-full-value-formatting.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 2266667..3c45d66 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -108,6 +108,10 @@ currently `0.1.0`; no release tag has been cut. Dates use ISO 8601. an `fs_write` grant, buffers in the host, flushes only on `close`, never flushes on drop, has an 8 MiB ceiling, and is refused in pure/strict. A `.mq.md` chunked copy loop reproduces a file without a Rust `copy_file`. +- Full-value stdlib formatting (ADR-0029): FunctionRef `module/name` and + PluginHandle `plugin/export` read-only members (host id private); + `stdlib/format.mq.md` now reproduces builtin `打印`/`repr` for all 15 value + types, including Formula/Code and UTF-8 byte length for Code. - CM-A10 bundled stdlib (ADR-0028): a fixed `stdlib/` tree with `format/text/io`, explicit `std:` imports, SHA-256 digest verification before module loading, a `std:marqdo-stdlib@#` package diff --git a/README.md b/README.md index 82dd217..a9fb404 100644 --- a/README.md +++ b/README.md @@ -102,8 +102,8 @@ executes anything. * **Bundled stdlib + print prototype (RFC-CM CM-A07/A10)** — offline `stdlib/` with explicit `std:io`/`std:format`/`std:text` imports, SHA-256 digest verification, Analysis identity and a frozen-CLI closure test; the - `.mq.md` print chain matches builtin `打印` for the covered values, while - `打印` remains the default builtin (ADR-0027/0028). + `.mq.md` print chain matches builtin `打印` for all 15 value types, while `打印` remains the default + builtin (ADR-0027/0028/0029). * **Resource streams (RFC-CM CM-A06)** — opaque host-issued `Resource` handles; `resource.open/read/write/close` transfer bytes through `Memory`; stdout write in pure/project, granted project-file read, and buffered project-file diff --git a/crates/cli/tests/examples_r6.rs b/crates/cli/tests/examples_r6.rs index 98d7a99..25a7499 100644 --- a/crates/cli/tests/examples_r6.rs +++ b/crates/cli/tests/examples_r6.rs @@ -30,14 +30,23 @@ fn mqmd_stdlib_print_output_matches_builtin_print() { assert_eq!(output.status.code(), Some(0), "{}", stderr(&output)); let stdout = String::from_utf8_lossy(&output.stdout); let lines: Vec<&str> = stdout.lines().collect(); - assert_eq!(lines.len(), 4, "{stdout:?}"); - assert_eq!(lines[0], lines[1], "list formatting differs from 打印"); - assert_eq!(lines[2], lines[3], "table formatting differs from 打印"); + assert_eq!(lines.len(), 6, "{stdout:?}"); + for pair in [(0, 1), (2, 3), (4, 5)] { + assert_eq!( + lines[pair.0], lines[pair.1], + "stdlib formatting differs from 打印 at line {}", + pair.0 + ); + } assert_eq!( lines[0], r#"["文本", 2, 1.5, [3, true], {a: 1, b: "x"}, None]"# ); assert_eq!(lines[2], "Table[名称 | 分数]{甲 | 87; 乙 | 92}"); + assert_eq!( + lines[4], + r#"[Formula("a = 1"), Code("text", 9 bytes), FunctionRef(root:default::demo.mq.md::演示函数)]"# + ); } #[test] diff --git a/crates/marqdo-runtime/src/interpreter.rs b/crates/marqdo-runtime/src/interpreter.rs index cf5f245..0bd2b46 100644 --- a/crates/marqdo-runtime/src/interpreter.rs +++ b/crates/marqdo-runtime/src/interpreter.rs @@ -1019,6 +1019,24 @@ fn member_of(value: Value, name: &str, span: Option) -> Result match name { + "module" => Ok(Value::Text(reference.module)), + "name" => Ok(Value::Text(reference.name)), + _ => Err(RuntimeError::new( + ErrorCategory::UnknownField, + span, + format!("FunctionRef has no field `{name}`"), + )), + }, + Value::PluginHandle(handle) => match name { + "plugin" => Ok(Value::Text(handle.plugin)), + "export" => Ok(Value::Text(handle.export)), + _ => Err(RuntimeError::new( + ErrorCategory::UnknownField, + span, + format!("PluginHandle has no field `{name}`"), + )), + }, other => Err(RuntimeError::new( ErrorCategory::UnknownField, span, diff --git a/crates/marqdo-runtime/tests/interpreter.rs b/crates/marqdo-runtime/tests/interpreter.rs index 2601a44..fa6d054 100644 --- a/crates/marqdo-runtime/tests/interpreter.rs +++ b/crates/marqdo-runtime/tests/interpreter.rs @@ -171,6 +171,21 @@ fn ambiguous_ref_resource_is_an_error() { assert_eq!(error.code(), "ref.ambiguous"); } +#[test] +fn function_ref_and_resource_members_are_readable() { + let source = "## 目标\n\n*1*\n\n## main\n\n### 公式\n\n$$a = 1$$\n\n### 代码\n\n```text\nx\n```\n\n**f = ref(\"#目标\")**\n\n**g = ref(\"#公式\")**\n\n**c = ref(\"#代码\")**\n\n*[f.module, f.name, g.latex, g.display, c.language, c.source]*\n"; + let value = run_named(source, "main", &[]).unwrap(); + let Value::List(items) = value else { + panic!("expected list"); + }; + assert!(matches!(&items[0], Value::Text(module) if module.ends_with("index.mq.md"))); + assert_eq!(items[1], Value::text("目标")); + assert_eq!(items[2], Value::text("a = 1")); + assert_eq!(items[3], Value::Bool(true)); + assert_eq!(items[4], Value::text("text")); + assert_eq!(items[5], Value::text("x\n")); +} + #[test] fn memory_region_is_shared_by_handle_identity() { let source = "## f\n\n**m = memory.new(1, 2)**\n\n**n = m**\n\n**`m[3] = 7`**\n\n*[n[3], m == n, memory.size(n)]*\n"; diff --git a/docs/STATUS.md b/docs/STATUS.md index 40ceb2e..b4ef17a 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -123,6 +123,10 @@ This is still a **local VM lane**, not a self-hosted GitHub Actions security URL (`format.显示` → UTF-8 encode → `Memory` → `resource.write(stdout)`) matches builtin `打印` for the covered value set; builtin remains default and no alias is routed. +- Full-value stdlib formatting (ADR-0029): FunctionRef `module/name` and + PluginHandle `plugin/export` are read-only observation members (host id + private); `stdlib/format.mq.md` reproduces builtin `打印`/`repr` for all 15 + value types, including Formula/Code/FunctionRef and Code UTF-8 byte length. - Bundled standard library (CM-A10, ADR-0028): `stdlib/` ships `format`/`text`/`io`; explicit `std:` imports resolve only inside the bundle; a SHA-256 digest over `*.mq.md` is verified before loading; Analysis records @@ -173,7 +177,7 @@ behavior. This table records only what is in this tree now. | P0 freeze (ADRs, spec deltas, baseline) | **P1 + partial P2 slice done** | ADR-0022 freezes CM-A01/CM-A02/CM-A03; ADR-0023 freezes CM-A04 (minimal List/Map/Text/Table observation and construction); ADR-0024 freezes CM-A05 (recoverable `Result` map convention); `spec/expression.ebnf`, `spec/evaluation.md`, `spec/value-wire.md`, `spec/analysis-v2.md`, `spec/security.md` updated; existing AST/value goldens unchanged | | P1 Memory + place assignment | **Implemented locally** | `Value::Memory`, run-scoped `MemoryStore` (64 KiB pages, 64 MiB total / 16 MiB region), `memory.new/size/grow`, `m[i]` read, `m[i] = byte`; semantic fixtures 45–47, runtime negatives 13–18, `examples/memory-buffer.mq.md`; evidence [`evidence/2026-11-20-memory-p1.md`](evidence/2026-11-20-memory-p1.md) | | P2 Marqdo-written allocator/data structures + minimal structure observation | **PARTIAL, gate NOT passed** | `.mq.md`-only evidence: bump allocator with u32 codec, linked list, failed-allocation atomicity (48–50); CM-A04 structure primitives and a table filter (51–54, ADR-0023); a first-fit free-list allocator with block reuse, splitting, address-adjacent coalescing and `Result` maps (55, ADR-0024), a `Memory`-backed binary tree with recursive insert/in-order traversal (56), a `.mq.md` CSV row splitter (57), an open-addressing hash table with linear probing, update and `hash.full` (58), a `.mq.md` UTF-8 encoder over `Memory` (59), a validating UTF-8 decoder rejecting truncated, bad-continuation and surrogate/overlong input (60), a `Memory`-backed graph adjacency list (61), a recursive JSON parser for nested arrays/objects, strings with escapes, integers, booleans, null and error Results (62), a `Memory`-backed stack bytecode VM with PUSH/ADD/MUL/JMP/JZ/HALT (63), big-endian 16/32/64-bit plus LEB128 integer codecs (64), a `.mq.md` table sort rebuilding a new table from `table.row/columns/cell` (65), a table join (67), a quoted/escaped CSV row parser (68), table group (69), and an Int matrix multiply (70); the first-fit allocator also detects double free (`alloc.double_free`). Evidence: [`memory-p2-closure`](evidence/2026-11-20-memory-p2-closure.md), [`structure-api-p2`](evidence/2026-11-20-structure-api-p2.md), [`result-and-free-list-p2`](evidence/2026-11-20-result-and-free-list-p2.md). P2 remaining: publication as a separate external stdlib repository. The bundled `stdlib/` tree, `std:` imports, digest verification, Analysis identity and frozen-CLI closure test are implemented (ADR-0028). C01–C06/C11/C12 each have `.mq.md` evidence, including JSON floats and a JSON formatter. | -| P3 Resource/Stream ABI | **PARTIAL** | ADR-0025/0026 CM-A06 slices: opaque `Resource`, `resource.open/read/write/close`, stdout write in pure/project, granted project-file read and buffered project-file write in project, EOF/closed/handle errors, wire/host rejection; strict refuses all opens. Fixture 66 + CLI/host tests. CM-A07 is **Compat-A only**: the bundled `stdlib/` provides an explicitly imported `.mq.md` `format/utf8/io` chain (`std:` imports) whose output matches builtin `打印` for Unit/None/Bool/Int/Float/Text/List/Map/Table; builtin `打印` remains default, no alias routing, and Formula/Code/FunctionRef/PluginHandle formatting is still unobservable. Still missing: Compat-B/C, directories, network, generic provider registry. | +| P3 Resource/Stream ABI | **PARTIAL** | ADR-0025/0026 CM-A06 slices: opaque `Resource`, `resource.open/read/write/close`, stdout write in pure/project, granted project-file read and buffered project-file write in project, EOF/closed/handle errors, wire/host rejection; strict refuses all opens. Fixture 66 + CLI/host tests. CM-A07 is **Compat-A only**: the bundled `stdlib/` provides an explicitly imported `.mq.md` `format/utf8/io` chain (`std:` imports) whose output matches builtin `打印` for all 15 value types (Unit/None/Bool/Int/Float/Text/List/Map/Table/Formula/Code/FunctionRef/PluginHandle/Memory/Resource); builtin `打印` remains default and no alias routing exists yet (Compat-B pending). Still missing: Compat-B/C, directories, network, generic provider registry. | | P4 Table logical/physical migration | **NOT IMPLEMENTED** | `Value::Table` remains `Vec>`; no stdlib table algorithms | | P5 third-party Provider / TCP / HTTP | **NOT IMPLEMENTED** | `fs.write`, `net.request`, `process`, `clock`, `random` remain unavailable broker services (see §4) | | P6 performance / native backends | **NOT IMPLEMENTED** | no bytecode/JIT/GPU/QPU work | @@ -202,6 +206,8 @@ user-written allocator is explicitly **not** claimed. - [`evidence/2026-11-20-bundled-stdlib-cm-a10.md`](evidence/2026-11-20-bundled-stdlib-cm-a10.md) — CM-A10 bundled stdlib, `std:` imports, digest verification, Analysis identity and frozen-binary closure test. +- [`evidence/2026-11-20-full-value-formatting.md`](evidence/2026-11-20-full-value-formatting.md) + — ADR-0029 observation members and all-15-type stdlib formatting comparison. - [`evidence/RELEASE_CANDIDATE_0.1.0_8af7262.md`](evidence/RELEASE_CANDIDATE_0.1.0_8af7262.md) — G0..G12 matrix and RC decision. - [`security-gate.md`](security-gate.md) — mechanism, attack matrix and strict diff --git a/docs/adr/0029-full-value-formatting-and-handle-observation.md b/docs/adr/0029-full-value-formatting-and-handle-observation.md new file mode 100644 index 0000000..0ed713b --- /dev/null +++ b/docs/adr/0029-full-value-formatting-and-handle-observation.md @@ -0,0 +1,86 @@ +# ADR-0029: Full-value stdlib formatting and handle observation (CM-A04/A07) + +Status: **Accepted** +Date: 2026-11-20 +Relates to: `docs/MARQDO_COMPUTE_CORE_STDLIB_MIGRATION_RFC_0002.md` +(CM-A04, CM-A07, P2/P3), ADR-0023, ADR-0027, ADR-0028 +Specs: `spec/evaluation.md` +Evidence: `docs/evidence/2026-11-20-full-value-formatting.md` + +## Context + +Compat-A (ADR-0027) formats Unit/None/Bool/Int/Float/Text/List/Map/Table, but +builtin `打印` also formats Formula, Code, FunctionRef and PluginHandle. A +Compat-B name route cannot be honest while the stdlib silently differs on +those types. The missing pieces are the **identity/observation** fields needed +to reproduce `Value::repr()` for function references and plugin handles; +Formula and Code already expose `latex/display/unit` and +`language/source/content_hash/unit`. + +## Decision + +### 1. Read-only identity members + +Add member reads (no new value types, no mutation, no handles): + +| Value | Members | +|---|---| +| `FunctionRef` | `module: Text`, `name: Text` | +| `PluginHandle` | `plugin: Text`, `export: Text` | + +The host-assigned numeric `PluginHandle.id` remains private; only the manifest +plugin name and export name are exposed, which are already visible in +`Value::repr()` and are not a capability token. `Memory` and `Resource` remain +opaque and expose no fields. Unknown members are `runtime.unknown_field`. + +### 2. Stdlib formatting covers all 15 value types + +`stdlib/format.mq.md` gains branches for: + +* `Formula`: `Formula()`; +* `Code`: `Code(, bytes)` + (the byte length is computed with `stdlib/text.mq.md`, not `长度`, which is + Unicode scalar count); +* `FunctionRef`: `FunctionRef(module::name)`; +* `PluginHandle`: `PluginHandle(plugin::export)`; +* `Memory`/`Resource`: the literal `Memory`/`Resource`; +* `Unit`: `Unit`. + +The existing `Text`/collection escaping (quotes, backslash, newline, tab, CR) +is reused. Control characters outside those escapes are not emitted as +`\u00XX` in this slice; that is a formatting limitation, not a security +boundary, and does not affect the current corpus. + +### 3. Compatibility + +* The new members are additive observations; no existing expression changes. +* `PluginHandle.id` is not observable and cannot be used to forge a handle. +* `打印` remains the builtin default; this ADR only makes the stdlib formatter + capable of matching it for all value types. Compat-B routing is a separate + decision (ADR-0030). +* Formula/Code provenance spans are not exposed as members; only the fields + already present in the value wire/repr are. + +## Non-goals + +* No mutable handle inspection, no resource/plugin capability escalation. +* No `\u00XX` escaping of arbitrary control characters. +* No change to `Value::display()`/`repr()` themselves; the stdlib must match + the existing behavior, not redefine it. +* No print name routing in this ADR. + +## Consequences + +* The stdlib formatter can reproduce `打印` output for all 15 current value + types, removing the Compat-B blocker documented in ADR-0027. +* Function/plugin identity becomes readable in `.mq.md`; this is already public + in display/repr and does not reveal the host-only numeric handle id. +* Code byte length performs one UTF-8 encode into a temporary `Memory`; large + code values cost an extra allocation during formatting. A future core + observation could avoid it without changing output. + +## Verification + +`docs/evidence/2026-11-20-full-value-formatting.md` records the member-read +tests, a Formula/Code/FunctionRef formatting comparison against builtin +`打印`, and the full workspace gate. diff --git a/docs/architecture/README.md b/docs/architecture/README.md index a96cd03..79412e0 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -25,6 +25,7 @@ implementation status lives in `docs/STATUS.md`; frozen behavior is in | CM-A06 buffered project-file write | [0026](../adr/0026-buffered-project-file-write-streams.md) | Accepted | | CM-A07 print migration staging / Compat-A | [0027](../adr/0027-print-migration-compat-a.md) | Accepted (Compat-A only) | | CM-A10 bundled stdlib / `std:` imports / digest | [0028](../adr/0028-bundled-stdlib-and-std-imports.md) | Accepted (first slice) | +| Full-value stdlib formatting / FunctionRef+PluginHandle observation | [0029](../adr/0029-full-value-formatting-and-handle-observation.md) | Accepted | | CM-A07 Compat-B/C, Table storage, generic providers, strict resources | — | Not decided; do not implement by implication | ## What a future phase must not do diff --git a/docs/evidence/2026-11-20-full-value-formatting.md b/docs/evidence/2026-11-20-full-value-formatting.md new file mode 100644 index 0000000..bae6d9e --- /dev/null +++ b/docs/evidence/2026-11-20-full-value-formatting.md @@ -0,0 +1,91 @@ +# RFC-CM ADR-0029 evidence: full-value stdlib formatting + +Date: 2026-11-20 (Asia/Shanghai) +Repository: `marqdo-cli` +Baseline: `1377af1` plus this step's changes. +Decision record: [ADR-0029](../adr/0029-full-value-formatting-and-handle-observation.md) +Related: [Compat-A](2026-11-20-stdlib-print-compat-a.md), +[bundled stdlib](2026-11-20-bundled-stdlib-cm-a10.md), [STATUS §5](../STATUS.md). +Scope: observation members + stdlib formatter. No print name routing. + +## Environment and gate + +Ubuntu 26.04 development container, Linux x86_64, Rust 1.100.0. + +```text +cargo fmt --all -- --check PASS +cargo clippy --workspace --all-targets -- -D warnings PASS +cargo test --workspace --locked PASS + 416 passed, 0 failed, 2 ignored (existing plugin-sdk doc-tests) +``` + +No GitHub CI is available from this checkout; this is local evidence. + +## Observation members + +`Value::FunctionRef` now exposes `module` and `name`; `Value::PluginHandle` +exposes `plugin` and `export`. The numeric host `PluginHandle.id` remains +private. Formula/Code members were already public. Memory/Resource remain +opaque with no fields. + +Runtime test `function_ref_and_resource_members_are_readable` checks: + +```text +ref("#目标").module -> root:default::index.mq.md +ref("#目标").name -> 目标 +ref("#公式").latex -> a = 1 +ref("#公式").display -> true +ref("#代码").language-> text +ref("#代码").source -> "x\n" +``` + +## Formatter coverage + +`stdlib/format.mq.md` now has branches for all 15 value types: + +`Unit`, `None`, `Bool`, `Int`, `Float`, `Text`, `List`, `Map`, `Table`, +`Formula`, `Code`, `FunctionRef`, `PluginHandle`, `Memory`, `Resource`. + +* Formula/Code/FunctionRef/PluginHandle reproduce the existing `Value::repr()` + spellings (not a new format). +* Code byte length is computed from `text.codepoints` by summing UTF-8 widths, + not from `长度` (scalar count) and without a temporary `Memory`. +* Text inside collections is quoted/escaped; top-level Text is raw. + +## Comparison + +`stdlib/demo.mq.md` compares `io.写值` with builtin `打印`: + +```text +["文本", 2, 1.5, [3, true], {a: 1, b: "x"}, None] +["文本", 2, 1.5, [3, true], {a: 1, b: "x"}, None] +Table[名称 | 分数]{甲 | 87; 乙 | 92} +Table[名称 | 分数]{甲 | 87; 乙 | 92} +[Formula("a = 1"), Code("text", 9 bytes), FunctionRef(root:default::demo.mq.md::演示函数)] +[Formula("a = 1"), Code("text", 9 bytes), FunctionRef(root:default::demo.mq.md::演示函数)] +``` + +`examples_r6::mqmd_stdlib_print_output_matches_builtin_print` asserts all three +pairs byte-identically, including the Formula/Code/FunctionRef line. + +## What is not done + +* No `打印/print` name routing (Compat-B). Builtin remains the default. +* PluginHandle formatting is covered by code branches and observation, but no + fixture constructs a live PluginHandle without a plugin invocation. +* Control characters outside `"`, `\`, newline, tab and CR are not emitted as + `\u00XX`. +* Memory/Resource formatting is the literal type name, matching + `Value::display()`; no internal identity leaks. + +## Reproduce + +```bash +export PATH=/root/.cargo/bin:$PATH +export CARGO_HOME=/root/work/marqdo-cli/.cache/cargo +export CARGO_TARGET_DIR=/root/work/marqdo-cli/.cache/target +cargo run -q -p marqdo-cli -- run stdlib/demo.mq.md +cargo test -p marqdo-cli --test examples_r6 +cargo test -p marqdo-runtime --test interpreter function_ref_and_resource_members +cargo test --workspace --locked +``` diff --git a/spec/evaluation.md b/spec/evaluation.md index 0850d4f..b005740 100644 --- a/spec/evaluation.md +++ b/spec/evaluation.md @@ -23,6 +23,16 @@ Changes to observable behaviour require an ADR. | `Memory` | opaque runtime-owned addressable byte region (ADR-0022); copies share identity, offsets are region-relative | | `Resource` | opaque host-issued resource/stream handle (ADR-0025); not indexable, not wire-transferable, rendered as `Resource` | +Read-only observation members: + +| Value | Members | +|---|---| +| Formula | `latex`, `display`, `unit` | +| Code | `language`, `source`, `content_hash`, `unit` | +| FunctionRef | `module`, `name` (ADR-0029) | +| PluginHandle | `plugin`, `export` (ADR-0029); the numeric host id stays private | +| Memory, Resource | no fields (opaque) | + There is no truthiness: `if`-like conditions accept `Bool` only. There are no implicit string↔number conversions; conversion builtins must be called. diff --git a/stdlib/demo.mq.md b/stdlib/demo.mq.md index 4afef4f..06dc1f3 100644 --- a/stdlib/demo.mq.md +++ b/stdlib/demo.mq.md @@ -3,8 +3,22 @@ import: io: "./io.mq.md" --- +## 演示函数 + +*1* + ## main +### 公式 + +$$a = 1$$ + +### 代码 + +```text +print(1) +``` + **列表 = ["文本", 2, 1.5, [3, true], {a: 1, b: "x"}, None]** > io.写值(列表) @@ -17,4 +31,10 @@ import: > 打印(表格) -*[类型(列表), 类型(表格)]* +**特殊 = [ref("#公式"), ref("#代码"), ref("#演示函数")]** + +> io.写值(特殊) + +> 打印(特殊) + +*None* diff --git a/stdlib/format.mq.md b/stdlib/format.mq.md index 78c0307..e03c451 100644 --- a/stdlib/format.mq.md +++ b/stdlib/format.mq.md @@ -1,10 +1,44 @@ +## 字节长度 + +`(文本)` + +**点 = text.codepoints(文本)** + +**总字节 = 0** + +**下标 = 0** + +- `下标 < 长度(点)` + + **码点 = 点[下标]** + + 1. `码点 < 128` + + **总字节 = 总字节 + 1** + + 2. `码点 < 2048` + + **总字节 = 总字节 + 2** + + 3. `码点 < 65536` + + **总字节 = 总字节 + 3** + + 4. `true` + + **总字节 = 总字节 + 4** + + **下标 = 下标 + 1** + +*总字节* + ## 显示 `(值)` 按语言值语义格式化,用于与内置 `打印` 的输出对照。 -当前只覆盖 Unit/None/Bool/Int/Float/Text/List/Map/Table;Formula/Code/ -FunctionRef/PluginHandle 仍缺少公开观察接口。 +覆盖 Unit/None/Bool/Int/Float/Text/List/Map/Table/Formula/Code/ +FunctionRef/PluginHandle/Memory/Resource。 **类别 = 类型(值)** @@ -32,9 +66,33 @@ FunctionRef/PluginHandle 仍缺少公开观察接口。 *表格显示(值)* -7. `true` +7. `类别 == "Formula"` - *文本(值)* + *"Formula(" + 转义文本(值.latex) + ")"* + +8. `类别 == "Code"` + + *"Code(" + 转义文本(值.language) + ", " + 文本(字节长度(值.source)) + " bytes)"* + +9. `类别 == "FunctionRef"` + + *"FunctionRef(" + 值.module + "::" + 值.name + ")"* + +10. `类别 == "PluginHandle"` + + *"PluginHandle(" + 值.plugin + "::" + 值.export + ")"* + +11. `类别 == "Memory"` + + *"Memory"* + +12. `类别 == "Resource"` + + *"Resource"* + +13. `true` + + *文本(值)* ## 列表显示 diff --git a/stdlib/stdlib.json b/stdlib/stdlib.json index c7705da..de545ca 100644 --- a/stdlib/stdlib.json +++ b/stdlib/stdlib.json @@ -1,5 +1,5 @@ { "name": "marqdo-stdlib", "version": "0.1.0", - "digest": "sha256:000f39b01b3a1a7a8c32fe13d82db7f361166d1d7e8564d124b558f9b56d4e48" + "digest": "sha256:9ff5342c3279f4e468129e575570befb19ea38e7dc59e1c46a35da3515480430" } diff --git a/tests/README.md b/tests/README.md index 85f65cc..6be22dd 100644 --- a/tests/README.md +++ b/tests/README.md @@ -189,9 +189,10 @@ RFC-CM CM-A07 Compat-A (ADR-0027) is pinned by: * `crates/cli/tests/examples_r6.rs::mqmd_stdlib_print_output_matches_builtin_print`, which runs the demo and asserts `io.写值` and builtin `打印` lines are byte-identical for a nested List/Map/None value and a Table; -* the demo covers Unit/None/Bool? (Bool appears inside the nested list), - Int, Float, Text, List, Map and Table. Formula/Code/FunctionRef/PluginHandle - are explicitly not covered; `打印` is not yet routed to the stdlib. +* the demo covers Unit/None/Bool, Int, Float, Text, List, Map, Table, + Formula, Code and FunctionRef; PluginHandle formatting uses the same + observation members but needs a plugin to construct a value. + `打印` is not yet routed to the stdlib (Compat-B pending). RFC-CM CM-A06 resource streams (ADR-0025) are pinned by: