diff --git a/Cargo.lock b/Cargo.lock index 76ff9ee..0de2e54 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -11,6 +11,15 @@ dependencies = [ "memchr", ] +[[package]] +name = "android_system_properties" +version = "0.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "819e7219dbd41043ac279b19830f2efc897156490d7fd6ea916720117ee66311" +dependencies = [ + "libc", +] + [[package]] name = "anstream" version = "0.6.21" @@ -111,6 +120,39 @@ dependencies = [ "serde_core", ] +[[package]] +name = "bumpalo" +version = "3.20.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649" + +[[package]] +name = "cc" +version = "1.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5add81bb678e6cb321aff7fa0dc7689ad82b112dbc032cea19f91d6b8e3582b9" +dependencies = [ + "find-msvc-tools", + "shlex", +] + +[[package]] +name = "cfg-if" +version = "1.0.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801" + +[[package]] +name = "chrono" +version = "0.4.45" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1aa79e62e7697b8e29b513a68abacf485adcd1fe8284a4316c5ae868e6633327" +dependencies = [ + "iana-time-zone", + "num-traits", + "windows-link", +] + [[package]] name = "chunked_transfer" version = "1.5.0" @@ -163,6 +205,12 @@ version = "1.0.5" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570" +[[package]] +name = "core-foundation-sys" +version = "0.8.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b" + [[package]] name = "difflib" version = "0.4.0" @@ -175,6 +223,12 @@ version = "0.3.4" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "780955b8b195a21ab8e4ac6b60dd1dbdcec1dc6c51c0617964b08c81785e12c9" +[[package]] +name = "find-msvc-tools" +version = "0.1.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582" + [[package]] name = "float-cmp" version = "0.9.0" @@ -184,6 +238,30 @@ dependencies = [ "num-traits", ] +[[package]] +name = "futures-core" +version = "0.3.33" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2cd50c473c80f6d7c3670a752354b8e569b1a7cbfdc0419ec88e5edad85e0dc7" + +[[package]] +name = "futures-task" +version = "0.3.33" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b231ed28831efb4a61a08580c4bc233ec56bc009f4cd8f52da2c3cb97df0c109" + +[[package]] +name = "futures-util" +version = "0.3.33" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a77a90a256fce34da66415271e30f94ee91c57b04b8a2c042d9cf3220179deaa" +dependencies = [ + "futures-core", + "futures-task", + "pin-project-lite", + "slab", +] + [[package]] name = "getopts" version = "0.2.24" @@ -205,12 +283,53 @@ version = "1.0.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "df3b46402a9d5adb4c86a0cf463f42e19994e3ee891101b1841f30a545cb49a9" +[[package]] +name = "iana-time-zone" +version = "0.1.65" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e31bc9ad994ba00e440a8aa5c9ef0ec67d5cb5e5cb0cc7f8b744a35b389cc470" +dependencies = [ + "android_system_properties", + "core-foundation-sys", + "iana-time-zone-haiku", + "js-sys", + "log", + "wasm-bindgen", + "windows-core", +] + +[[package]] +name = "iana-time-zone-haiku" +version = "0.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f31827a206f56af32e590ba56d5d2d085f558508192593743f16b2306495269f" +dependencies = [ + "cc", +] + [[package]] name = "is_terminal_polyfill" version = "1.70.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695" +[[package]] +name = "itoa" +version = "1.0.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682" + +[[package]] +name = "js-sys" +version = "0.3.103" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "53b44bfcdb3f8d5837a46dae1ca9660a837176eee74a28b229bc626816589102" +dependencies = [ + "cfg-if", + "futures-util", + "wasm-bindgen", +] + [[package]] name = "libc" version = "0.2.189" @@ -229,9 +348,11 @@ version = "0.0.3" dependencies = [ "anyhow", "assert_cmd", + "chrono", "clap", "predicates", "pulldown-cmark", + "serde_json", "thiserror", "tiny_http", ] @@ -257,12 +378,24 @@ dependencies = [ "autocfg", ] +[[package]] +name = "once_cell" +version = "1.21.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50" + [[package]] name = "once_cell_polyfill" version = "1.70.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe" +[[package]] +name = "pin-project-lite" +version = "0.2.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd" + [[package]] name = "predicates" version = "3.1.0" @@ -359,6 +492,21 @@ version = "0.8.11" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4" +[[package]] +name = "rustversion" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f" + +[[package]] +name = "serde" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba" +dependencies = [ + "serde_core", +] + [[package]] name = "serde_core" version = "1.0.229" @@ -379,6 +527,31 @@ dependencies = [ "syn 3.0.3", ] +[[package]] +name = "serde_json" +version = "1.0.151" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14" +dependencies = [ + "itoa", + "memchr", + "serde", + "serde_core", + "zmij", +] + +[[package]] +name = "shlex" +version = "2.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba" + +[[package]] +name = "slab" +version = "0.4.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5" + [[package]] name = "strsim" version = "0.10.0" @@ -478,12 +651,110 @@ dependencies = [ "libc", ] +[[package]] +name = "wasm-bindgen" +version = "0.2.126" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4b067c0c11094aef6b7a801c1e34a26affafdf3d051dba08456b868789aaf9a4" +dependencies = [ + "cfg-if", + "once_cell", + "rustversion", + "wasm-bindgen-macro", + "wasm-bindgen-shared", +] + +[[package]] +name = "wasm-bindgen-macro" +version = "0.2.126" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "167ce5e579f6bcf889c4f7175a8a5a585de84e8ff93976ce393efa5f2837aab1" +dependencies = [ + "quote", + "wasm-bindgen-macro-support", +] + +[[package]] +name = "wasm-bindgen-macro-support" +version = "0.2.126" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f3997c7839262f4ef12cf90b818d6340c18e80f263f1a94bf157d0ec4420380e" +dependencies = [ + "bumpalo", + "proc-macro2", + "quote", + "syn 2.0.119", + "wasm-bindgen-shared", +] + +[[package]] +name = "wasm-bindgen-shared" +version = "0.2.126" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dc1b4cb0cc549fcf58d7dfc081778139b3d283a081644e833e84682ad71cea24" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "windows-core" +version = "0.62.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b8e83a14d34d0623b51dce9581199302a221863196a1dde71a7663a4c2be9deb" +dependencies = [ + "windows-implement", + "windows-interface", + "windows-link", + "windows-result", + "windows-strings", +] + +[[package]] +name = "windows-implement" +version = "0.60.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "windows-interface" +version = "0.59.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + [[package]] name = "windows-link" version = "0.2.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5" +[[package]] +name = "windows-result" +version = "0.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7781fa89eaf60850ac3d2da7af8e5242a5ea78d1a11c49bf2910bb5a73853eb5" +dependencies = [ + "windows-link", +] + +[[package]] +name = "windows-strings" +version = "0.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7837d08f69c77cf6b07689544538e017c1bfcf57e34b4c0ff58e6c2cd3b37091" +dependencies = [ + "windows-link", +] + [[package]] name = "windows-sys" version = "0.61.2" @@ -492,3 +763,9 @@ checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc" dependencies = [ "windows-link", ] + +[[package]] +name = "zmij" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b" diff --git a/Cargo.toml b/Cargo.toml index 5de00d0..1d7d927 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -13,8 +13,10 @@ path = "src/main.rs" [dependencies] anyhow = "1" +chrono = { version = "0.4", default-features = false, features = ["clock", "std"] } clap = { version = "=4.4.18", features = ["derive"] } pulldown-cmark = "0.12" +serde_json = "1" thiserror = "1" tiny_http = "0.12" diff --git a/doc/README.md b/doc/README.md index a844724..f138af8 100644 --- a/doc/README.md +++ b/doc/README.md @@ -26,6 +26,9 @@ | [design/keywords-i18n.md](design/keywords-i18n.md) | **内核中英双名(无需导入;少而精)** | | [design/stdlib.md](design/stdlib.md) | **P2 标准库:内置 + `lib/` + 错误约定** | | [design/stdlib-i18n.md](design/stdlib-i18n.md) | **标准库中英命名:靠库文件名区分,无 lang 开关** | +| [design/stdlib-modules.md](design/stdlib-modules.md) | **本波 L1:文件/系统/时间/JSON/网络(JSON 中英同库)** | +| [design/stdlib-math.md](design/stdlib-math.md) | **暂缓:数学库(数值/符号/作图/`$$`)** | +| [design/stdlib-foreign.md](design/stdlib-foreign.md) | **暂缓:外联胶水(\`\`\`lang 具名块)** | | [design/call-arguments.md](design/call-arguments.md) | **调用:具名 + 位置实参** | | [design/examples-and-tests.md](design/examples-and-tests.md) | **tests/ 金样例目录布局** | | [design/view.md](design/view.md) | **`marqdo view` / `view output` 黑白极简 + 静态文档** | diff --git a/doc/design/stdlib-foreign.md b/doc/design/stdlib-foreign.md new file mode 100644 index 0000000..0a98bb5 --- /dev/null +++ b/doc/design/stdlib-foreign.md @@ -0,0 +1,207 @@ +# 外联 / 胶水标准库(候选) + +| | | +|---|---| +| 状态 | **草案 / 暂缓**(本波不实现;五库之后再议) | +| 日期 | 2026-08-05 | +| 相关 | [stdlib-modules.md](stdlib-modules.md) · [code-vs-comment.md](code-vs-comment.md) · [markdown-mapping.md](markdown-mapping.md) · [stdlib-math.md](stdlib-math.md) | +| 灵感 | Markdown \`\`\`lang 代码块;Marqdo 作编排层 | + +--- + +## 1. 为什么值得做 + +[code-vs-comment.md](code-vs-comment.md) 已划出**外联面**:\`\`\`lang 是「其它语言」。若运行时能: + +1. **收集**本文件(或导入图)中的围栏代码块; +2. 按语言 **subprocess / 嵌入运行时**执行; +3. 把 stdout / 约定返回值 **接回 Marqdo 值**; + +则 Marqdo 成为**文学化胶水语言**:结构、叙述、分支循环用 Marqdo,重活交给 Python/JS/Shell/SQL。 + +风险:安全(任意代码)、可复现(环境漂移)、view/CI(无解释器)——故为**候选**,默认关闭。 + +--- + +## 2. 与叙述面的边界 + +| 面 | 行为 | +|----|------| +| 叙述段里的 \`\`\` | 今日:注释;**外联库启用后仍可配置为「可调用」或「仅展示」** | +| 可执行面附近的 \`\`\` | 建议:**具名块**才可调用,避免误跑文档里的示例 | + +推荐:**只有带名字的围栏**进入外联目录。 + +--- + +## 3. 命名围栏语法(草案) + +三种候选(实现前锁定一种): + +### 3.1 信息串后缀(推荐试水) + +````markdown +```python name=normalize +def normalize(s): + return s.strip().lower() +``` +```` + +或: + +````markdown +```python#normalize +… +``` +```` + +### 3.2 HTML 注释锚点 + +````markdown + +```python +… +``` +```` + +### 3.3 紧邻 Marqdo 声明 + +```markdown +*`normalize` = foreign_def lang=python * + +```python +… +``` +``` + +**倾向 3.1**:仍是合法 Markdown,多数渲染器忽略未知 info 字段;与「文档即源」一致。 + +未命名围栏:view 可语法高亮展示,**不可** `foreign_call`。 + +--- + +## 4. 导入与 API + +| 导入 | API 语言 | +|------|----------| +| `> lib/foreign.mq.md` | 英文 | +| `> lib/外联.mq.md` | 中文 | + +| 英文 | 中文 | 形参 | 结果 | +|------|------|------|------| +| `run` | `运行` | `name`, 可选 `stdin` / `名`, `标准输入` | 文本(stdout) | +| `run_lang` | `按语言运行` | `lang`, `source`, 可选 `stdin` | 文本 | +| `call` | `调用` | `name`, 可选 `args`(JSON 文本) | 文本 | +| `langs` | `语言表` | (无) | 已注册语言列表 | + +`call` 约定(v1): + +- 宿主把 `args` 经环境变量或临时 JSON 文件传给子进程; +- 被调代码打印**一行 JSON** 到 stdout 作为返回值; +- 或退出码非 0 → Marqdo 诊断。 + +更紧的 Python 嵌入(`pyo3`)列为后期优化,**v1 只用子进程**,便于推理安全边界。 + +--- + +## 5. 语言支持矩阵(v1) + +| 语言 | 探测 | 备注 | +|------|------|------| +| `python` / `python3` | `PATH` | 优先实现;服务科学计算与 [stdlib-math.md](stdlib-math.md) CAS 外置 | +| `node` / `javascript` | `PATH` | 第二 | +| `sh` / `bash` | Unix;Windows 可用 Git Bash 或跳过 | 高风险,默认更严 | +| `cmd` / `powershell` | Windows | 可选 | +| 其它 | 配置表 | `marqdo.toml` / 环境变量注册解释器路径 | + +无解释器时:清晰诊断 `foreign language not available: python`,而非静默跳过。 + +--- + +## 6. 权限模型(硬性) + +| 场景 | 默认 | +|------|------| +| `marqdo run` | **拒绝**,除非 `--allow-foreign` | +| `marqdo view` | 拒绝(或仅 `--allow-foreign` 的本地演示) | +| `view output` / CI 用户站 | **拒绝**(文档示例用录制输出或纯 Marqdo) | +| 金样例 | 用 `tests/foreign/` + 环境探测;无 Python 则 `ignore` | + +附加约束(可组合): + +- `--foreign-lang python,node` 白名单; +- 超时(默认 5–30s); +- 工作目录锁在文件所在根; +- 无网络(与 `--allow-net` 分离;子进程环境可剥 `HTTP_PROXY` 等——尽力而为)。 + +--- + +## 7. 典型胶水故事 + +```markdown +--- +title: Normalize names +> lib/foreign.mq.md +> lib/fs.mq.md +--- + +```python name=normalize +import sys +print(sys.stdin.read().strip().lower()) +``` + +# main + +*`raw` = > read_text path=names.txt * +*`clean` = > run name=normalize stdin=`raw` * +> print text=`clean` +``` + +中文轨: + +```markdown +--- +> lib/外联.mq.md +> lib/文件.mq.md +--- +``` + +叙述说明用中文;围栏内语言仍是 Python——**外联块语言 ≠ Marqdo API 语言**。 + +--- + +## 8. 与数学库的关系 + +- 厚 CAS(SymPy)**优先**走外联,而不是塞进默认 `lib/math`。 +- 官方可提供可选示例:`examples/math-sympy.mq.md`(要求 Python + `--allow-foreign`)。 +- 数值与 SVG 仍留在数学库,保证无 Python 时可教可演示。 + +--- + +## 9. 是否定为「标准库」的决策标准 + +纳入默认 `lib/foreign` 当且仅当: + +1. 权限模型在 CLI/view/CI 测全; +2. 至少一种语言金样例在 CI 稳定(或正式 `#[ignore]` 策略); +3. 文档明确「胶水能力默认关闭,不是网页 RCE」。 + +若短期内无法保证安全叙事 → 放在 `lib/experimental/foreign` 或 feature `foreign`,用户站不放可点击「运行外联」的按钮。 + +--- + +## 10. 实现分期 + +| 期 | 内容 | +|----|------| +| F0 | 词法:收集命名围栏 → 模块表(尚不执行) | +| F1 | `run` + Python 子进程 + 权限旗标 | +| F2 | `call` JSON 约定;超时与 cwd 锁 | +| F3 | Node;view 展示块与「需 CLI 权限」提示 | +| F4 | 可选嵌入运行时、与 math-cas 示例合流 | + +--- + +## 11. 一句话 + +**\`\`\`lang 是外联面的源,不是自动执行的陷阱;具名块 + 显式导入 + 默认拒绝权限,才能把 Marqdo 做成安全可讲的胶水语言。** diff --git a/doc/design/stdlib-i18n.md b/doc/design/stdlib-i18n.md index 0325211..62c5502 100644 --- a/doc/design/stdlib-i18n.md +++ b/doc/design/stdlib-i18n.md @@ -5,7 +5,7 @@ | 状态 | **草案(先文档、后实现)** | | 日期 | 2026-08-04 | | 原则 | **不指定语言**;靠**库文件名**区分中英(及日后其它语言) | -| 相关 | [stdlib.md](stdlib.md) · [keywords.md](keywords.md) · [keywords-i18n.md](keywords-i18n.md) · [user-site.md](user-site.md) | +| 相关 | [stdlib.md](stdlib.md) · [stdlib-modules.md](stdlib-modules.md) · [keywords.md](keywords.md) · [keywords-i18n.md](keywords-i18n.md) · [user-site.md](user-site.md) | --- @@ -76,12 +76,24 @@ --- +## 2.4 特例:JSON + +`JSON` 为专有缩写,**不强求**中文库名或中文 API 翻译。官方只提供: + +```text +lib/json.mq.md # 中英文档均 `> lib/json.mq.md`;函数 parse / stringify / get / keys +``` + +不设 `lib/数据.mq.md` 等平行文件。其余模块仍遵守 §2.1。详见 [stdlib-modules.md](stdlib-modules.md) §3.4。 + +--- + ## 3. 与「少而精内置」的边界 | 层 | 内容 | 如何获得 | |----|------|----------| | **内置(L0)** | 极少:`print` `input` `len` `str` `int`(及语言字面量关键字) | 直接调用,无需导入 | -| **标准库(L1)** | 文本/表等扩展 API;**中英各一套文件、各一套函数名** | frontmatter `> lib/…` | +| **标准库(L1)** | 文本/表等扩展 API;**通常**中英各一套文件、各一套函数名(**JSON 例外**:仅 `lib/json.mq.md`) | frontmatter `> lib/…` | | **宿主原语(实现细节)** | 若 `trim`/`split` 等暂由解释器实现 | 仅供标准库包装调用;**文档与用户站引导走 L1**,不鼓励当「关键字」堆砌 | 日后若某能力足够「核心」,可再升格为 L0;升格前先留在 L1。 @@ -92,11 +104,11 @@ ```text lib/ - text.mq.md # 英文文本库 - 文本.mq.md # 中文文本库 - table.mq.md # 英文表库 - 表.mq.md # 中文表库 - # 日后:texte.mq.md / テキスト.mq.md … + text.mq.md / 文本.mq.md + table.mq.md / 表.mq.md + # 本波:fs/文件 · sys/系统 · time/时间 · json(中英同文件)· net/网络 + # 暂缓:math/数学 · foreign/外联 + # 其它语言:texte.mq.md / テキスト.mq.md … ``` 扩展新语言时: @@ -111,9 +123,9 @@ lib/ ## 5. 文档与示例义务 -- 用户站:英文库、中文库各给一页(或同页两小节),导入路径与调用名并排出现。 -- 金样例:`tests/…` 中英导入至少各一条,避免只测中文或只测英文。 -- [keywords.md](keywords.md) 只列 L0;L1 指向本文 + [stdlib.md](stdlib.md)。 +- 用户站:英/中库各一页(或同页两小节),导入路径与调用名并排;**JSON** 可共用一页、同一导入。 +- 金样例:分文件模块中英导入至少各一条;JSON 测 `lib/json.mq.md` 即可。 +- [keywords.md](keywords.md) 只列 L0;L1 指向本文 + [stdlib.md](stdlib.md) + [stdlib-modules.md](stdlib-modules.md)。 --- @@ -131,4 +143,4 @@ lib/ ## 7. 一句话 -**标准库用文件名区分语言;英文库名进英文 API,中文库名进中文 API——导入即选择,无语言开关。** +**标准库用文件名区分语言(导入即选择);JSON 为缩写特例,中英共用 `lib/json.mq.md`——无语言开关。** diff --git a/doc/design/stdlib-math.md b/doc/design/stdlib-math.md new file mode 100644 index 0000000..91e9fb9 --- /dev/null +++ b/doc/design/stdlib-math.md @@ -0,0 +1,181 @@ +# 数学标准库(候选) + +| | | +|---|---| +| 状态 | **草案 / 暂缓**(本波不实现;五库之后再议) | +| 日期 | 2026-08-05 | +| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-i18n.md](stdlib-i18n.md) · [view.md](view.md) · [markdown-mapping.md](markdown-mapping.md) | +| 灵感 | Markdown `$$…$$` / `$…$` 公式面;文档即计算笔记本 | + +--- + +## 1. 为什么值得做 + +Markdown 读者已习惯用 `$$` 写公式。若 Marqdo 能: + +1. **认出**文档中的公式(或显式传入 LaTeX/ASCII-math 字符串); +2. **符号整理 / 求值 / 求解**; +3. 在 **`marqdo view` 里画出**简单图像; + +则同一份 `.mq.md` 既是讲义又是可运行实验,差异化远大于「再包一层 `sin`」。 + +风险同样大:CAS、数值稳定、渲染栈都会显著增加依赖与维护面。故标为**候选**:先定分层,允许只实现「数值 + 显式字符串」,再渐进接 `$$`。 + +--- + +## 2. 产品分层(建议) + +| 层 | 能力 | 依赖量 | 建议阶段 | +|----|------|--------|----------| +| **Math-N(数值)** | 四则、幂、根、三角函数、常数;列表上的 map 式计算 | 小(可纯 Rust) | 若纳入官方库,**先做这层** | +| **Math-S(符号)** | 化简、展开、求导、代入、解方程(单变元优先) | 中–大(自研子集或嵌 CAS) | 第二期 | +| **Math-P(作图)** | 把表达式/点列渲染为 SVG(或 PNG)嵌入 view | 中(SVG 即可) | 与 view 同期 | +| **Math-D(文档公式)** | 解析正文 `$$…$$`,命名后供调用 | 中(词法/源映射) | 第三期 | + +**默认发版建议:** 官方 `lib/math` 先只承诺 **Math-N**;S/P/D 放 `experimental` 或 feature `math-cas` / `math-plot`,避免「标准库」名不副实。 + +--- + +## 3. 导入与命名 + +| 导入 | API 语言 | +|------|----------| +| `> lib/math.mq.md` | 英文 | +| `> lib/数学.mq.md` | 中文 | + +宿主原语(L0.5)示例:`math_sin`、`math_eval`、`math_solve` —— 仅供库包装。 + +--- + +## 4. 用户 API 草图 + +### 4.1 数值(Math-N) + +| 英文 | 中文 | 说明 | +|------|------|------| +| `pi` / `e` | `圆周率` / `自然底数` | 无参,返回文本或「十进制文本」——**本波仍无 float 类型时用文本十进制**,或引入 `num` 宿主类型 | +| `add` `sub` `mul` `div` `pow` `sqrt` | `加` `减` `乘` `除` `幂` `根` | | +| `sin` `cos` `tan` `ln` `exp` | `正弦` `余弦` `正切` `对数` `指数` | 弧度 | +| `round` `floor` `ceil` | `四舍` `向下` `向上` | | +| `eval_num` | `求值` | `expr` 文本 → 数值文本 | + +**类型抉择(必须先 ADR):** + +| 选项 | 优点 | 缺点 | +|------|------|------| +| A. 继续只用 `int` + 十进制 `text` | 不碰 L0 | 慢、易错 | +| B. 新增宿主 `num`(十进制或 f64) | API 干净 | 类型与字节码要跟进 | +| C. 数学库内部不透明 `handle` | 隔离好 | 与 `print`/`json` 互通差 | + +倾向:**B(`num`)**,与 JSON 的非整数数字策略一并设计。 + +### 4.2 符号(Math-S) + +| 英文 | 中文 | 形参 | 结果 | +|------|------|------|------| +| `simplify` | `化简` | `expr` | 表达式文本(或 handle) | +| `expand` | `展开` | `expr` | 同上 | +| `diff` | `求导` | `expr`, `var` | 同上 | +| `subs` | `代入` | `expr`, `var`, `value` | 同上 | +| `solve` | `求解` | `expr`, `var` | 解列表(文本) | + +表达式互换格式(草案):**ASCII 优先**(`2*x^2 + 1`),LaTeX 作为可选输入 `format=latex`。 + +单变元多项式 / 简单超越方程为 v1 目标;多变元方程组、积分:**不做承诺**。 + +### 4.3 作图(Math-P) + +| 英文 | 中文 | 说明 | +|------|------|------| +| `plot_fn` | `绘函数` | `expr`, `var`, `min`, `max`, 可选 `steps` → **SVG 文本** | +| `plot_points` | `绘点列` | `xs`, `ys` → SVG 文本 | + +view 行为: + +- 若 stdout / 返回值为「带标记的 SVG」或约定 MIME,Execution 区**内嵌渲染**(非仅 `
`)。
+- 静态 `view output`:把 SVG 写入 HTML。
+- CLI:默认打印 SVG 文本;`--plot-file out.svg` 可选。
+
+不引入完整浏览器 Chart 框架;**SVG 路径足够**教微积分与拟合入门。
+
+### 4.4 文档公式面(Math-D)
+
+与 [markdown-mapping.md](markdown-mapping.md) 的衔接:
+
+| 现状 | 目标 |
+|------|------|
+| `$$` 多半落入叙述/未定义 | 可选:**命名公式块**可被引用 |
+
+建议语法(草案,需进 mapping 修订):
+
+```markdown
+$$:energy
+E = mc^2
+$$
+```
+
+或 frontmatter / 标题锚定:
+
+```markdown
+## energy
+$$
+E = mc^2
+$$
+```
+
+调用:
+
+```markdown
+---`
+> lib/math.mq.md
+---`
+
+*`e2` = > simplify expr=> formula name=energy *
+```
+
+更简单的 v1:**不解析正文 `$$`**,只接受:
+
+```markdown
+*`e2` = > simplify expr=E=mc^2 format=latex *
+```
+
+正文 `$$` 仍由 view 的 Markdown 渲染(KaTeX/MathJax)负责「好看」,计算走显式字符串——**降低词法耦合**,推荐作为第一刀。
+
+---
+
+## 5. 实现策略选项
+
+| 策略 | 说明 | 建议 |
+|------|------|------|
+| **纯 Rust 数值** | `libm` / 自写 | Math-N 必选 |
+| **嵌入轻量 CAS** | 如符号子集自研,或绑 `meval`/`fasteval` 仅数值 | 求值用 |
+| **外挂 SymPy(经外联库)** | 符号交给 Python | 与 [stdlib-foreign.md](stdlib-foreign.md) 合流;标准库变薄 |
+| **WASM CAS** | 可嵌入 view | 后期 |
+
+务实路径:**Math-N 自研 → Math-P SVG → Math-S 先外联 SymPy(可选)→ 再考虑内嵌**。这样「数学标准库」在官方包里可以很瘦,重能力走外联 feature。
+
+---
+
+## 6. 安全与性能
+
+- 表达式长度、求解迭代、绘图采样点设硬上限。
+- 禁止公式里跑任意宿主代码(与外联分离)。
+- view 中绘图同步、限时。
+
+---
+
+## 7. 是否定为「标准库」的决策标准
+
+纳入默认 `lib/math` 当且仅当:
+
+1. Math-N API 稳定且有中英金样例;
+2. 不强制下载数百 MB 依赖;
+3. 无外联时文档站示例仍可跑(纯数值 + 可选 SVG)。
+
+若符号/作图依赖 SymPy 或大型引擎 → 标 **`lib/math` = 数值**,符号示例放到 `examples/math-cas` 并要求 `--allow-foreign`。
+
+---
+
+## 8. 一句话
+
+**用 Markdown 的公式习惯服务「可计算文档」;官方数学库先数值与 SVG,符号与 `$$` 引用分期,必要时借外联而非做大内核。**
diff --git a/doc/design/stdlib-modules.md b/doc/design/stdlib-modules.md
new file mode 100644
index 0000000..302b848
--- /dev/null
+++ b/doc/design/stdlib-modules.md
@@ -0,0 +1,227 @@
+# 标准库下一波(L1 扩展模块)
+
+| | |
+|---|---|
+| 状态 | **本波已落地(M1–M5)**;HTTPS 与带 `/` 的裸路径字面量仍受限 |
+| 日期 | 2026-08-05 |
+| 本波范围 | **仅前五个库**:文件 / 系统 / 时间 / JSON / 网络 |
+| 暂缓 | 数学、外联(重型;详稿保留、不排期)— [stdlib-math.md](stdlib-math.md) · [stdlib-foreign.md](stdlib-foreign.md) |
+| 原则 | 全部经 frontmatter **导入**;除 JSON 外中英分文件;内核保持少而精 |
+| 相关 | [stdlib.md](stdlib.md) · [stdlib-i18n.md](stdlib-i18n.md) · [keywords-i18n.md](keywords-i18n.md) · [view.md](view.md) |
+
+---
+
+## 1. 目标
+
+在现有 `lib/text`·`lib/文本`、`lib/table`·`lib/表` 之上,把 Marqdo 推进到可写日常脚本。标准库**必须导入**才可用。
+
+| 模块族 | 英文库 | 中文库 | 本波 |
+|--------|--------|--------|------|
+| 文本(已有) | `lib/text.mq.md` | `lib/文本.mq.md` | 已有 |
+| 表(已有) | `lib/table.mq.md` | `lib/表.mq.md` | 已有 |
+| **文件** | `lib/fs.mq.md` | `lib/文件.mq.md` | **做** |
+| **系统** | `lib/sys.mq.md` | `lib/系统.mq.md` | **做** |
+| **时间** | `lib/time.mq.md` | `lib/时间.mq.md` | **做** |
+| **JSON** | `lib/json.mq.md` | **同文件(特例,§3.4)** | **做** |
+| **网络(简)** | `lib/net.mq.md` | `lib/网络.mq.md` | **做** |
+| 数学 | `lib/math.mq.md` | `lib/数学.mq.md` | **暂缓** |
+| 外联 | `lib/foreign.mq.md` | `lib/外联.mq.md` | **暂缓** |
+
+---
+
+## 2. 分层与实现分工
+
+```text
+用户 .mq.md
+ │ > lib/fs.mq.md
+ ▼
+L1 官方库(.mq.md)
+ │
+ ▼
+L0.5 宿主原语(Rust,英文蛇形)
+ │
+ ▼
+OS / HTTP / 时钟 / …
+```
+
+| 层 | 谁实现 | 用户是否直接调用 |
+|----|--------|------------------|
+| **L0** | 解释器内置 | 是(`print`/`len`/…) |
+| **L0.5 宿主原语** | Rust(`src/builtin` 或 `src/host/`) | **原则上否**;供 L1 包装;金样例可直测 |
+| **L1 官方库** | `lib/*.mq.md` | **是**(文档与用户站只教这一层) |
+
+规则:
+
+1. **导入即选择语言**(JSON 除外):`lib/fs.mq.md` → 英文 API;`lib/文件.mq.md` → 中文 API(见 [stdlib-i18n.md](stdlib-i18n.md))。
+2. **不设 `lang:`**。
+3. 宿主原语保持英文;中英差异只存在于 L1 包装层(JSON 无第二套包装)。
+4. 失败一律 `path:line:col: message`([stdlib.md](stdlib.md) §4)。
+
+---
+
+## 3. 核心模块 API 草图(L1)
+
+### 3.1 文件 — `fs` / `文件`
+
+| 英文 | 中文 | 形参(英 / 中) | 结果 |
+|------|------|-----------------|------|
+| `read_text` | `读文本` | `path` / `路径` | 文本 |
+| `write_text` | `写文本` | `path`, `text` / `路径`, `内容` | `None` |
+| `append_text` | `追加文本` | 同上 | `None` |
+| `exists` | `存在` | `path` / `路径` | 布尔 |
+| `list_dir` | `列目录` | `path` / `路径` | 文本列表 |
+| `make_dir` | `建目录` | `path` / `路径` | `None` |
+| `remove` | `删除` | `path` / `路径` | `None` |
+
+约定:路径相对工作目录或绝对路径;二进制 I/O 本波不做;写/删默认需 `--allow-fs-write`(§6)。
+
+### 3.2 系统 — `sys` / `系统`
+
+| 英文 | 中文 | 形参 | 结果 |
+|------|------|------|------|
+| `env_get` | `取环境` | `name` / `名` | 文本或 `None` |
+| `env_set` | `设环境` | `name`, `value` / `名`, `值` | `None` |
+| `args` | `参数表` | (无) | 文本列表 |
+| `cwd` | `工作目录` | (无) | 文本 |
+| `exit` | `退出` | `code` / `码` | 不返回 |
+| `exec` | `执行` | `cmd`, 可选 `args` | 退出码(实现时写死语义) |
+
+`exec` 默认关(`--allow-exec`);view / 静态站永不开放。
+
+### 3.3 时间 — `time` / `时间`
+
+| 英文 | 中文 | 形参 | 结果 |
+|------|------|------|------|
+| `now_unix` | `此刻秒` | (无) | 整数(Unix 秒) |
+| `now_ms` | `此刻毫秒` | (无) | 整数 |
+| `format` | `格式化` | `unix`, `pattern` / `秒`, `格式` | 文本 |
+| `sleep_ms` | `睡眠毫秒` | `ms` / `毫秒` | `None` |
+| `parse` | `解析时间` | `text`, `pattern` / `内容`, `格式` | 整数秒或诊断失败 |
+
+view 中 `sleep_ms` 设上限(如 5s)。
+
+### 3.4 JSON — `json`(**中英同库特例**)
+
+JSON 是专有缩写,**很难也不必要**做合规中文库名/API 翻译。本波定稿:
+
+| 项 | 约定 |
+|----|------|
+| 唯一路径 | **`lib/json.mq.md`**(中英文档均导入此路径) |
+| 函数名 | 国际通行英文:`parse` / `stringify` / `get` / `keys` |
+| 形参 | 英文:`text` / `value` / `key` / `indent` |
+| 不设 | `lib/数据.mq.md`、音译名、中文函数双份 |
+
+这是对 [stdlib-i18n.md](stdlib-i18n.md)「一概念两文件」的**显式例外**;其它模块仍中英分文件。
+
+| 函数 | 形参 | 结果 |
+|------|------|------|
+| `parse` | `text` | 值(见下) |
+| `stringify` | `value`, 可选 `indent` | JSON 文本 |
+| `get` | `value`, `key` | 值或 `None` |
+| `keys` | `value` | 文本列表 |
+
+**类型映射(草案)**:
+
+| JSON | Marqdo Value |
+|------|----------------|
+| `null` | `None` |
+| bool | bool |
+| number(整数可表) | int |
+| number(其余) | 文本(本波不引入 float)或诊断拒绝 |
+| string | text |
+| array | list |
+| object | 倾向新宿主类型 **`map`**(`type` → `map`);否则体验差 |
+
+`map` 为 L0.5 类型扩展,可与 json 同期或紧随;不阻塞 `fs`/`time` 先行。
+
+### 3.5 网络(简)— `net` / `网络`
+
+| 英文 | 中文 | 形参 | 结果 |
+|------|------|------|------|
+| `http_get` | `获取` | `url` / `地址` | 响应文本(或 map:status/body) |
+| `http_post` | `提交` | `url`, `body`, 可选 `content_type` | 同上 |
+| `url_encode` | `编码地址` | `text` / `内容` | 文本 |
+
+仅 **HTTP 明文**(HTTPS 本波未做,会诊断提示);短超时、响应体上限;默认需 `--allow-net`;view / 静态站默认关。
+
+**路径字面量:** 具名实参里 `path=a/b` 会被解析成除法。请用无斜杠文件名,或先赋给变量再传入。
+
+---
+
+## 4. 中英路径总表(本波)
+
+```text
+lib/
+ text.mq.md / 文本.mq.md # 已有
+ table.mq.md / 表.mq.md # 已有
+ fs.mq.md / 文件.mq.md # 本波
+ sys.mq.md / 系统.mq.md
+ time.mq.md / 时间.mq.md
+ json.mq.md # 本波;中英共用,无第二文件
+ net.mq.md / 网络.mq.md
+ # 暂缓:math / 数学 · foreign / 外联
+```
+
+别名:`std/…` ≡ `lib/…`。
+
+---
+
+## 5. 落地分期(本波 = M1–M5)
+
+| 期 | 内容 | 完成定义 |
+|----|------|----------|
+| **M1** | 宿主能力框架:权限旗标、`host` 分发、错误文案 | `--allow-*` 可测 |
+| **M2** | `fs` + `time`(只读 fs + 时钟) | 中英库 + 金样例 |
+| **M3** | `sys`(env/cwd/args;`exec` 默认关) | 同上 |
+| **M4** | `json`(+ 可选 `map`) | 往返金样例;唯 `lib/json.mq.md` |
+| **M5** | `net`(默认关) | 本地 mock 或录制夹具 |
+
+**不做 M6/M7**(数学 / 外联):详稿仅存档,待五库稳定后再议。
+
+文档站:`fs`/`sys`/`time`/`net` 英中各一页;`json` 可一页双语叙述、同一导入路径。
+
+---
+
+## 6. 安全与 view / 静态导出
+
+### 6.1 行为一致
+
+`marqdo run`、live `view`、`view output` 对标准库 **默认同一套能力**(读/写盘、HTTP、exec 均可用)。导入库即表示要用;不再要求 `--allow-*`。
+
+差异仅在 **软退出**:
+
+| | CLI `run` | view / capture / 静态导出 |
+|--|-----------|---------------------------|
+| `exit` | 结束进程 | 报诊断,不杀 view/构建进程 |
+| `sleep_ms` | 默认可睡(有上限) | live 有上限;导出通常为 0 |
+
+沙箱:相对路径落在源文件目录(或 view 根)下,防止 `..` 逃逸。
+
+### 6.2 静态部署
+
+访客浏览器 **不再执行** Marqdo;HTML 里是构建时冻结的输出。源码中的路径/URL 访客改不了、也触发不了新的 host 调用。审 PR 时审查写死的目标即可。
+
+勿在静态页嵌入「用户可改 URL 再请求」的浏览器脚本。
+
+---
+
+## 7. 与现有库的关系
+
+- `text` / `table` 继续纯包装、无 IO。
+- JSON `stringify` ≠ `str`(显示)。
+
+---
+
+## 8. 刻意不做(本波)
+
+- 数学库、外联/胶水库(及其依赖、权限旗标实现)。
+- 数据库、异步事件循环、WebSocket、原始 TCP。
+- float/复数进 L0。
+- `lang:` 或按 locale 自动选库。
+- 为 JSON 强造中文库名或中文 API 双份。
+
+---
+
+## 9. 一句话
+
+**本波只落地文件 / 系统 / 时间 / JSON / 网络;JSON 中英共用 `lib/json.mq.md`;数学与外联暂缓。**
diff --git a/doc/design/stdlib.md b/doc/design/stdlib.md
index d8e00ca..e71fa8e 100644
--- a/doc/design/stdlib.md
+++ b/doc/design/stdlib.md
@@ -4,10 +4,10 @@
|---|---|
| 状态 | **S0–S3 落地** |
| 日期 | 2026-08-04 |
-| 相关 | [keywords.md](keywords.md) · [call-arguments.md](call-arguments.md) · [stdlib-i18n.md](stdlib-i18n.md) · [roadmap/next-phase.md](../roadmap/next-phase.md) |
+| 相关 | [keywords.md](keywords.md) · [call-arguments.md](call-arguments.md) · [stdlib-i18n.md](stdlib-i18n.md) · [stdlib-modules.md](stdlib-modules.md) · [roadmap/next-phase.md](../roadmap/next-phase.md) |
-> **多语言库命名**已单独定稿方向:见 [stdlib-i18n.md](stdlib-i18n.md)。
-> 要点:不设 `lang:`;`lib/text.mq.md`(英文函数)与 `lib/文本.mq.md`(中文函数)分文件导入。下文 §3 的单轨中文示例将在实现阶段按该草案改掉。
+> **多语言库命名**:见 [stdlib-i18n.md](stdlib-i18n.md)(不设 `lang:`;中英分文件)。
+> **下一波模块(本波:文件 / 系统 / 时间 / JSON / 网络;数学·外联暂缓)**:见 [stdlib-modules.md](stdlib-modules.md)。
---
@@ -60,8 +60,17 @@ Frontmatter:
| 路径 | 导出函数 |
|------|----------|
-| `lib/text.mq.md` | `去空白` `拆分` `拼接` |
-| `lib/table.mq.md` | `行数` `取行` |
+| `lib/fs.mq.md` / `lib/文件.mq.md` | `read_text`… / `读文本`… |
+| `lib/time.mq.md` / `lib/时间.mq.md` | `now_unix`… / `此刻秒`… |
+| `lib/sys.mq.md` / `lib/系统.mq.md` | `env_get`… / `取环境`… |
+| `lib/json.mq.md` | `parse` `stringify` `get` `keys`(中英同文件) |
+| `lib/net.mq.md` / `lib/网络.mq.md` | `http_get`… / `获取`… |
+| `lib/text.mq.md` | `str_trim` `str_split` `str_join` |
+| `lib/文本.mq.md` | `去空白` `拆分` `拼接` |
+| `lib/table.mq.md` | `rows` `row_at` |
+| `lib/表.mq.md` | `行数` `取行` |
+
+规划中的 L1 扩展见 [stdlib-modules.md](stdlib-modules.md)。
---
diff --git a/doc/design/view.md b/doc/design/view.md
index 0f4ef2e..7f7e39e 100644
--- a/doc/design/view.md
+++ b/doc/design/view.md
@@ -75,6 +75,7 @@ OUT_DIR/
- 页内链接一律**相对路径**,可用任意静态服务器或 `file://`(同目录结构下)打开。
- 用户文档推荐流程:`marqdo view output public -o public`,将生成物发布到 `gh-pages`(见 [user-site.md](user-site.md))。
+- **执行权限**:与 `marqdo run` 一致(导入即用);view/导出仅对 `exit`/`sleep` 做软化,避免拖垮进程。详见 [stdlib-modules.md](stdlib-modules.md) §6。
- 金样例浏览仍可用:`marqdo view output tests -o /tmp/mq-tests`(含 errors,勿当对外用户站)。
- 渲染逻辑与实时 `view` **共用**同一套 HTML 构件(结构 / 执行 / 源码),禁止两套皮肤分叉。
diff --git a/doc/roadmap/next-phase.md b/doc/roadmap/next-phase.md
index 86a7dce..c75f170 100644
--- a/doc/roadmap/next-phase.md
+++ b/doc/roadmap/next-phase.md
@@ -17,7 +17,7 @@
| **`input`** | CLI 双后端 + `--stdin-file`;frontmatter `stdin:`/`输入:`;live view 表单覆盖;无预置时 capture 提示补线 | **P1a + P1b 完成** |
| **诊断** | 语句级 `path:line:col: message`;字节码指令带 `spans`;errors 金样例双后端断言位置 | **P0 完成** |
| **view** | 结构 + 一次执行 + 源码;注释已 Markdown 渲染;无暂停/断点 | **文档浏览器,不是调试器** |
-| **标准库** | S0–S3:`len`/`str`/`int`/`type`/`trim`/`split`/`join`/`at` + 官方 `lib/` | **P2 完成** |
+| **标准库** | S0–S3 完成;本波扩展 = 文件/系统/时间/JSON/网络([stdlib-modules.md](../design/stdlib-modules.md));数学/外联暂缓 | **P2 完成;五库扩展设计中** |
| **模块** | `> file.mq.md` 顶层函数合并,无命名空间 | 短期可继续用 |
用户点名的三件事都对,但**不能并行硬开**:断点调试依赖「可信位置 + 可暂停执行」;标准库依赖稳定运行时与 I/O;`input` 在 CLI 与 view 是两条路径。
diff --git a/lib/fs.mq.md b/lib/fs.mq.md
new file mode 100644
index 0000000..c7baaa3
--- /dev/null
+++ b/lib/fs.mq.md
@@ -0,0 +1,41 @@
+---
+title: lib/fs
+description: English filesystem wrappers
+---
+
+# read_text
+ - path
+
+**> host_read_text path=`path`**
+
+# write_text
+ - path
+ - text
+
+**> host_write_text path=`path` text=`text`**
+
+# append_text
+ - path
+ - text
+
+**> host_append_text path=`path` text=`text`**
+
+# exists
+ - path
+
+**> host_exists path=`path`**
+
+# list_dir
+ - path
+
+**> host_list_dir path=`path`**
+
+# make_dir
+ - path
+
+**> host_make_dir path=`path`**
+
+# remove
+ - path
+
+**> host_remove path=`path`**
diff --git a/lib/json.mq.md b/lib/json.mq.md
new file mode 100644
index 0000000..427a485
--- /dev/null
+++ b/lib/json.mq.md
@@ -0,0 +1,25 @@
+---
+title: lib/json
+description: JSON parse/stringify (shared EN/ZH import)
+---
+
+# parse
+ - text
+
+**> host_json_parse text=`text`**
+
+# stringify
+ - value
+
+**> host_json_stringify value=`value`**
+
+# get
+ - value
+ - key
+
+**> host_json_get value=`value` key=`key`**
+
+# keys
+ - value
+
+**> host_json_keys value=`value`**
diff --git a/lib/net.mq.md b/lib/net.mq.md
new file mode 100644
index 0000000..c4e93e6
--- /dev/null
+++ b/lib/net.mq.md
@@ -0,0 +1,20 @@
+---
+title: lib/net
+description: English minimal HTTP wrappers
+---
+
+# http_get
+ - url
+
+**> host_http_get url=`url`**
+
+# http_post
+ - url
+ - body
+
+**> host_http_post url=`url` body=`body`**
+
+# url_encode
+ - text
+
+**> host_url_encode text=`text`**
diff --git a/lib/sys.mq.md b/lib/sys.mq.md
new file mode 100644
index 0000000..213e132
--- /dev/null
+++ b/lib/sys.mq.md
@@ -0,0 +1,33 @@
+---
+title: lib/sys
+description: English system wrappers
+---
+
+# env_get
+ - name
+
+**> host_env_get name=`name`**
+
+# env_set
+ - name
+ - value
+
+**> host_env_set name=`name` value=`value`**
+
+# args
+
+**> host_args**
+
+# cwd
+
+**> host_cwd**
+
+# exit
+ - code
+
+**> host_exit code=`code`**
+
+# exec
+ - cmd
+
+**> host_exec cmd=`cmd`**
diff --git a/lib/time.mq.md b/lib/time.mq.md
new file mode 100644
index 0000000..8c89b98
--- /dev/null
+++ b/lib/time.mq.md
@@ -0,0 +1,29 @@
+---
+title: lib/time
+description: English time wrappers
+---
+
+# now_unix
+
+**> host_now_unix**
+
+# now_ms
+
+**> host_now_ms**
+
+# format
+ - unix
+ - pattern
+
+**> host_format_time unix=`unix` pattern=`pattern`**
+
+# sleep_ms
+ - ms
+
+**> host_sleep_ms ms=`ms`**
+
+# parse
+ - text
+ - pattern
+
+**> host_parse_time text=`text` pattern=`pattern`**
diff --git a/lib/文件.mq.md b/lib/文件.mq.md
new file mode 100644
index 0000000..d779edb
--- /dev/null
+++ b/lib/文件.mq.md
@@ -0,0 +1,41 @@
+---
+title: lib/文件
+description: 中文文件系统包装
+---
+
+# 读文本
+ - 路径
+
+**> host_read_text path=`路径`**
+
+# 写文本
+ - 路径
+ - 内容
+
+**> host_write_text path=`路径` text=`内容`**
+
+# 追加文本
+ - 路径
+ - 内容
+
+**> host_append_text path=`路径` text=`内容`**
+
+# 存在
+ - 路径
+
+**> host_exists path=`路径`**
+
+# 列目录
+ - 路径
+
+**> host_list_dir path=`路径`**
+
+# 建目录
+ - 路径
+
+**> host_make_dir path=`路径`**
+
+# 删除
+ - 路径
+
+**> host_remove path=`路径`**
diff --git a/lib/时间.mq.md b/lib/时间.mq.md
new file mode 100644
index 0000000..93d3071
--- /dev/null
+++ b/lib/时间.mq.md
@@ -0,0 +1,29 @@
+---
+title: lib/时间
+description: 中文时间包装
+---
+
+# 此刻秒
+
+**> host_now_unix**
+
+# 此刻毫秒
+
+**> host_now_ms**
+
+# 格式化
+ - 秒
+ - 格式
+
+**> host_format_time unix=`秒` pattern=`格式`**
+
+# 睡眠毫秒
+ - 毫秒
+
+**> host_sleep_ms ms=`毫秒`**
+
+# 解析时间
+ - 内容
+ - 格式
+
+**> host_parse_time text=`内容` pattern=`格式`**
diff --git a/lib/系统.mq.md b/lib/系统.mq.md
new file mode 100644
index 0000000..cf695dd
--- /dev/null
+++ b/lib/系统.mq.md
@@ -0,0 +1,33 @@
+---
+title: lib/系统
+description: 中文系统包装
+---
+
+# 取环境
+ - 名
+
+**> host_env_get name=`名`**
+
+# 设环境
+ - 名
+ - 值
+
+**> host_env_set name=`名` value=`值`**
+
+# 参数表
+
+**> host_args**
+
+# 工作目录
+
+**> host_cwd**
+
+# 退出
+ - 码
+
+**> host_exit code=`码`**
+
+# 执行
+ - 命令
+
+**> host_exec cmd=`命令`**
diff --git a/lib/网络.mq.md b/lib/网络.mq.md
new file mode 100644
index 0000000..af79c2b
--- /dev/null
+++ b/lib/网络.mq.md
@@ -0,0 +1,20 @@
+---
+title: lib/网络
+description: 中文简易网络包装
+---
+
+# 获取
+ - 地址
+
+**> host_http_get url=`地址`**
+
+# 提交
+ - 地址
+ - 内容
+
+**> host_http_post url=`地址` body=`内容`**
+
+# 编码地址
+ - 内容
+
+**> host_url_encode text=`内容`**
diff --git a/public/00-welcome.mq.md b/public/00-welcome.mq.md
index cd99688..094948c 100644
--- a/public/00-welcome.mq.md
+++ b/public/00-welcome.mq.md
@@ -9,7 +9,7 @@ Hi — thanks for opening this site. Marqdo is a language where **code is docume
AI already prefers Markdown. Marqdo asks: why keep docs and code as two worlds? A `.mq.md` file is both. The longer ambition includes OKF-style knowledge YAML and more; for now the focus is a solid interpreter and this site (yes — generated by Marqdo itself).
-The language is young. You get structure markers, a small bilingual core (`print` / `打印`, …), optional stdlib files (`lib/text.mq.md` vs `lib/文本.mq.md`), local `view`, and static export. Contribute on [GitHub](https://github.com/cflmy/marqdo).
+The language is young. You get structure markers, a small bilingual core (`print` / `打印`, …), optional stdlib files under `lib/` (see [`stdlib/`](stdlib/) on this site), local `view`, and static export. Contribute on [GitHub](https://github.com/cflmy/marqdo).
中文文档请看同目录的 [`00-欢迎.mq.md`](00-欢迎.mq.md)(叙述与内置均用中文)。
diff --git a/public/00-欢迎.mq.md b/public/00-欢迎.mq.md
index 54caf97..ffc2b71 100644
--- a/public/00-欢迎.mq.md
+++ b/public/00-欢迎.mq.md
@@ -9,7 +9,7 @@ description: 用户文档首页 — 代码即文档(中文版)
AI 输出本就偏爱 Markdown。作者的念头是:何必再把文档和代码拆成两套?`.mq.md` 双后缀保证它仍是合法 Markdown。更长远的目标包括 OKF 式知识清单等;眼下先把解释器与本站做好——对,这个站点就是 Marqdo 生成的。
-语言仍在起步:结构标记、中英内核双名(`打印` / `print` …)、可导入的标准库(`lib/文本.mq.md` 与 `lib/text.mq.md`)、本地 `view` 与静态导出。欢迎到 [GitHub](https://github.com/cflmy/marqdo) 一起做。
+语言仍在起步:结构标记、中英内核双名(`打印` / `print` …)、可导入的标准库(见本站 [`stdlib/`](stdlib/))、本地 `view` 与静态导出。欢迎到 [GitHub](https://github.com/cflmy/marqdo) 一起做。
English docs: [`00-welcome.mq.md`](00-welcome.mq.md) (English prose and English builtins).
diff --git a/public/README.md b/public/README.md
index 5a2bd7b..f1d8264 100644
--- a/public/README.md
+++ b/public/README.md
@@ -2,28 +2,26 @@
本目录即面向访客的 Marqdo 介绍:每个 `.mq.md` 既是文稿也能 `marqdo run`,并随仓库 / 静态站一起下载。
-**双语约定:** 拉丁文件名 → 英文叙述与英文内置;中文文件名 → 中文叙述与中文编程(`打印`、`长度` …)。成对放在同一目录(如 `structure/01-hello.mq.md` 与 `structure/01-你好.mq.md`)。标准库按路径选 API:`lib/text.mq.md` vs `lib/文本.mq.md`。
+**双语约定:** 拉丁文件名 → 英文叙述与英文内置;中文文件名 → 中文叙述与中文编程。成对放在同一目录。标准库:拉丁路径用英文 API,中文路径用中文 API;JSON 仅 `lib/json.mq.md`。
| 路径 | 内容 |
|------|------|
| [`00-welcome.mq.md`](00-welcome.mq.md) / [`00-欢迎.mq.md`](00-欢迎.mq.md) | 首页(英 / 中) |
-| [`structure/`](structure/) | 基本结构(英 / 中并列) |
-| [`keywords/`](keywords/) | 关键字与内置(英 / 中并列) |
-| [`features/`](features/) | 特性迭代(英 / 中并列) |
-| [`lib-import.mq.md`](lib-import.mq.md) / [`lib-导入.mq.md`](lib-导入.mq.md) | 导入 `lib/text` / `lib/文本` |
+| [`structure/`](structure/) | 基本结构 |
+| [`keywords/`](keywords/) | 关键字与 L0 内置 |
+| [`stdlib/`](stdlib/) | **标准库**(导入方式 + text/表/文件/时间/系统/json/网络) |
+| [`features/`](features/) | 特性迭代 |
+| [`lib-import.mq.md`](lib-import.mq.md) / [`lib-导入.mq.md`](lib-导入.mq.md) | 快速导入示例(text) |
-**不放** `errors/`:失败样例只在 `tests/errors/`,避免用户站出现红色执行失败。
+**不放** `errors/`:失败样例只在 `tests/errors/`。
-开发文档(语言设计等)在 [`doc/`](../doc/),与本目录分离。
+开发文档在 [`doc/`](../doc/)。
## 浏览与生成 HTML
```bash
cargo run -- view public
cargo run -- view output public -o public
-# 或
-./scripts/build-public.sh
-powershell -File ./scripts/build-public.ps1
```
-生成的 `index.html` 与 `pages/` 默认被 ignore;CI 构建后推到 `gh-pages`。详见 [user-site.md](../doc/design/user-site.md)。
+详见 [user-site.md](../doc/design/user-site.md)。
diff --git a/public/stdlib/00-overview.mq.md b/public/stdlib/00-overview.mq.md
new file mode 100644
index 0000000..e968588
--- /dev/null
+++ b/public/stdlib/00-overview.mq.md
@@ -0,0 +1,18 @@
+---
+title: Standard library — overview
+description: How to import official lib modules
+---
+
+# main
+
+Official libraries live under lib/ (alias std/). Import them in YAML frontmatter with a greater-than line, for example lib/text.mq.md or lib/fs.mq.md.
+
+English-named files export English APIs; Chinese-named files export Chinese APIs. JSON is special: only lib/json.mq.md (shared by both languages).
+
+No extra allow flags: importing a module means you intend to use it. Under marqdo view or static export, exit soft-fails and long sleeps are clamped so the console stays up.
+
+Modules: text (text / 文本), table (table / 表), files (fs / 文件), time (time / 时间), system (sys / 系统), json (json only), net (net / 网络).
+
+Sibling pages in this folder document each module. Chinese overview: 00-索引.mq.md.
+
+> print text=stdlib overview ok
diff --git a/public/stdlib/00-索引.mq.md b/public/stdlib/00-索引.mq.md
new file mode 100644
index 0000000..e36ebef
--- /dev/null
+++ b/public/stdlib/00-索引.mq.md
@@ -0,0 +1,18 @@
+---
+title: 标准库 — 总览
+description: 如何导入官方 lib 模块
+---
+
+# main
+
+官方库在仓库 lib/(别名 std/)。在 YAML frontmatter 用大于号行导入,例如 lib/文本.mq.md 或 lib/文件.mq.md。
+
+拉丁文件名导出英文 API;中文文件名导出中文 API。JSON 特例:只有 lib/json.mq.md(中英共用)。
+
+导入即表示要用对应能力,无需再加允许旗标。marqdo view 或静态导出里,退出会软失败、长睡眠会被钳制,以免拖垮控制台。
+
+模块:文本(text / 文本)、表(table / 表)、文件(fs / 文件)、时间(time / 时间)、系统(sys / 系统)、json(仅 json)、网络(net / 网络)。
+
+各模块说明见本目录其它页。English: 00-overview.mq.md.
+
+> 打印 内容=标准库总览就绪
diff --git a/public/stdlib/fs.mq.md b/public/stdlib/fs.mq.md
new file mode 100644
index 0000000..f9ad20d
--- /dev/null
+++ b/public/stdlib/fs.mq.md
@@ -0,0 +1,18 @@
+---
+title: lib/fs — files
+description: Read and write text under the sandbox
+> lib/fs.mq.md
+---
+
+# main
+
+Import lib/fs.mq.md. Functions: read_text, write_text, append_text, exists, list_dir, make_dir, remove (path / text params).
+
+Bare path words must not contain a slash character (parsed as division). Prefer a same-folder name or a variable.
+
+*`ok` = > exists path=demo.txt *
+
++ `ok`
+ > print text=demo-present
++ *
+ > print text=demo-missing
diff --git a/public/stdlib/json.mq.md b/public/stdlib/json.mq.md
new file mode 100644
index 0000000..fff8c93
--- /dev/null
+++ b/public/stdlib/json.mq.md
@@ -0,0 +1,19 @@
+---
+title: lib/json — JSON
+description: Shared EN/ZH path; parse and stringify
+> lib/json.mq.md
+---
+
+# main
+
+Import lib/json.mq.md from both English and Chinese docs (no translated twin). Functions: parse(text), stringify(value), get(value, key), keys(value). Objects become the map runtime type.
+
+*`obj` = > parse text={} *
+
+*`ty` = > type `obj` *
+
+> print text=`ty`
+
+*`out` = > stringify value=`obj` *
+
+> print text=`out`
diff --git a/public/stdlib/net.mq.md b/public/stdlib/net.mq.md
new file mode 100644
index 0000000..e1a6e8f
--- /dev/null
+++ b/public/stdlib/net.mq.md
@@ -0,0 +1,13 @@
+---
+title: lib/net — HTTP
+description: Minimal HTTP client and URL encode
+> lib/net.mq.md
+---
+
+# main
+
+Import lib/net.mq.md. Functions: http_get(url) returns map status/body, http_post(url, body), url_encode(text). v1 speaks cleartext http only.
+
+*`e` = > url_encode text=hello world *
+
+> print text=`e`
diff --git a/public/stdlib/sys.mq.md b/public/stdlib/sys.mq.md
new file mode 100644
index 0000000..a7f15e6
--- /dev/null
+++ b/public/stdlib/sys.mq.md
@@ -0,0 +1,18 @@
+---
+title: lib/sys — process
+description: Env, cwd, args, exit, exec
+> lib/sys.mq.md
+---
+
+# main
+
+Import lib/sys.mq.md. Functions: env_get, env_set, args, cwd, exit(code), exec(cmd). Under view, exit soft-fails instead of killing the process.
+
+*`d` = > cwd *
+
+*`n` = > len `d` *
+
++ `n` > 0
+ > print text=cwd-ok
++ *
+ > print text=cwd-empty
diff --git a/public/stdlib/table.mq.md b/public/stdlib/table.mq.md
new file mode 100644
index 0000000..4cb981d
--- /dev/null
+++ b/public/stdlib/table.mq.md
@@ -0,0 +1,24 @@
+---
+title: lib/table — lists
+description: Row count and index helpers
+> lib/table.mq.md
+---
+
+# main
+
+Import lib/table.mq.md. Functions: rows(xs), row_at(xs, i). Single-column Markdown tables are lists at runtime.
+
+`xs` =
+
+| v |
+|---|
+| a |
+| b |
+
+*`n` = > rows xs=`xs`*
+
+> print text=`n`
+
+*`r` = > row_at xs=`xs` i=0*
+
+> print text=`r`
diff --git a/public/stdlib/text.mq.md b/public/stdlib/text.mq.md
new file mode 100644
index 0000000..384707c
--- /dev/null
+++ b/public/stdlib/text.mq.md
@@ -0,0 +1,19 @@
+---
+title: lib/text — strings
+description: Trim, split, join wrappers
+> lib/text.mq.md
+---
+
+# main
+
+Import lib/text.mq.md. Functions: str_trim(s), str_split(s, sep), str_join(xs, sep).
+
+*`t` = > str_trim s= marqdo *
+
+> print text=`t`
+
+*`parts` = > str_split s=a,b,c sep=,*
+
+*`j` = > str_join xs=`parts` sep=-*
+
+> print text=`j`
diff --git a/public/stdlib/time.mq.md b/public/stdlib/time.mq.md
new file mode 100644
index 0000000..682407b
--- /dev/null
+++ b/public/stdlib/time.mq.md
@@ -0,0 +1,19 @@
+---
+title: lib/time — clock
+description: Unix time, format, parse, sleep
+> lib/time.mq.md
+---
+
+# main
+
+Import lib/time.mq.md. Functions: now_unix, now_ms, format(unix, pattern), parse(text, pattern), sleep_ms(ms). Patterns use strftime.
+
+*`s` = > format unix=0 pattern=%Y-%m-%d *
+
+> print text=`s`
+
+*`u` = > parse text=1970-01-01 00:00:00 pattern=%Y-%m-%d %H:%M:%S *
+
+> print text=`u`
+
+> sleep_ms ms=0
diff --git a/public/stdlib/文件.mq.md b/public/stdlib/文件.mq.md
new file mode 100644
index 0000000..bb529e1
--- /dev/null
+++ b/public/stdlib/文件.mq.md
@@ -0,0 +1,18 @@
+---
+title: lib/文件 — 文件系统
+description: 沙箱内读写文本
+> lib/文件.mq.md
+---
+
+# main
+
+导入 lib/文件.mq.md。函数:读文本、写文本、追加文本、存在、列目录、建目录、删除。
+
+裸路径字面量不要写斜杠(会被当成除法)。可用同目录文件名或变量。
+
+*`ok` = > 存在 路径=demo.txt *
+
++ `ok`
+ > 打印 内容=有演示文件
++ *
+ > 打印 内容=无演示文件
diff --git a/public/stdlib/文本.mq.md b/public/stdlib/文本.mq.md
new file mode 100644
index 0000000..14e0f53
--- /dev/null
+++ b/public/stdlib/文本.mq.md
@@ -0,0 +1,19 @@
+---
+title: lib/文本 — 字符串
+description: 去空白、拆分、拼接
+> lib/文本.mq.md
+---
+
+# main
+
+导入 lib/文本.mq.md。函数:去空白(s)、拆分(s, sep)、拼接(xs, sep)。
+
+*`t` = > 去空白 s= marqdo *
+
+> 打印 内容=`t`
+
+*`parts` = > 拆分 s=甲,乙,丙 sep=,*
+
+*`j` = > 拼接 xs=`parts` sep=-*
+
+> 打印 内容=`j`
diff --git a/public/stdlib/时间.mq.md b/public/stdlib/时间.mq.md
new file mode 100644
index 0000000..100fb0c
--- /dev/null
+++ b/public/stdlib/时间.mq.md
@@ -0,0 +1,19 @@
+---
+title: lib/时间 — 时钟
+description: Unix 时间、格式化、解析、睡眠
+> lib/时间.mq.md
+---
+
+# main
+
+导入 lib/时间.mq.md。函数:此刻秒、此刻毫秒、格式化(秒, 格式)、解析时间(内容, 格式)、睡眠毫秒(毫秒)。格式为 strftime。
+
+*`s` = > 格式化 秒=0 格式=%Y-%m-%d *
+
+> 打印 内容=`s`
+
+*`u` = > 解析时间 内容=1970-01-01 00:00:00 格式=%Y-%m-%d %H:%M:%S *
+
+> 打印 内容=`u`
+
+> 睡眠毫秒 毫秒=0
diff --git a/public/stdlib/系统.mq.md b/public/stdlib/系统.mq.md
new file mode 100644
index 0000000..b9c46ba
--- /dev/null
+++ b/public/stdlib/系统.mq.md
@@ -0,0 +1,18 @@
+---
+title: lib/系统 — 进程
+description: 环境变量、工作目录、参数、退出、执行
+> lib/系统.mq.md
+---
+
+# main
+
+导入 lib/系统.mq.md。函数:取环境、设环境、参数表、工作目录、退出(码)、执行(命令)。view 下退出会软失败,不结束进程。
+
+*`d` = > 工作目录 *
+
+*`n` = > 长度 值=`d` *
+
++ `n` > 0
+ > 打印 内容=工作目录就绪
++ *
+ > 打印 内容=工作目录空
diff --git a/public/stdlib/网络.mq.md b/public/stdlib/网络.mq.md
new file mode 100644
index 0000000..b9f89f4
--- /dev/null
+++ b/public/stdlib/网络.mq.md
@@ -0,0 +1,13 @@
+---
+title: lib/网络 — HTTP
+description: 简易 HTTP 与地址编码
+> lib/网络.mq.md
+---
+
+# main
+
+导入 lib/网络.mq.md。函数:获取(地址) 返回 map status/body、提交(地址, 内容)、编码地址(内容)。本波仅明文 http。
+
+*`e` = > 编码地址 内容=你好 *
+
+> 打印 内容=`e`
diff --git a/public/stdlib/表.mq.md b/public/stdlib/表.mq.md
new file mode 100644
index 0000000..ee67637
--- /dev/null
+++ b/public/stdlib/表.mq.md
@@ -0,0 +1,24 @@
+---
+title: lib/表 — 列表
+description: 行数与取行
+> lib/表.mq.md
+---
+
+# main
+
+导入 lib/表.mq.md。函数:行数(xs)、取行(xs, i)。单列表在运行时是列表。
+
+`xs` =
+
+| v |
+|---|
+| 甲 |
+| 乙 |
+
+*`n` = > 行数 xs=`xs`*
+
+> 打印 内容=`n`
+
+*`r` = > 取行 xs=`xs` i=0*
+
+> 打印 内容=`r`
diff --git a/src/aliases.rs b/src/aliases.rs
index b733b1d..617568f 100644
--- a/src/aliases.rs
+++ b/src/aliases.rs
@@ -22,6 +22,9 @@ pub fn is_reserved_keyword(name: &str) -> bool {
/// Map a builtin callee (EN or ZH alias) to its English canonical name.
/// Host primitives without ZH L0 aliases only match English.
pub fn canonical_builtin(name: &str) -> Option<&'static str> {
+ if let Some(h) = crate::host::HostFn::from_name(name) {
+ return Some(h.name());
+ }
match name {
"print" | "打印" => Some("print"),
"input" | "输入" => Some("input"),
diff --git a/src/builtin.rs b/src/builtin.rs
index cb905e6..6db2507 100644
--- a/src/builtin.rs
+++ b/src/builtin.rs
@@ -31,7 +31,7 @@ pub fn builtin_int(v: &Value) -> Result {
}
}
-/// `type`: type tag as text (`none` / `bool` / `int` / `text` / `list`).
+/// `type`: type tag as text (`none` / `bool` / `int` / `text` / `list` / `map`).
pub fn builtin_type(v: &Value) -> Value {
Value::Text(
match v {
@@ -40,6 +40,7 @@ pub fn builtin_type(v: &Value) -> Value {
Value::Int(_) => "int",
Value::Text(_) => "text",
Value::List(_) => "list",
+ Value::Map(_) => "map",
}
.into(),
)
diff --git a/src/bytecode/compile.rs b/src/bytecode/compile.rs
index c2596ec..0dd30c2 100644
--- a/src/bytecode/compile.rs
+++ b/src/bytecode/compile.rs
@@ -427,6 +427,45 @@ impl<'a> FnCompiler<'a> {
}
return Ok(());
}
+ other if crate::host::HostFn::from_name(other).is_some() => {
+ let hf = crate::host::HostFn::from_name(other).unwrap();
+ let params = hf.all_params();
+ let mut named: HashMap = HashMap::new();
+ let mut positionals = Vec::new();
+ for a in &call.args {
+ match a {
+ Arg::Positional(e) => positionals.push(e),
+ Arg::Named { name, value } => {
+ named.insert(name.clone(), value);
+ }
+ }
+ }
+ let mut pos_i = 0usize;
+ let required_n = hf.required_params().len();
+ for (i, p) in params.iter().enumerate() {
+ if let Some(e) = named.get(*p) {
+ self.compile_expr(e)?;
+ } else if pos_i < positionals.len() {
+ self.compile_expr(positionals[pos_i])?;
+ pos_i += 1;
+ } else if i < required_n {
+ return Err(self.err(format!("{} requires `{p}`", hf.name())));
+ } else {
+ self.emit(Op::None_);
+ }
+ }
+ if pos_i < positionals.len() {
+ return Err(self.err(format!(
+ "too many positional arguments ({} extra)",
+ positionals.len() - pos_i
+ )));
+ }
+ self.emit(Op::HostCall(hf.as_u16(), params.len() as u8));
+ if as_stmt {
+ self.emit(Op::Pop);
+ }
+ return Ok(());
+ }
_ => {}
}
diff --git a/src/bytecode/mod.rs b/src/bytecode/mod.rs
index ab83274..0cfaf59 100644
--- a/src/bytecode/mod.rs
+++ b/src/bytecode/mod.rs
@@ -54,6 +54,8 @@ pub enum Op {
GetIndex,
/// Call function by index; argc values are on the stack (param order).
Call(u16, u8),
+ /// Host primitive: pop `argc` args (param order), push result.
+ HostCall(u16, u8),
Return,
}
diff --git a/src/bytecode/vm.rs b/src/bytecode/vm.rs
index e8e1e51..03804a8 100644
--- a/src/bytecode/vm.rs
+++ b/src/bytecode/vm.rs
@@ -8,11 +8,13 @@ use crate::builtin::{
builtin_at, builtin_int, builtin_join, builtin_len, builtin_split, builtin_str, builtin_trim,
builtin_type,
};
+use crate::host::{call_host, HostContext, HostFn};
use crate::bytecode::{Op, Program};
use crate::debug::emit_trace;
use crate::diagnostics::{bail_at, Span};
use crate::input_feed::InputFeed;
use crate::value::Value;
+use std::collections::HashMap;
pub struct Vm {
path: Option,
@@ -20,6 +22,7 @@ pub struct Vm {
pub captured_stdout: String,
input: InputFeed,
trace: bool,
+ host: HostContext,
}
struct Frame {
@@ -36,6 +39,7 @@ impl Vm {
captured_stdout: String::new(),
input: InputFeed::new(false, Vec::new()),
trace: false,
+ host: HostContext::for_run(path, Default::default(), Vec::new()),
}
}
@@ -46,6 +50,7 @@ impl Vm {
captured_stdout: String::new(),
input: InputFeed::new(true, Vec::new()),
trace: false,
+ host: HostContext::for_capture(path, Default::default()),
}
}
@@ -59,6 +64,11 @@ impl Vm {
self
}
+ pub fn with_host(mut self, host: HostContext) -> Self {
+ self.host = host;
+ self
+ }
+
fn emit_line(&mut self, text: &str) {
if self.capture {
self.captured_stdout.push_str(text);
@@ -276,6 +286,35 @@ impl Vm {
let list = pop(&mut stack).map_err(|m| self.err_at(span, m))?;
stack.push(builtin_at(&list, &idx).map_err(|m| self.err_at(span, m))?);
}
+ Op::HostCall(id, argc) => {
+ let hf = HostFn::from_u16(id)
+ .ok_or_else(|| self.err_at(span, format!("unknown host id {id}")))?;
+ let argc = argc as usize;
+ let params = hf.all_params();
+ if params.len() != argc {
+ return Err(self.err_at(span, "host call argc mismatch"));
+ }
+ let mut vals = Vec::with_capacity(argc);
+ for _ in 0..argc {
+ vals.push(pop(&mut stack).map_err(|m| self.err_at(span, m))?);
+ }
+ vals.reverse();
+ let mut bound = HashMap::new();
+ for (p, v) in params.iter().zip(vals.into_iter()) {
+ bound.insert((*p).to_string(), v);
+ }
+ for req in hf.required_params() {
+ if !bound.contains_key(*req) {
+ return Err(self.err_at(
+ span,
+ format!("{} requires `{req}`", hf.name()),
+ ));
+ }
+ }
+ let result =
+ call_host(&self.host, hf, &bound).map_err(|m| self.err_at(span, m))?;
+ stack.push(result);
+ }
Op::Call(fid, argc) => {
let fid = fid as usize;
let argc = argc as usize;
diff --git a/src/host/dispatch.rs b/src/host/dispatch.rs
new file mode 100644
index 0000000..e1fb06e
--- /dev/null
+++ b/src/host/dispatch.rs
@@ -0,0 +1,227 @@
+//! Host function registry and dispatch.
+
+use std::collections::HashMap;
+
+use crate::host::{fs, json, net, sys, time, HostContext};
+use crate::value::Value;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[repr(u16)]
+pub enum HostFn {
+ ReadText = 1,
+ WriteText = 2,
+ AppendText = 3,
+ Exists = 4,
+ ListDir = 5,
+ MakeDir = 6,
+ Remove = 7,
+ NowUnix = 8,
+ NowMs = 9,
+ FormatTime = 10,
+ SleepMs = 11,
+ ParseTime = 12,
+ EnvGet = 13,
+ EnvSet = 14,
+ Args = 15,
+ Cwd = 16,
+ Exit = 17,
+ Exec = 18,
+ JsonParse = 19,
+ JsonStringify = 20,
+ JsonGet = 21,
+ JsonKeys = 22,
+ HttpGet = 23,
+ HttpPost = 24,
+ UrlEncode = 25,
+}
+
+impl HostFn {
+ pub fn from_u16(id: u16) -> Option {
+ Some(match id {
+ 1 => Self::ReadText,
+ 2 => Self::WriteText,
+ 3 => Self::AppendText,
+ 4 => Self::Exists,
+ 5 => Self::ListDir,
+ 6 => Self::MakeDir,
+ 7 => Self::Remove,
+ 8 => Self::NowUnix,
+ 9 => Self::NowMs,
+ 10 => Self::FormatTime,
+ 11 => Self::SleepMs,
+ 12 => Self::ParseTime,
+ 13 => Self::EnvGet,
+ 14 => Self::EnvSet,
+ 15 => Self::Args,
+ 16 => Self::Cwd,
+ 17 => Self::Exit,
+ 18 => Self::Exec,
+ 19 => Self::JsonParse,
+ 20 => Self::JsonStringify,
+ 21 => Self::JsonGet,
+ 22 => Self::JsonKeys,
+ 23 => Self::HttpGet,
+ 24 => Self::HttpPost,
+ 25 => Self::UrlEncode,
+ _ => return None,
+ })
+ }
+
+ pub fn from_name(name: &str) -> Option {
+ Some(match name {
+ "host_read_text" => Self::ReadText,
+ "host_write_text" => Self::WriteText,
+ "host_append_text" => Self::AppendText,
+ "host_exists" => Self::Exists,
+ "host_list_dir" => Self::ListDir,
+ "host_make_dir" => Self::MakeDir,
+ "host_remove" => Self::Remove,
+ "host_now_unix" => Self::NowUnix,
+ "host_now_ms" => Self::NowMs,
+ "host_format_time" => Self::FormatTime,
+ "host_sleep_ms" => Self::SleepMs,
+ "host_parse_time" => Self::ParseTime,
+ "host_env_get" => Self::EnvGet,
+ "host_env_set" => Self::EnvSet,
+ "host_args" => Self::Args,
+ "host_cwd" => Self::Cwd,
+ "host_exit" => Self::Exit,
+ "host_exec" => Self::Exec,
+ "host_json_parse" => Self::JsonParse,
+ "host_json_stringify" => Self::JsonStringify,
+ "host_json_get" => Self::JsonGet,
+ "host_json_keys" => Self::JsonKeys,
+ "host_http_get" => Self::HttpGet,
+ "host_http_post" => Self::HttpPost,
+ "host_url_encode" => Self::UrlEncode,
+ _ => return None,
+ })
+ }
+
+ pub fn as_u16(self) -> u16 {
+ self as u16
+ }
+
+ pub fn name(self) -> &'static str {
+ match self {
+ Self::ReadText => "host_read_text",
+ Self::WriteText => "host_write_text",
+ Self::AppendText => "host_append_text",
+ Self::Exists => "host_exists",
+ Self::ListDir => "host_list_dir",
+ Self::MakeDir => "host_make_dir",
+ Self::Remove => "host_remove",
+ Self::NowUnix => "host_now_unix",
+ Self::NowMs => "host_now_ms",
+ Self::FormatTime => "host_format_time",
+ Self::SleepMs => "host_sleep_ms",
+ Self::ParseTime => "host_parse_time",
+ Self::EnvGet => "host_env_get",
+ Self::EnvSet => "host_env_set",
+ Self::Args => "host_args",
+ Self::Cwd => "host_cwd",
+ Self::Exit => "host_exit",
+ Self::Exec => "host_exec",
+ Self::JsonParse => "host_json_parse",
+ Self::JsonStringify => "host_json_stringify",
+ Self::JsonGet => "host_json_get",
+ Self::JsonKeys => "host_json_keys",
+ Self::HttpGet => "host_http_get",
+ Self::HttpPost => "host_http_post",
+ Self::UrlEncode => "host_url_encode",
+ }
+ }
+
+ /// Required params first; see `optional_params` for trailing optionals.
+ pub fn required_params(self) -> &'static [&'static str] {
+ match self {
+ Self::ReadText | Self::Exists | Self::ListDir | Self::MakeDir | Self::Remove => {
+ &["path"]
+ }
+ Self::WriteText | Self::AppendText => &["path", "text"],
+ Self::NowUnix | Self::NowMs | Self::Args | Self::Cwd => &[],
+ Self::FormatTime => &["unix", "pattern"],
+ Self::ParseTime => &["text", "pattern"],
+ Self::SleepMs => &["ms"],
+ Self::EnvGet => &["name"],
+ Self::EnvSet => &["name", "value"],
+ Self::Exit => &["code"],
+ Self::Exec => &["cmd"],
+ Self::JsonParse | Self::UrlEncode => &["text"],
+ Self::JsonStringify | Self::JsonKeys => &["value"],
+ Self::JsonGet => &["value", "key"],
+ Self::HttpGet => &["url"],
+ Self::HttpPost => &["url", "body"],
+ }
+ }
+
+ pub fn optional_params(self) -> &'static [&'static str] {
+ match self {
+ Self::JsonStringify => &["indent"],
+ Self::HttpPost => &["content_type"],
+ Self::Exec => &["args"],
+ _ => &[],
+ }
+ }
+
+ pub fn all_params(self) -> Vec<&'static str> {
+ let mut v = self.required_params().to_vec();
+ v.extend_from_slice(self.optional_params());
+ v
+ }
+}
+
+pub fn call_host(
+ ctx: &HostContext,
+ fn_id: HostFn,
+ bound: &HashMap,
+) -> Result {
+ match fn_id {
+ HostFn::ReadText => fs::read_text(ctx, require(bound, "path")?),
+ HostFn::WriteText => {
+ fs::write_text(ctx, require(bound, "path")?, require(bound, "text")?)
+ }
+ HostFn::AppendText => {
+ fs::append_text(ctx, require(bound, "path")?, require(bound, "text")?)
+ }
+ HostFn::Exists => fs::exists(ctx, require(bound, "path")?),
+ HostFn::ListDir => fs::list_dir(ctx, require(bound, "path")?),
+ HostFn::MakeDir => fs::make_dir(ctx, require(bound, "path")?),
+ HostFn::Remove => fs::remove(ctx, require(bound, "path")?),
+ HostFn::NowUnix => time::now_unix(),
+ HostFn::NowMs => time::now_ms(),
+ HostFn::FormatTime => {
+ time::format_time(require(bound, "unix")?, require(bound, "pattern")?)
+ }
+ HostFn::SleepMs => time::sleep_ms(ctx, require(bound, "ms")?),
+ HostFn::ParseTime => {
+ time::parse_time(require(bound, "text")?, require(bound, "pattern")?)
+ }
+ HostFn::EnvGet => sys::env_get(require(bound, "name")?),
+ HostFn::EnvSet => sys::env_set(require(bound, "name")?, require(bound, "value")?),
+ HostFn::Args => sys::args(ctx),
+ HostFn::Cwd => sys::cwd(ctx),
+ HostFn::Exit => sys::exit(ctx, require(bound, "code")?),
+ HostFn::Exec => sys::exec(ctx, require(bound, "cmd")?, bound.get("args")),
+ HostFn::JsonParse => json::parse(require(bound, "text")?),
+ HostFn::JsonStringify => {
+ json::stringify(require(bound, "value")?, bound.get("indent"))
+ }
+ HostFn::JsonGet => json::get(require(bound, "value")?, require(bound, "key")?),
+ HostFn::JsonKeys => json::keys(require(bound, "value")?),
+ HostFn::HttpGet => net::http_get(ctx, require(bound, "url")?),
+ HostFn::HttpPost => net::http_post(
+ ctx,
+ require(bound, "url")?,
+ require(bound, "body")?,
+ bound.get("content_type"),
+ ),
+ HostFn::UrlEncode => net::url_encode(require(bound, "text")?),
+ }
+}
+
+fn require<'a>(bound: &'a HashMap, key: &str) -> Result<&'a Value, String> {
+ bound
+ .get(key)
+ .ok_or_else(|| format!("host call missing `{key}`"))
+}
diff --git a/src/host/fs.rs b/src/host/fs.rs
new file mode 100644
index 0000000..eacda34
--- /dev/null
+++ b/src/host/fs.rs
@@ -0,0 +1,108 @@
+//! Filesystem host primitives.
+
+use std::fs;
+use std::path::Path;
+
+use crate::host::HostContext;
+use crate::value::Value;
+
+pub fn path_under_root(path: &Path, root: &Path) -> bool {
+ let mut cur = path.to_path_buf();
+ loop {
+ if cur == *root {
+ return true;
+ }
+ if !cur.pop() {
+ return false;
+ }
+ }
+}
+
+fn text_path(v: &Value) -> Result<&str, String> {
+ match v {
+ Value::Text(s) => Ok(s.as_str()),
+ _ => Err("path must be text".into()),
+ }
+}
+
+fn text_body(v: &Value) -> Result<&str, String> {
+ match v {
+ Value::Text(s) => Ok(s.as_str()),
+ _ => Err("text must be text".into()),
+ }
+}
+
+pub fn read_text(ctx: &HostContext, path: &Value) -> Result {
+ let p = ctx.resolve_path(text_path(path)?)?;
+ let s = fs::read_to_string(&p).map_err(|e| format!("read_text {}: {e}", p.display()))?;
+ Ok(Value::Text(s))
+}
+
+pub fn write_text(ctx: &HostContext, path: &Value, text: &Value) -> Result {
+ if !ctx.allow_fs_write() {
+ return Err("write_text denied by host policy".into());
+ }
+ let p = ctx.resolve_path(text_path(path)?)?;
+ if let Some(parent) = p.parent() {
+ fs::create_dir_all(parent).map_err(|e| format!("write_text mkdir: {e}"))?;
+ }
+ fs::write(&p, text_body(text)?).map_err(|e| format!("write_text {}: {e}", p.display()))?;
+ Ok(Value::None)
+}
+
+pub fn append_text(ctx: &HostContext, path: &Value, text: &Value) -> Result {
+ if !ctx.allow_fs_write() {
+ return Err("append_text denied by host policy".into());
+ }
+ let p = ctx.resolve_path(text_path(path)?)?;
+ use std::io::Write;
+ let mut f = fs::OpenOptions::new()
+ .create(true)
+ .append(true)
+ .open(&p)
+ .map_err(|e| format!("append_text {}: {e}", p.display()))?;
+ f.write_all(text_body(text)?.as_bytes())
+ .map_err(|e| format!("append_text {}: {e}", p.display()))?;
+ Ok(Value::None)
+}
+
+pub fn exists(ctx: &HostContext, path: &Value) -> Result {
+ let p = ctx.resolve_path(text_path(path)?)?;
+ Ok(Value::Bool(p.exists()))
+}
+
+pub fn list_dir(ctx: &HostContext, path: &Value) -> Result {
+ let p = ctx.resolve_path(text_path(path)?)?;
+ let mut names = Vec::new();
+ let rd = fs::read_dir(&p).map_err(|e| format!("list_dir {}: {e}", p.display()))?;
+ for ent in rd {
+ let ent = ent.map_err(|e| format!("list_dir: {e}"))?;
+ names.push(Value::Text(
+ ent.file_name().to_string_lossy().into_owned(),
+ ));
+ }
+ names.sort_by(|a, b| a.as_display().cmp(&b.as_display()));
+ Ok(Value::List(names))
+}
+
+pub fn make_dir(ctx: &HostContext, path: &Value) -> Result {
+ if !ctx.allow_fs_write() {
+ return Err("make_dir denied by host policy".into());
+ }
+ let p = ctx.resolve_path(text_path(path)?)?;
+ fs::create_dir_all(&p).map_err(|e| format!("make_dir {}: {e}", p.display()))?;
+ Ok(Value::None)
+}
+
+pub fn remove(ctx: &HostContext, path: &Value) -> Result {
+ if !ctx.allow_fs_write() {
+ return Err("remove denied by host policy".into());
+ }
+ let p = ctx.resolve_path(text_path(path)?)?;
+ if p.is_dir() {
+ fs::remove_dir_all(&p).map_err(|e| format!("remove {}: {e}", p.display()))?;
+ } else {
+ fs::remove_file(&p).map_err(|e| format!("remove {}: {e}", p.display()))?;
+ }
+ Ok(Value::None)
+}
diff --git a/src/host/json.rs b/src/host/json.rs
new file mode 100644
index 0000000..6d7b714
--- /dev/null
+++ b/src/host/json.rs
@@ -0,0 +1,106 @@
+//! JSON host primitives + Value↔JSON mapping.
+
+use crate::value::Value;
+
+pub fn parse(text: &Value) -> Result {
+ let s = match text {
+ Value::Text(s) => s.as_str(),
+ _ => return Err("json parse needs text".into()),
+ };
+ let v: serde_json::Value =
+ serde_json::from_str(s).map_err(|e| format!("json parse: {e}"))?;
+ json_to_value(&v)
+}
+
+pub fn stringify(value: &Value, indent: Option<&Value>) -> Result {
+ let j = value_to_json(value)?;
+ let pretty = match indent {
+ None => false,
+ Some(Value::Int(n)) => *n > 0,
+ Some(Value::Bool(b)) => *b,
+ Some(Value::None) => false,
+ Some(_) => return Err("json stringify indent must be int or bool".into()),
+ };
+ let s = if pretty {
+ serde_json::to_string_pretty(&j).map_err(|e| format!("json stringify: {e}"))?
+ } else {
+ serde_json::to_string(&j).map_err(|e| format!("json stringify: {e}"))?
+ };
+ Ok(Value::Text(s))
+}
+
+pub fn get(value: &Value, key: &Value) -> Result {
+ let k = match key {
+ Value::Text(s) => s.as_str(),
+ _ => return Err("json get key must be text".into()),
+ };
+ match value {
+ Value::Map(entries) => Ok(entries
+ .iter()
+ .find(|(kk, _)| kk == k)
+ .map(|(_, v)| v.clone())
+ .unwrap_or(Value::None)),
+ _ => Err("json get needs map".into()),
+ }
+}
+
+pub fn keys(value: &Value) -> Result {
+ match value {
+ Value::Map(entries) => Ok(Value::List(
+ entries.iter().map(|(k, _)| Value::Text(k.clone())).collect(),
+ )),
+ _ => Err("json keys needs map".into()),
+ }
+}
+
+fn json_to_value(v: &serde_json::Value) -> Result {
+ Ok(match v {
+ serde_json::Value::Null => Value::None,
+ serde_json::Value::Bool(b) => Value::Bool(*b),
+ serde_json::Value::Number(n) => {
+ if let Some(i) = n.as_i64() {
+ Value::Int(i)
+ } else {
+ Value::Text(n.to_string())
+ }
+ }
+ serde_json::Value::String(s) => Value::Text(s.clone()),
+ serde_json::Value::Array(xs) => {
+ let mut out = Vec::with_capacity(xs.len());
+ for x in xs {
+ out.push(json_to_value(x)?);
+ }
+ Value::List(out)
+ }
+ serde_json::Value::Object(map) => {
+ let mut entries = Vec::with_capacity(map.len());
+ for (k, v) in map {
+ entries.push((k.clone(), json_to_value(v)?));
+ }
+ Value::Map(entries)
+ }
+ })
+}
+
+fn value_to_json(v: &Value) -> Result {
+ Ok(match v {
+ Value::None => serde_json::Value::Null,
+ Value::Bool(b) => serde_json::Value::Bool(*b),
+ Value::Int(n) => serde_json::Value::Number((*n).into()),
+ Value::Text(s) => serde_json::Value::String(s.clone()),
+ Value::List(xs) => {
+ let mut arr = Vec::with_capacity(xs.len());
+ for x in xs {
+ arr.push(value_to_json(x)?);
+ }
+ serde_json::Value::Array(arr)
+ }
+ Value::Map(entries) => {
+ let mut map = serde_json::Map::new();
+ for (k, v) in entries {
+ map.insert(k.clone(), value_to_json(v)?);
+ }
+ serde_json::Value::Object(map)
+ }
+ })
+}
diff --git a/src/host/mod.rs b/src/host/mod.rs
new file mode 100644
index 0000000..12bce24
--- /dev/null
+++ b/src/host/mod.rs
@@ -0,0 +1,126 @@
+//! L0.5 host primitives for official stdlib (`lib/fs`, `time`, …).
+//!
+//! User docs should import L1 wrappers; these `host_*` names are the Rust surface.
+//! Capabilities default **on** (importing a lib means you intend to use it).
+//! Soft side-effects (no process::exit; sleep clamp) apply under view / capture only.
+
+mod dispatch;
+mod fs;
+mod json;
+mod net;
+mod sys;
+mod time;
+
+pub use dispatch::{call_host, HostFn};
+pub use fs::path_under_root;
+
+use std::path::{Path, PathBuf};
+
+/// Host capability flags. Default: all enabled.
+#[derive(Debug, Clone)]
+pub struct HostCaps {
+ pub fs_write: bool,
+ pub exec: bool,
+ pub net: bool,
+}
+
+impl Default for HostCaps {
+ fn default() -> Self {
+ Self {
+ fs_write: true,
+ exec: true,
+ net: true,
+ }
+ }
+}
+
+#[derive(Debug, Clone)]
+pub struct HostContext {
+ pub caps: HostCaps,
+ pub fs_root: Option,
+ pub cwd: PathBuf,
+ pub argv: Vec,
+ /// Soft mode: do not `process::exit`; honor sleep_limit (view / capture / export).
+ pub soft_side_effects: bool,
+ pub sleep_limit_ms: Option,
+}
+
+impl Default for HostContext {
+ fn default() -> Self {
+ Self {
+ caps: HostCaps::default(),
+ fs_root: None,
+ cwd: std::env::current_dir().unwrap_or_else(|_| PathBuf::from(".")),
+ argv: Vec::new(),
+ soft_side_effects: false,
+ sleep_limit_ms: Some(30_000),
+ }
+ }
+}
+
+impl HostContext {
+ pub fn for_run(path: Option<&Path>, caps: HostCaps, argv: Vec) -> Self {
+ let mut ctx = Self::default();
+ ctx.caps = caps;
+ ctx.argv = argv;
+ if let Some(p) = path {
+ if let Some(parent) = p.parent() {
+ let parent = if parent.as_os_str().is_empty() {
+ PathBuf::from(".")
+ } else {
+ parent.to_path_buf()
+ };
+ ctx.cwd = parent.clone();
+ ctx.fs_root = Some(parent);
+ }
+ }
+ ctx
+ }
+
+ /// Capture stdout / view / export: soft exit + sleep clamp; same caps as CLI by default.
+ pub fn for_capture(path: Option<&Path>, caps: HostCaps) -> Self {
+ let mut ctx = Self::for_run(path, caps, Vec::new());
+ ctx.soft_side_effects = true;
+ ctx.sleep_limit_ms = Some(0);
+ ctx
+ }
+
+ pub fn allow_fs_write(&self) -> bool {
+ self.caps.fs_write
+ }
+
+ pub fn allow_exec(&self) -> bool {
+ self.caps.exec
+ }
+
+ pub fn allow_net(&self) -> bool {
+ self.caps.net
+ }
+
+ pub fn resolve_path(&self, rel: &str) -> Result {
+ let p = Path::new(rel);
+ let abs = if p.is_absolute() {
+ p.to_path_buf()
+ } else {
+ self.cwd.join(p)
+ };
+ if let Some(root) = &self.fs_root {
+ let root_canon = root.canonicalize().unwrap_or_else(|_| root.clone());
+ let check = abs.canonicalize().unwrap_or_else(|_| abs.clone());
+ if !path_under_root(&check, &root_canon) && !path_under_root(&abs, root) {
+ if let Some(parent) = abs.parent() {
+ let parent_ok = parent
+ .canonicalize()
+ .map(|p| path_under_root(&p, &root_canon))
+ .unwrap_or_else(|_| path_under_root(parent, root));
+ if !parent_ok {
+ return Err(format!("path escapes sandbox root: {}", abs.display()));
+ }
+ } else {
+ return Err(format!("path escapes sandbox root: {}", abs.display()));
+ }
+ }
+ }
+ Ok(abs)
+ }
+}
diff --git a/src/host/net.rs b/src/host/net.rs
new file mode 100644
index 0000000..a6852df
--- /dev/null
+++ b/src/host/net.rs
@@ -0,0 +1,152 @@
+//! Minimal HTTP host primitives (HTTP cleartext in v1; HTTPS deferred).
+
+use std::io::{Read, Write};
+use std::net::TcpStream;
+use std::time::Duration;
+
+use crate::host::HostContext;
+use crate::value::Value;
+
+fn as_text<'a>(v: &'a Value, label: &str) -> Result<&'a str, String> {
+ match v {
+ Value::Text(s) => Ok(s.as_str()),
+ _ => Err(format!("{label} must be text")),
+ }
+}
+
+struct UrlParts {
+ host: String,
+ port: u16,
+ path: String,
+}
+
+fn parse_http_url(url: &str) -> Result {
+ let rest = url
+ .strip_prefix("http://")
+ .ok_or_else(|| {
+ if url.starts_with("https://") {
+ "https is not supported yet (use http:// or wait for TLS)".to_string()
+ } else {
+ "url must start with http://".into()
+ }
+ })?;
+ let (hostport, path) = match rest.split_once('/') {
+ Some((h, p)) => (h, format!("/{p}")),
+ None => (rest, "/".into()),
+ };
+ let (host, port) = if let Some((h, p)) = hostport.split_once(':') {
+ let port: u16 = p
+ .parse()
+ .map_err(|_| format!("invalid port in url: {p}"))?;
+ (h.to_string(), port)
+ } else {
+ (hostport.to_string(), 80)
+ };
+ if host.is_empty() {
+ return Err("url missing host".into());
+ }
+ Ok(UrlParts { host, port, path })
+}
+
+fn http_exchange(
+ method: &str,
+ url: &str,
+ body: Option<&str>,
+ content_type: &str,
+) -> Result<(u16, String), String> {
+ let parts = parse_http_url(url)?;
+ let addr = format!("{}:{}", parts.host, parts.port);
+ let mut stream = TcpStream::connect(&addr).map_err(|e| format!("http connect {addr}: {e}"))?;
+ stream
+ .set_read_timeout(Some(Duration::from_secs(10)))
+ .ok();
+ stream
+ .set_write_timeout(Some(Duration::from_secs(10)))
+ .ok();
+
+ let body = body.unwrap_or("");
+ let mut req = format!(
+ "{method} {path} HTTP/1.0\r\nHost: {host}\r\nConnection: close\r\nUser-Agent: marqdo\r\n",
+ path = parts.path,
+ host = parts.host,
+ );
+ if method == "POST" {
+ req.push_str(&format!(
+ "Content-Type: {content_type}\r\nContent-Length: {}\r\n",
+ body.len()
+ ));
+ }
+ req.push_str("\r\n");
+ if method == "POST" {
+ req.push_str(body);
+ }
+ stream
+ .write_all(req.as_bytes())
+ .map_err(|e| format!("http write: {e}"))?;
+
+ let mut buf = Vec::new();
+ stream
+ .read_to_end(&mut buf)
+ .map_err(|e| format!("http read: {e}"))?;
+ if buf.len() > 2 * 1024 * 1024 {
+ return Err("http response exceeds 2MiB limit".into());
+ }
+ let text = String::from_utf8_lossy(&buf);
+ let (header, body) = text.split_once("\r\n\r\n").unwrap_or((text.as_ref(), ""));
+ let status = header
+ .lines()
+ .next()
+ .and_then(|line| line.split_whitespace().nth(1))
+ .and_then(|s| s.parse::().ok())
+ .unwrap_or(0);
+ Ok((status, body.to_string()))
+}
+
+pub fn http_get(ctx: &HostContext, url: &Value) -> Result {
+ if !ctx.allow_net() {
+ return Err("http_get denied by host policy".into());
+ }
+ let url = as_text(url, "url")?;
+ let (status, body) = http_exchange("GET", url, None, "")?;
+ Ok(Value::Map(vec![
+ ("status".into(), Value::Int(status as i64)),
+ ("body".into(), Value::Text(body)),
+ ]))
+}
+
+pub fn http_post(
+ ctx: &HostContext,
+ url: &Value,
+ body: &Value,
+ content_type: Option<&Value>,
+) -> Result {
+ if !ctx.allow_net() {
+ return Err("http_post denied by host policy".into());
+ }
+ let url = as_text(url, "url")?;
+ let body = as_text(body, "body")?;
+ let ct = match content_type {
+ Some(v) => as_text(v, "content_type")?,
+ None => "text/plain; charset=utf-8",
+ };
+ let (status, resp) = http_exchange("POST", url, Some(body), ct)?;
+ Ok(Value::Map(vec![
+ ("status".into(), Value::Int(status as i64)),
+ ("body".into(), Value::Text(resp)),
+ ]))
+}
+
+pub fn url_encode(text: &Value) -> Result {
+ let s = as_text(text, "text")?;
+ Ok(Value::Text(
+ s.bytes()
+ .map(|b| match b {
+ b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'.' | b'~' => {
+ (b as char).to_string()
+ }
+ b' ' => "+".into(),
+ _ => format!("%{b:02X}"),
+ })
+ .collect(),
+ ))
+}
diff --git a/src/host/sys.rs b/src/host/sys.rs
new file mode 100644
index 0000000..c4d9e0c
--- /dev/null
+++ b/src/host/sys.rs
@@ -0,0 +1,79 @@
+//! System / process host primitives.
+
+use std::process::Command;
+
+use crate::host::HostContext;
+use crate::value::Value;
+
+fn as_text<'a>(v: &'a Value, label: &str) -> Result<&'a str, String> {
+ match v {
+ Value::Text(s) => Ok(s.as_str()),
+ _ => Err(format!("{label} must be text")),
+ }
+}
+
+fn as_i64(v: &Value, label: &str) -> Result {
+ match v {
+ Value::Int(n) => Ok(*n),
+ _ => Err(format!("{label} must be int")),
+ }
+}
+
+pub fn env_get(name: &Value) -> Result {
+ let key = as_text(name, "name")?;
+ Ok(match std::env::var(key) {
+ Ok(v) => Value::Text(v),
+ Err(_) => Value::None,
+ })
+}
+
+pub fn env_set(name: &Value, value: &Value) -> Result {
+ let key = as_text(name, "name")?;
+ let val = as_text(value, "value")?;
+ std::env::set_var(key, val);
+ Ok(Value::None)
+}
+
+pub fn args(ctx: &HostContext) -> Result {
+ Ok(Value::List(
+ ctx.argv.iter().map(|s| Value::Text(s.clone())).collect(),
+ ))
+}
+
+pub fn cwd(ctx: &HostContext) -> Result {
+ Ok(Value::Text(ctx.cwd.display().to_string()))
+}
+
+pub fn exit(ctx: &HostContext, code: &Value) -> Result {
+ let c = as_i64(code, "code")?;
+ if ctx.soft_side_effects {
+ return Err(format!("exit {c} (soft mode does not terminate process)"));
+ }
+ std::process::exit(c as i32);
+}
+
+pub fn exec(ctx: &HostContext, cmd: &Value, args: Option<&Value>) -> Result {
+ if !ctx.allow_exec() {
+ return Err("exec denied by host policy".into());
+ }
+ let cmd = as_text(cmd, "cmd")?;
+ let mut command = Command::new(cmd);
+ command.current_dir(&ctx.cwd);
+ if let Some(a) = args {
+ match a {
+ Value::List(xs) => {
+ for x in xs {
+ command.arg(x.as_display());
+ }
+ }
+ Value::Text(s) => {
+ command.arg(s);
+ }
+ _ => return Err("exec args must be list or text".into()),
+ }
+ }
+ let status = command
+ .status()
+ .map_err(|e| format!("exec `{cmd}`: {e}"))?;
+ Ok(Value::Int(status.code().unwrap_or(1) as i64))
+}
diff --git a/src/host/time.rs b/src/host/time.rs
new file mode 100644
index 0000000..fdba51d
--- /dev/null
+++ b/src/host/time.rs
@@ -0,0 +1,71 @@
+//! Time host primitives.
+
+use std::thread;
+use std::time::{Duration, SystemTime, UNIX_EPOCH};
+
+use chrono::{DateTime, NaiveDateTime, Utc};
+
+use crate::host::HostContext;
+use crate::value::Value;
+
+pub fn now_unix() -> Result {
+ let secs = SystemTime::now()
+ .duration_since(UNIX_EPOCH)
+ .map_err(|e| format!("now_unix: {e}"))?
+ .as_secs();
+ Ok(Value::Int(secs as i64))
+}
+
+pub fn now_ms() -> Result {
+ let ms = SystemTime::now()
+ .duration_since(UNIX_EPOCH)
+ .map_err(|e| format!("now_ms: {e}"))?
+ .as_millis();
+ Ok(Value::Int(ms as i64))
+}
+
+fn as_i64(v: &Value, label: &str) -> Result {
+ match v {
+ Value::Int(n) => Ok(*n),
+ _ => Err(format!("{label} must be int")),
+ }
+}
+
+fn as_text<'a>(v: &'a Value, label: &str) -> Result<&'a str, String> {
+ match v {
+ Value::Text(s) => Ok(s.as_str()),
+ _ => Err(format!("{label} must be text")),
+ }
+}
+
+pub fn format_time(unix: &Value, pattern: &Value) -> Result {
+ let secs = as_i64(unix, "unix")?;
+ let pat = as_text(pattern, "pattern")?;
+ let dt = DateTime::::from_timestamp(secs, 0)
+ .ok_or_else(|| format!("invalid unix timestamp: {secs}"))?;
+ Ok(Value::Text(dt.format(pat).to_string()))
+}
+
+pub fn parse_time(text: &Value, pattern: &Value) -> Result {
+ let t = as_text(text, "text")?;
+ let pat = as_text(pattern, "pattern")?;
+ let dt = NaiveDateTime::parse_from_str(t, pat).map_err(|e| format!("parse_time: {e}"))?;
+ Ok(Value::Int(dt.and_utc().timestamp()))
+}
+
+pub fn sleep_ms(ctx: &HostContext, ms: &Value) -> Result {
+ let n = as_i64(ms, "ms")?;
+ if n < 0 {
+ return Err("sleep_ms must be >= 0".into());
+ }
+ let n = n as u64;
+ if let Some(lim) = ctx.sleep_limit_ms {
+ if n > lim {
+ return Err(format!("sleep_ms {n} exceeds limit {lim}"));
+ }
+ }
+ if n > 0 {
+ thread::sleep(Duration::from_millis(n));
+ }
+ Ok(Value::None)
+}
diff --git a/src/interp.rs b/src/interp.rs
index 4e8471a..0bfbb74 100644
--- a/src/interp.rs
+++ b/src/interp.rs
@@ -13,6 +13,7 @@ use crate::builtin::{
};
use crate::debug::emit_trace;
use crate::diagnostics::{bail_at, Span};
+use crate::host::{call_host, HostContext, HostFn};
use crate::input_feed::InputFeed;
use crate::value::Value;
@@ -23,6 +24,7 @@ pub struct Interpreter {
pub captured_stdout: String,
current_span: Span,
input: InputFeed,
+ host: HostContext,
}
struct Env {
@@ -59,6 +61,7 @@ impl Interpreter {
captured_stdout: String::new(),
current_span: Span::new(1, 1),
input: InputFeed::new(false, Vec::new()),
+ host: HostContext::for_run(path, Default::default(), Vec::new()),
}
}
@@ -70,6 +73,7 @@ impl Interpreter {
captured_stdout: String::new(),
current_span: Span::new(1, 1),
input: InputFeed::new(true, Vec::new()),
+ host: HostContext::for_capture(path, Default::default()),
}
}
@@ -78,6 +82,11 @@ impl Interpreter {
self
}
+ pub fn with_host(mut self, host: HostContext) -> Self {
+ self.host = host;
+ self
+ }
+
fn err(&self, message: impl Into) -> anyhow::Error {
bail_at(self.path.as_deref(), self.current_span, message)
}
@@ -517,6 +526,21 @@ impl Interpreter {
.ok_or_else(|| self.err("at requires index"))?;
return builtin_at(value, index).map_err(|m| self.err(m));
}
+ other if HostFn::from_name(other).is_some() => {
+ let hf = HostFn::from_name(other).unwrap();
+ let mut params: Vec =
+ hf.required_params().iter().map(|s| (*s).to_string()).collect();
+ for p in hf.optional_params() {
+ params.push((*p).to_string());
+ }
+ let bound = bind_args(¶ms, &ev_args, true).map_err(|m| self.err(m))?;
+ for req in hf.required_params() {
+ if !bound.contains_key(*req) {
+ return Err(self.err(format!("{} requires `{req}`", hf.name())));
+ }
+ }
+ return call_host(&self.host, hf, &bound).map_err(|m| self.err(m));
+ }
_ => {}
}
diff --git a/src/lib.rs b/src/lib.rs
index ef412d7..87abde4 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -11,6 +11,7 @@ pub mod capture;
pub mod catalog;
pub mod debug;
pub mod diagnostics;
+pub mod host;
pub mod input_feed;
pub mod interp;
pub mod lex;
@@ -23,6 +24,7 @@ use std::path::Path;
use anyhow::{bail, Result};
+use crate::host::{HostCaps, HostContext};
use crate::ast::format_ast_dump;
use crate::bytecode::{compile_module, Vm};
use crate::capture::RunCapture;
@@ -48,7 +50,7 @@ impl Backend {
}
/// Options for a single `run` / dump invocation.
-#[derive(Debug, Clone, Default)]
+#[derive(Debug, Clone)]
pub struct RunOptions {
pub dump_lines: bool,
pub dump_tokens: bool,
@@ -59,6 +61,36 @@ pub struct RunOptions {
pub backend: Backend,
/// Preset lines consumed by `input` (from `--stdin-file` or view).
pub stdin_lines: Vec,
+ pub allow_fs_write: bool,
+ pub allow_exec: bool,
+ pub allow_net: bool,
+ /// Exposed via `host_args` / `args`.
+ pub argv: Vec,
+ /// Override filesystem sandbox root (default: source file's directory).
+ pub fs_root: Option,
+ /// Sleep clamp when capturing (None = host default; view export uses `Some(0)`).
+ pub sleep_limit_ms: Option,
+}
+
+impl Default for RunOptions {
+ fn default() -> Self {
+ Self {
+ dump_lines: false,
+ dump_tokens: false,
+ dump_ast: false,
+ dump_sema: false,
+ dump_bytecode: false,
+ trace_eval: false,
+ backend: Backend::default(),
+ stdin_lines: Vec::new(),
+ allow_fs_write: true,
+ allow_exec: true,
+ allow_net: true,
+ argv: Vec::new(),
+ fs_root: None,
+ sleep_limit_ms: None,
+ }
+ }
}
impl RunOptions {
@@ -70,8 +102,7 @@ impl RunOptions {
dump_sema: true,
dump_bytecode: true,
trace_eval: true,
- backend: Backend::Tree,
- stdin_lines: Vec::new(),
+ ..Self::default()
}
}
@@ -83,6 +114,14 @@ impl RunOptions {
|| self.dump_bytecode
|| self.trace_eval
}
+
+ pub fn host_caps(&self) -> HostCaps {
+ HostCaps {
+ fs_write: self.allow_fs_write,
+ exec: self.allow_exec,
+ net: self.allow_net,
+ }
+ }
}
/// Run a `.mq.md` program (prints to real stdout).
@@ -128,8 +167,10 @@ pub fn run_file(path: &Path, opts: &RunOptions) -> Result {
match opts.backend {
Backend::Tree => {
+ let host = HostContext::for_run(Some(path), opts.host_caps(), opts.argv.clone());
let mut interp = Interpreter::new(Some(path), opts.trace_eval)
- .with_stdin(stdin_lines.clone());
+ .with_stdin(stdin_lines.clone())
+ .with_host(host);
if opts.trace_eval {
eprintln!("=== marqdo: trace-eval ({path_label}) ===");
}
@@ -143,9 +184,11 @@ pub fn run_file(path: &Path, opts: &RunOptions) -> Result {
if opts.dump_bytecode {
print!("{}", program.disassemble());
}
+ let host = HostContext::for_run(Some(path), opts.host_caps(), opts.argv.clone());
let mut vm = Vm::new(Some(path))
.with_stdin(stdin_lines)
- .with_trace(opts.trace_eval);
+ .with_trace(opts.trace_eval)
+ .with_host(host);
if opts.trace_eval {
eprintln!("=== marqdo: trace-eval ({path_label}) ===");
}
@@ -173,7 +216,17 @@ pub fn run_file_capture(path: &Path, opts: &RunOptions) -> Result {
let module = load_module(path)?;
match opts.backend {
Backend::Tree => {
- let mut interp = Interpreter::with_capture(Some(path), false).with_stdin(stdin_lines);
+ let mut host = HostContext::for_capture(Some(path), opts.host_caps());
+ host.argv = opts.argv.clone();
+ if let Some(root) = &opts.fs_root {
+ host.fs_root = Some(root.clone());
+ }
+ if let Some(lim) = opts.sleep_limit_ms {
+ host.sleep_limit_ms = Some(lim);
+ }
+ let mut interp = Interpreter::with_capture(Some(path), false)
+ .with_stdin(stdin_lines)
+ .with_host(host);
let value = interp.run_module(&module)?;
Ok(RunCapture {
stdout: interp.captured_stdout,
@@ -182,7 +235,17 @@ pub fn run_file_capture(path: &Path, opts: &RunOptions) -> Result {
}
Backend::Bytecode => {
let program = compile_module(Some(path), &module)?;
- let mut vm = Vm::with_capture(Some(path)).with_stdin(stdin_lines);
+ let mut host = HostContext::for_capture(Some(path), opts.host_caps());
+ host.argv = opts.argv.clone();
+ if let Some(root) = &opts.fs_root {
+ host.fs_root = Some(root.clone());
+ }
+ if let Some(lim) = opts.sleep_limit_ms {
+ host.sleep_limit_ms = Some(lim);
+ }
+ let mut vm = Vm::with_capture(Some(path))
+ .with_stdin(stdin_lines)
+ .with_host(host);
let value = vm.run(&program)?;
Ok(RunCapture {
stdout: vm.captured_stdout,
diff --git a/src/main.rs b/src/main.rs
index cc0507f..522ddd7 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -156,6 +156,7 @@ fn try_main() -> Result {
trace_eval,
backend: backend.into(),
stdin_lines,
+ ..RunOptions::default()
}
};
if dump_all {
diff --git a/src/value.rs b/src/value.rs
index 2a955f2..103522b 100644
--- a/src/value.rs
+++ b/src/value.rs
@@ -10,6 +10,8 @@ pub enum Value {
Text(String),
/// Single-column table rows (v0); multi-column later.
List(Vec),
+ /// JSON object / string-keyed map (insertion order).
+ Map(Vec<(String, Value)>),
}
impl Value {
@@ -20,6 +22,7 @@ impl Value {
Value::Int(n) => *n != 0,
Value::Text(s) => !s.is_empty(),
Value::List(xs) => !xs.is_empty(),
+ Value::Map(xs) => !xs.is_empty(),
}
}
@@ -31,6 +34,7 @@ impl Value {
Value::Int(n) => n.to_string(),
Value::Text(s) => s.clone(),
Value::List(_) => "".into(),
+ Value::Map(_) => "