Define mid-stdlib admission rules and a phased roadmap so general primitives land in lib/ instead of ABI plugins. Co-authored-by: Cursor <cursoragent@cursor.com>
4.8 KiB
4.8 KiB
标准库(P2)
| 状态 | S0–S3 + 核心 L1 已落地 · 中层 L1(Mid)规划中 |
| 日期 | 2026-09-07 |
| 相关 | keywords.md · objects.md · call-arguments.md · stdlib-i18n.md · stdlib-modules.md · stdlib-mid.md · module-namespace.md · ext-abi.md |
多语言库命名:见 stdlib-i18n.md(不设
lang:;中英分文件)。
L1 模块清单(含 math/foreign/plugin):见 stdlib-modules.md。
中层标准库(数个版本):通用原语沉lib/、减少「事事插件」——设计 stdlib-mid.md · 路线 roadmap/stdlib-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 / csv / … — 仍在 lib/,见 stdlib-mid.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
import table:lib/table.mq.md
---
调用示例:> time.now_unix、> json.parse text=…。需要本地短名时用 导入 format(冲突:time.format`(冲突 → 硬错误)。
std/text.mq.md 等价于 lib/text.mq.md。解析顺序:
- 相对当前文件
MARQDO_LIB(可指向lib目录或仓库根)- 当前工作目录的
lib/ - 可执行文件附近的
lib/(含cargo run的相对路径) - 内嵌 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。