Frontmatter imports are now valid YAML (`import:` / `导入:` with bind→target entries), removing spaced keys. Add `marqdo migrate imports`, hard-error the old one-liner form, and migrate lib/ext/examples/tests/docs accordingly. Co-authored-by: Cursor <cursoragent@cursor.com>
5.2 KiB
5.2 KiB
标准库多语言命名(草案)
| 状态 | 草案(先文档、后实现) |
| 日期 | 2026-08-04 |
| 原则 | 不指定语言;靠库文件名区分中英(及日后其它语言) |
| 相关 | stdlib.md · stdlib-modules.md · keywords.md · keywords-i18n.md · user-site.md |
1. 要解决什么
- 内置(解释器里的名字)必须少而精;更多能力放进可
>导入的标准库。 - 标准库需要中英两套 API(函数名不同),并方便以后再加日文、西班牙文等。
- 不要用 frontmatter
lang:、环境变量默认语言、或「同一导入路径再解析语言」——那是负累,也不符合「文档即代码」的直观性。
2. 方案(采用)
导入哪个库文件,就用哪套函数名。
文件名本身表达语言;解释器只做路径解析,不做语言推断。
2.1 推荐:库名用目标语言书写
| 导入 | 库内函数名(示例) |
|---|---|
import text:lib/text.mq.md |
trim · split · join |
导入 文本:lib/文本.mq.md |
去空白 · 拆分 · 拼接 |
import table:lib/table.mq.md |
put · rows · row_at · list/map(见 stdlib-table.md) |
导入 表:lib/表.mq.md |
行数 · 取行 |
示例:
---
import:
text: lib/text.mq.md
---
# main
*`xs` = > split value=a,b,c sep=,*
---
导入:
文本: lib/文本.mq.md
---
# main
*`xs` = > 拆分 s=a,b,c sep=,*
读者看到导入路径就能知道后面该用英文还是中文函数名——无需再声明语言。
2.2 可选:同概念用后缀区分(同目录、同「概念」)
若希望「同一概念」在文件名上仍共享拉丁词根,可用:
| 导入 | 含义 |
|---|---|
import text-en:lib/text-en.mq.md |
英文 API |
import text-zh:lib/text-zh.mq.md |
中文 API |
这与 §2.1 等价可选,不是第二套解析器:仍然是「写哪个路径就加载哪个文件」。
优先推荐 §2.1(text / 文本),后缀形式留给需要 ASCII-only 路径的环境。
2.3 明确不做
| 不做 | 原因 |
|---|---|
lang: zh / MARQDO_LANG |
隐式状态,难读、难测 |
> std/text 再按语言展开 |
多一次魔法 |
| 同一文件内中英函数双份导出 | 遮蔽与文档混乱 |
| 强制用户只许用中文或只许用英文 | Marqdo 本就多语言友好 |
2.4 特例:JSON
JSON 为专有缩写,不强求中文库名或中文 API 翻译。官方只提供:
lib/json.mq.md # 中英文档均 `import json:lib/json.mq.md`;函数 parse / stringify / get / keys
不设 lib/数据.mq.md 等平行文件。其余模块仍遵守 §2.1。详见 stdlib-modules.md §3.4。
3. 与「少而精内置」的边界
| 层 | 内容 | 如何获得 |
|---|---|---|
| 内置(L0) | 极少:print input len str int(及语言字面量关键字) |
直接调用,无需导入 |
| 标准库(L1) | 文本/表等扩展 API;通常中英各一套文件、各一套函数名(JSON 例外:仅 lib/json.mq.md) |
frontmatter import …:lib/… |
| 宿主原语(实现细节) | 若 trim/split 等暂由解释器实现 |
仅供标准库包装调用;文档与用户站引导走 L1,不鼓励当「关键字」堆砌 |
日后若某能力足够「核心」,可再升格为 L0;升格前先留在 L1。
4. 目录与扩展约定
lib/
text.mq.md / 文本.mq.md
table.mq.md / 表.mq.md
# 本波:fs/文件 · sys/系统 · time/时间 · json(中英同文件)· net/网络
# 暂缓:math/数学 · foreign/外联
# 其它语言:texte.mq.md / テキスト.mq.md …
扩展新语言时:
- 新加一个库文件(文件名用该语言或
概念-xx)。 - 库内函数名用该语言习惯。
- 文档表增加一行映射;无需改解释器语言开关。
导入解析仍沿用现有规则:相对路径 → 官方 lib/ 根(MARQDO_LIB / 工作区 lib/ 等),不增加语言分支。
5. 文档与示例义务
- 用户站:英/中库各一页(或同页两小节),导入路径与调用名并排;JSON 可共用一页、同一导入。
- 金样例:分文件模块中英导入至少各一条;JSON 测
lib/json.mq.md即可。 - keywords.md 只列 L0;L1 指向本文 + stdlib.md + stdlib-modules.md。
6. 实现备忘(暂不开发)
实现阶段仅需:
- 落地
lib/text.mq.md与lib/文本.mq.md(及 table / 表)两套文件与函数名。 - 更新导入示例与金样例;删除「仅中文库名」的单轨示例。
- 不要实现
lang:、默认语言、或std/text自动选语言。
若历史上加过 Module.lang / lang: 解析,应撤回,与本草案对齐。
7. 一句话
标准库用文件名区分语言(导入即选择);JSON 为缩写特例,中英共用 lib/json.mq.md——无语言开关。