Add host stdlib modules and unify view/run capabilities.

Ship fs/time/sys/json/net L1 libs (plus existing text/table), default-on host caps with soft exit under view, bilingual public/stdlib docs, and design notes for deferred math/foreign.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
cflmyandCursor committed 2026-08-05 10:03:54 +08:00
1 parent a5d30c00b3
commit a53ebb65ee
66 files changed
+2703 -45

No files matched your search

Generated
+277
View File
@@ -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"
+2
View File
@@ -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"
+3
View File
@@ -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` 黑白极简 + 静态文档** |
+207
View File
@@ -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
<!-- foreign:normalize -->
```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 做成安全可讲的胶水语言。**
+23 -11
View File
@@ -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`——无语言开关。**
+181
View File
@@ -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 区**内嵌渲染**(非仅 `<pre>`)。
- 静态 `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,符号与 `$$` 引用分期,必要时借外联而非做大内核。**
+227
View File
@@ -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`;数学与外联暂缓。**
+14 -5
View File
@@ -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)。
---
+1
View File
@@ -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 构件(结构 / 执行 / 源码),禁止两套皮肤分叉。
+1 -1
View File
@@ -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 是两条路径。
+41
View File
@@ -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`**
+25
View File
@@ -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`**
+20
View File
@@ -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`**
+33
View File
@@ -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`**
+29
View File
@@ -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`**
+41
View File
@@ -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=`路径`**
+29
View File
@@ -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=`格式`**
+33
View File
@@ -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=`命令`**
+20
View File
@@ -0,0 +1,20 @@
---
title: lib/网络
description: 中文简易网络包装
---
# 获取
- 地址
**> host_http_get url=`地址`**
# 提交
- 地址
- 内容
**> host_http_post url=`地址` body=`内容`**
# 编码地址
- 内容
**> host_url_encode text=`内容`**
+1 -1
View File
@@ -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)(叙述与内置均用中文)。
+1 -1
View File
@@ -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).
+9 -11
View File
@@ -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)。
+18
View File
@@ -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
+18
View File
@@ -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.
> 打印 内容=标准库总览就绪
+18
View File
@@ -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
+19
View File
@@ -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`
+13
View File
@@ -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`
+18
View File
@@ -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
+24
View File
@@ -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`
+19
View File
@@ -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`
+19
View File
@@ -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
+18
View File
@@ -0,0 +1,18 @@
---
title: lib/文件 — 文件系统
description: 沙箱内读写文本
> lib/文件.mq.md
---
# main
导入 lib/文件.mq.md。函数:读文本、写文本、追加文本、存在、列目录、建目录、删除。
裸路径字面量不要写斜杠(会被当成除法)。可用同目录文件名或变量。
*`ok` = > 存在 路径=demo.txt *
+ `ok`
> 打印 内容=有演示文件
+ *
> 打印 内容=无演示文件
+19
View File
@@ -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`
+19
View File
@@ -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
+18
View File
@@ -0,0 +1,18 @@
---
title: lib/系统 — 进程
description: 环境变量、工作目录、参数、退出、执行
> lib/系统.mq.md
---
# main
导入 lib/系统.mq.md。函数:取环境、设环境、参数表、工作目录、退出(码)、执行(命令)。view 下退出会软失败,不结束进程。
*`d` = > 工作目录 *
*`n` = > 长度 值=`d` *
+ `n` > 0
> 打印 内容=工作目录就绪
+ *
> 打印 内容=工作目录空
+13
View File
@@ -0,0 +1,13 @@
---
title: lib/网络 — HTTP
description: 简易 HTTP 与地址编码
> lib/网络.mq.md
---
# main
导入 lib/网络.mq.md。函数:获取(地址) 返回 map status/body、提交(地址, 内容)、编码地址(内容)。本波仅明文 http。
*`e` = > 编码地址 内容=你好 *
> 打印 内容=`e`
+24
View File
@@ -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`
+3
View File
@@ -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"),
+2 -1
View File
@@ -31,7 +31,7 @@ pub fn builtin_int(v: &Value) -> Result<i64, String> {
}
}
/// `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(),
)
+39
View File
@@ -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<String, &Expr> = 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(());
}
_ => {}
}
+2
View File
@@ -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,
}
+39
View File
@@ -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<PathBuf>,
@@ -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;
+227
View File
@@ -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<Self> {
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<Self> {
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<String, Value>,
) -> Result<Value, String> {
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<String, Value>, key: &str) -> Result<&'a Value, String> {
bound
.get(key)
.ok_or_else(|| format!("host call missing `{key}`"))
}
+108
View File
@@ -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<Value, String> {
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<Value, String> {
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<Value, String> {
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<Value, String> {
let p = ctx.resolve_path(text_path(path)?)?;
Ok(Value::Bool(p.exists()))
}
pub fn list_dir(ctx: &HostContext, path: &Value) -> Result<Value, String> {
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<Value, String> {
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<Value, String> {
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)
}
+106
View File
@@ -0,0 +1,106 @@
//! JSON host primitives + Value↔JSON mapping.
use crate::value::Value;
pub fn parse(text: &Value) -> Result<Value, String> {
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<Value, String> {
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<Value, String> {
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<Value, String> {
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<Value, String> {
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<serde_json::Value, String> {
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)
}
})
}
+126
View File
@@ -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<PathBuf>,
pub cwd: PathBuf,
pub argv: Vec<String>,
/// Soft mode: do not `process::exit`; honor sleep_limit (view / capture / export).
pub soft_side_effects: bool,
pub sleep_limit_ms: Option<u64>,
}
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<String>) -> 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<PathBuf, String> {
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)
}
}
+152
View File
@@ -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<UrlParts, String> {
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::<u16>().ok())
.unwrap_or(0);
Ok((status, body.to_string()))
}
pub fn http_get(ctx: &HostContext, url: &Value) -> Result<Value, String> {
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<Value, String> {
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<Value, String> {
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(),
))
}
+79
View File
@@ -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<i64, String> {
match v {
Value::Int(n) => Ok(*n),
_ => Err(format!("{label} must be int")),
}
}
pub fn env_get(name: &Value) -> Result<Value, String> {
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<Value, String> {
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<Value, String> {
Ok(Value::List(
ctx.argv.iter().map(|s| Value::Text(s.clone())).collect(),
))
}
pub fn cwd(ctx: &HostContext) -> Result<Value, String> {
Ok(Value::Text(ctx.cwd.display().to_string()))
}
pub fn exit(ctx: &HostContext, code: &Value) -> Result<Value, String> {
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<Value, String> {
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))
}
+71
View File
@@ -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<Value, String> {
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<Value, String> {
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<i64, String> {
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<Value, String> {
let secs = as_i64(unix, "unix")?;
let pat = as_text(pattern, "pattern")?;
let dt = DateTime::<Utc>::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<Value, String> {
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<Value, String> {
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)
}
+24
View File
@@ -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<String>) -> 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<String> =
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(&params, &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));
}
_ => {}
}
+70 -7
View File
@@ -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<String>,
pub allow_fs_write: bool,
pub allow_exec: bool,
pub allow_net: bool,
/// Exposed via `host_args` / `args`.
pub argv: Vec<String>,
/// Override filesystem sandbox root (default: source file's directory).
pub fs_root: Option<std::path::PathBuf>,
/// Sleep clamp when capturing (None = host default; view export uses `Some(0)`).
pub sleep_limit_ms: Option<u64>,
}
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<i32> {
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<i32> {
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<RunCapture> {
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<RunCapture> {
}
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,
+1
View File
@@ -156,6 +156,7 @@ fn try_main() -> Result<i32> {
trace_eval,
backend: backend.into(),
stdin_lines,
..RunOptions::default()
}
};
if dump_all {
+4
View File
@@ -10,6 +10,8 @@ pub enum Value {
Text(String),
/// Single-column table rows (v0); multi-column later.
List(Vec<Value>),
/// 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(_) => "<list>".into(),
Value::Map(_) => "<map>".into(),
}
}
}
+10 -6
View File
@@ -130,7 +130,7 @@ fn handle(root: &ViewRoot, request: Request) -> Result<()> {
if let Some(first) = root.files.first() {
let rel = first.to_string_lossy().replace('\\', "/");
let resolved = resolve_rel(root, &rel)?;
let vm = build_file_view(&resolved, &rel, &[])?;
let vm = build_file_view(root, &resolved, &rel, &[], true)?;
let body = page_file(&root.files, &rel, &vm, &LinkMode::Live);
respond_html(request, body)
} else {
@@ -143,7 +143,7 @@ fn handle(root: &ViewRoot, request: Request) -> Result<()> {
let stdin_raw = query_param(query, "stdin").unwrap_or_default();
let stdin_lines = split_stdin_text(&stdin_raw);
let resolved = resolve_rel(root, &rel)?;
let vm = build_file_view(&resolved, &rel, &stdin_lines)?;
let vm = build_file_view(root, &resolved, &rel, &stdin_lines, true)?;
let body = page_file(&root.files, &rel, &vm, &LinkMode::Live);
respond_html(request, body)
}
@@ -160,9 +160,11 @@ fn handle(root: &ViewRoot, request: Request) -> Result<()> {
}
pub(crate) fn build_file_view(
root: &ViewRoot,
abs: &Path,
rel: &str,
stdin_lines: &[String],
live: bool,
) -> Result<FileViewModel> {
let source = fs::read_to_string(abs).with_context(|| format!("read {}", abs.display()))?;
let structure = match crate::load::load_module(abs) {
@@ -173,10 +175,12 @@ pub(crate) fn build_file_view(
),
};
let effective = effective_stdin(&source, stdin_lines);
let opts = RunOptions {
stdin_lines: effective.clone(),
..RunOptions::default()
};
// Same host caps as `marqdo run`. Soft exit + sleep clamp only.
let mut opts = RunOptions::default();
opts.stdin_lines = effective.clone();
opts.sleep_limit_ms = if live { Some(30_000) } else { Some(0) };
// Optional: sandbox to the whole view tree so sibling folders are reachable.
opts.fs_root = Some(root.root.clone());
let (stdout, stderr, ok) = match run_file_capture(abs, &opts) {
Ok(cap) => (cap.stdout, String::new(), true),
Err(e) => (
+1 -1
View File
@@ -25,7 +25,7 @@ pub fn write_static(opts: OutputOptions) -> Result<()> {
for rel_pb in &root.files {
let rel = rel_pb.to_string_lossy().replace('\\', "/");
let abs = resolve_abs(&root, &rel)?;
let mut vm = build_file_view(&abs, &rel, &[])?;
let mut vm = build_file_view(&root, &abs, &rel, &[], false)?;
if opts.no_exec {
vm.stdout.clear();
vm.stderr = "execution skipped (--no-exec)".into();
+42
View File
@@ -546,6 +546,48 @@ fn view_output_writes_html() {
assert!(dir.join("pages").join("hello.mq.md.html").exists());
}
#[test]
fn lib_fs_read() {
assert_out("tests/lib/fs-read.mq.md", "exists\nhello-lib");
}
#[test]
fn lib_fs_read_zh() {
assert_out("tests/lib/文件-读.mq.md", "存在\nhello-lib");
}
#[test]
fn lib_time_format() {
assert_out("tests/lib/time-format.mq.md", "1970-01-01\n0");
}
#[test]
fn lib_json_roundtrip() {
assert_out(
"tests/lib/json-roundtrip.mq.md",
"map\n1\n{\"a\":1,\"b\":\"x\"}",
);
}
#[test]
fn lib_sys_cwd() {
assert_out("tests/lib/sys-cwd.mq.md", "cwd-ok");
}
#[test]
fn lib_net_encode() {
assert_out("tests/lib/net-encode.mq.md", "a+b");
}
#[test]
fn bytecode_lib_json() {
assert_out_backend(
"tests/lib/json-roundtrip.mq.md",
"bytecode",
"map\n1\n{\"a\":1,\"b\":\"x\"}",
);
}
fn tempfile_dir(prefix: &str) -> std::path::PathBuf {
let dir = std::env::temp_dir().join(format!(
"{prefix}-{}",
+1
View File
@@ -0,0 +1 @@
hello-lib
+1
View File
@@ -0,0 +1 @@
{"a":1,"b":"x"}
+17
View File
@@ -0,0 +1,17 @@
---
title: fs read/exists
> lib/fs.mq.md
---
# main
*`ok` = > exists path=hello.txt *
+ `ok`
> print text=exists
+ *
> print text=missing
*`t` = > read_text path=hello.txt *
> print text=`t`
+1
View File
@@ -0,0 +1 @@
hello-lib
+23
View File
@@ -0,0 +1,23 @@
---
title: json roundtrip
> lib/fs.mq.md
> lib/json.mq.md
---
# main
*`raw` = > read_text path=sample.json *
*`obj` = > parse text=`raw` *
*`ty` = > type `obj` *
> print text=`ty`
*`a` = > get value=`obj` key=a *
> print text=`a`
*`out` = > stringify value=`obj` *
> print text=`out`
+10
View File
@@ -0,0 +1,10 @@
---
title: net url_encode
> lib/net.mq.md
---
# main
*`e` = > url_encode text=a b *
> print text=`e`
+1
View File
@@ -0,0 +1 @@
{"a":1,"b":"x"}
+15
View File
@@ -0,0 +1,15 @@
---
title: sys cwd
> lib/sys.mq.md
---
# main
*`d` = > cwd *
*`n` = > len `d` *
+ `n` > 0
> print text=cwd-ok
+ *
> print text=cwd-empty
+16
View File
@@ -0,0 +1,16 @@
---
title: time format/parse
> lib/time.mq.md
---
# main
*`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
+17
View File
@@ -0,0 +1,17 @@
---
title: 中文文件库
> lib/文件.mq.md
---
# main
*`有` = > 存在 路径=hello.txt *
+ `有`
> 打印 内容=存在
+ *
> 打印 内容=缺失
*`t` = > 读文本 路径=hello.txt *
> 打印 内容=`t`