103 lines
5.1 KiB
Markdown
103 lines
5.1 KiB
Markdown
# marqdo-stdlib (bundled first slice)
|
|
|
|
This directory is the official, offline `marqdo-stdlib` bundle consumed by
|
|
`std:<path>` imports. The CLI verifies `stdlib.json.digest` before loading any
|
|
module; a mismatch is a hard error.
|
|
|
|
> **Migration status (RFC-LANG-0002): the sources here are still pre-RFC and
|
|
> do not yet use the current language syntax.** Every `.mq.md` module in this
|
|
> directory is written in the superseded mapping (unmarked H2 as function,
|
|
> `Strong` as execution, `Emph` as return, ordered-list branches, bullet-list
|
|
> loops, block-quote calls, first code-span signatures). They are **not**
|
|
> valid sources for the target language and are not syntax examples to copy.
|
|
> The bundled stdlib will be migrated together with the Rust frontend and
|
|
> expression parser; `stdlib.json` and this digest will then be regenerated in
|
|
> the same change. Do not claim the stdlib already uses the new syntax.
|
|
> Authority:
|
|
> [`docs/architecture/RFC-LANG-0002-unified-semantics.md`](../docs/architecture/RFC-LANG-0002-unified-semantics.md),
|
|
> normative summary [`spec/mapping.md`](../spec/mapping.md), status
|
|
> [`docs/STATUS.md`](../docs/STATUS.md).
|
|
|
|
- `format.mq.md` — value formatting (`显示`, list/map/table display, escaping)
|
|
- `text.mq.md` — compatibility UTF-8 encoding into `Memory`
|
|
- `text/utf8.mq.md` — `.mq.md` UTF-8 encoder and validating decoder
|
|
- `io.mq.md` — compatibility facade over `stream` and `console`
|
|
- `fs/file.mq.md` — bounded project-file read/write/copy over `resource.*`
|
|
- `io/stream.mq.md` — `写全部` / `写文本` with short-write and close checking
|
|
- `io/console.mq.md` — `读取行` / `打印` over `stdio/stdin` and `stdio/stdout`
|
|
- `demo.mq.md` — side-by-side comparison with builtin `打印`
|
|
- `data/json.mq.md` — recursive JSON parser/formatter, 128-depth bound, multi-value
|
|
- `data/csv.mq.md` — quoted single/multi-row CSV parser and formatter
|
|
- `data/table.mq.md` — value-returning table select/filter/sort/append/set/join/group/GFM
|
|
- `env.mq.md` — explicitly granted `env.get` names over `resource.request`
|
|
- `process.mq.md` — explicitly granted `process.run` with timeout/output caps
|
|
- `compress.mq.md` — deterministic gzip compress/decompress over byte lists
|
|
- `random.mq.md` — explicitly granted OS entropy bytes/integers
|
|
- `datetime.mq.md` — UTC ISO-8601 format/parse over Unix milliseconds (pure)
|
|
- `clock.mq.md` — project-mode `clock.now` over `resource.request`
|
|
- `path.mq.md` — lexical join/basename/dirname/extension/normalize (no I/O)
|
|
- `regex.mq.md` — pure subset matcher + host-backed groups/alternation/captures
|
|
- `net/http.mq.md` — byte-exact HTTP/1.1 parsing (chunked) and request builder
|
|
- `tests/` — product self-tests for every public module
|
|
(`clock`, `compress`, `console`, `csv`, `datetime`, `demo`, `env`, `format`, `fs`, `http`,
|
|
`io`, `json`, `path`, `process`, `random`, `regex`, `stream`, `table`, `text`, `utf8`)
|
|
|
|
The digest is a SHA-256 over sorted `*.mq.md` relative paths, a NUL, file
|
|
bytes, and a NUL. It excludes `stdlib.json` and non-`.mq.md` files. After any
|
|
module change, regenerate it with:
|
|
|
|
```bash
|
|
python3 - stdlib <<'PY'
|
|
import hashlib, json, sys
|
|
from pathlib import Path
|
|
root=Path(sys.argv[1])
|
|
h=hashlib.sha256()
|
|
for p in sorted(root.rglob('*.mq.md'), key=lambda p: p.relative_to(root).as_posix()):
|
|
h.update(p.relative_to(root).as_posix().encode()); h.update(b'\0')
|
|
h.update(p.read_bytes()); h.update(b'\0')
|
|
manifest=json.loads((root/'stdlib.json').read_text())
|
|
manifest['digest']='sha256:'+h.hexdigest()
|
|
(root/'stdlib.json').write_text(json.dumps(manifest, indent=2)+'\n')
|
|
PY
|
|
```
|
|
|
|
The version/digest are part of each stdlib module's package instance id, so a
|
|
different bundle cannot silently masquerade as the one a project was checked
|
|
against.
|
|
|
|
## Official public aliases (`public_aliases`)
|
|
|
|
`stdlib.json` can declare language-surface aliases that are bound as ordinary
|
|
`Marqdo` functions (ADR-0058). The current table contains:
|
|
|
|
```json
|
|
"public_aliases": [
|
|
{
|
|
"public_names": ["print", "打印"],
|
|
"target_module": "io.mq.md",
|
|
"target_function": "写值",
|
|
"expected_signature": "params(值)",
|
|
"effects": ["host"]
|
|
}
|
|
],
|
|
"aliases_digest": "sha256:<64 lowercase hex>"
|
|
```
|
|
|
|
Rules:
|
|
|
|
* Only this verified bundle may declare a public alias. Third-party packages
|
|
cannot claim `打印`/`print`, `std.*` or `marqdo.*` names.
|
|
* `aliases_digest` is the SHA-256 of the canonical alias encoding: for each
|
|
alias sorted by `(target_module, target_function)`, module bytes + NUL,
|
|
function bytes + NUL, then each public name sorted + NUL. The loader verifies
|
|
it together with the `.mq.md` tree digest before loading any module; a
|
|
tampered table is a load error.
|
|
* The loader loads `target_module` only when the program references one of the
|
|
`public_names`, then binds the call to the ordinary target `FunctionId`; the
|
|
runtime has no print branch and `Program.print_override` does not exist.
|
|
* `expected_signature` is checked against the target function's declared
|
|
parameters; a mismatch is a load error.
|
|
* Output/error/Trace behavior must remain byte-identical for an official
|
|
install; `tools/pack-stdlib.py` refuses to package a bundle whose
|
|
`aliases_digest` does not match `public_aliases`.
|