Files
marqdo/doc/design/stdlib.md
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

5.4 KiB
Executable File
Raw Permalink Blame History

标准库(P2)

状态 S0–S3 + 核心 L1 + Mid M1–M6 + Mid2 M7–M10 已落地
日期 2026-09-09
相关 keywords.md · objects.md · call-arguments.md · lib-code-as-docs.md · stdlib-i18n.md · stdlib-modules.md · stdlib-mid.md · stdlib-mid2.md · module-namespace.md · ext-abi.md

库写法(代码即文档):lib-code-as-docs.md · roadmap/lib-ext-code-as-docs.md。
多语言库命名:见 stdlib-i18n.md(不设 lang:;中英分文件)。
L1 模块清单(含 math/foreign/plugin):见 stdlib-modules.md。
中层标准库 Mid(M1–M6):已落地——stdlib-mid.md · roadmap/stdlib-mid.md。
中层第二波 Mid2(M7–M10):已落地——stdlib-mid2.md · roadmap/stdlib-mid2.md · 缺口 stdlib-gaps-after-mid.md。
ext/ 不是 stdlib:官方可选扩展见 ext-llm.md / ext-agent.md。


1. 分层

层 内容
L0 内置 解释器内:print input len str int type trim split join at(type 可含 map)
L1 核心 已有 lib/:fs/sys/time/json/net/math/foreign/plugin/table/text/…
L1 中层(Mid) 已落地 re / encoding / path / hash / secrets / csv / text++ / table++ / cli / log / uuid — stdlib-mid.md
L1 Mid2 已落地 datetime / url / toml / html / fs++ / stats / log.fields — stdlib-mid2.md
官方 ext ext/(.mq.md + 可选原生插件);MARQDO_EXT;不属于 L1;插件仅领域热路径
L2 catalog / 用户站收录(随发版);应主要靠核心+中层、默认无插件

2. 内置一览(S0 + S1)

名 形参 结果
len value 文本标量数或列表长度
str value 显示文本
int value 整数(失败 → 诊断)
type value none/bool/int/text/list/map
trim value 去首尾空白
split value, sep 文本列表
join value, sep 拼接文本
at value, index 列表下标(越界 → None)

表(单列表格)在运行时是 list:行数用 len,取行用 at。


3. 官方库导入(S2)

Frontmatter 导入绑定库名(默认 = 文件名茎;as / 作为 可改)。成员经点号路径调用(time.parse、json.get),不倒进全局短名。完整语义见 module-namespace.md。

---
import:
  text: lib/text.mq.md
  table: lib/table.mq.md
---

调用示例:> time.now_unix、> json.parse text=…。需要本地短名时用 导入 format(冲突:time.format`(冲突 → 硬错误)。

std/text.mq.md 等价于 lib/text.mq.md。解析顺序:

  1. 相对当前文件
  2. MARQDO_LIB(可指向 lib 目录或仓库根)
  3. 当前工作目录的 lib/
  4. 可执行文件附近的 lib/(含 cargo run 的相对路径)
  5. 内嵌 stdlib(v0.1.2+,编译进二进制;无磁盘 lib/ 时自动使用)

当前模块(API 多为 ## 自由函数;见 objects.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…、load_dotenv… / 取环境…、加载环境…
lib/json.mq.md parse stringify get keys quote(中英同文件)
lib/net.mq.md / lib/网络.mq.md http_get…(HTTPS)/ 获取…
lib/math.mq.md / lib/数学.mq.md 数值 / 随机 / 公式 / 绘图
lib/foreign.mq.md / lib/外联.mq.md 具名围栏外联
lib/plugin.mq.md / lib/插件.mq.md load / unload / list(原生 ABI)
lib/writeback.mq.md / lib/自写回.mq.md record get clear list
lib/subtask.mq.md / lib/子任务.mq.md spawn poll wait kill wait_all
lib/text.mq.md str_trim str_split str_join
lib/文本.mq.md 去空白 拆分 拼接
lib/table.mq.md put 为首选写入;rows/row_at 及完整 list/map API — 见 stdlib-table.md
lib/表.mq.md 改 为首选写入;行数/取行 及完整 list/map API

完整清单见 stdlib-modules.md。


4. 转换错误约定(S3)

用户可见失败统一为:

path:line:col: message

内置转换相关文案(稳定子集,金样例断言):

情况 message
非法整数文本 cannot convert to int: "…"
int 类型不对 int needs int, bool, or text
len 类型不对 len needs text or list
trim 非文本 trim needs text
split/join 参数类型 split needs text value 等
空分隔符 split sep must not be empty

不引入独立异常类型对象;一律走 Diagnostic。