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>
149 lines
5.2 KiB
Markdown
149 lines
5.2 KiB
Markdown
# 标准库多语言命名(草案)
|
||
|
||
| | |
|
||
|---|---|
|
||
| 状态 | **草案(先文档、后实现)** |
|
||
| 日期 | 2026-08-04 |
|
||
| 原则 | **不指定语言**;靠**库文件名**区分中英(及日后其它语言) |
|
||
| 相关 | [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) |
|
||
|
||
---
|
||
|
||
## 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](stdlib-table.md)) |
|
||
| `导入 表:lib/表.mq.md` | `行数` · `取行` |
|
||
|
||
示例:
|
||
|
||
```markdown
|
||
---
|
||
import:
|
||
text: lib/text.mq.md
|
||
---
|
||
|
||
# main
|
||
*`xs` = > split value=a,b,c sep=,*
|
||
```
|
||
|
||
```markdown
|
||
---
|
||
导入:
|
||
文本: 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 翻译。官方只提供:
|
||
|
||
```text
|
||
lib/json.mq.md # 中英文档均 `import json: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;**通常**中英各一套文件、各一套函数名(**JSON 例外**:仅 `lib/json.mq.md`) | frontmatter `import …:lib/…` |
|
||
| **宿主原语(实现细节)** | 若 `trim`/`split` 等暂由解释器实现 | 仅供标准库包装调用;**文档与用户站引导走 L1**,不鼓励当「关键字」堆砌 |
|
||
|
||
日后若某能力足够「核心」,可再升格为 L0;升格前先留在 L1。
|
||
|
||
---
|
||
|
||
## 4. 目录与扩展约定
|
||
|
||
```text
|
||
lib/
|
||
text.mq.md / 文本.mq.md
|
||
table.mq.md / 表.mq.md
|
||
# 本波:fs/文件 · sys/系统 · time/时间 · json(中英同文件)· net/网络
|
||
# 暂缓:math/数学 · foreign/外联
|
||
# 其它语言:texte.mq.md / テキスト.mq.md …
|
||
```
|
||
|
||
扩展新语言时:
|
||
|
||
1. **新加一个库文件**(文件名用该语言或 `概念-xx`)。
|
||
2. 库内函数名用该语言习惯。
|
||
3. 文档表增加一行映射;**无需改解释器语言开关**。
|
||
|
||
导入解析仍沿用现有规则:相对路径 → 官方 `lib/` 根(`MARQDO_LIB` / 工作区 `lib/` 等),**不增加语言分支**。
|
||
|
||
---
|
||
|
||
## 5. 文档与示例义务
|
||
|
||
- 用户站:英/中库各一页(或同页两小节),导入路径与调用名并排;**JSON** 可共用一页、同一导入。
|
||
- 金样例:分文件模块中英导入至少各一条;JSON 测 `lib/json.mq.md` 即可。
|
||
- [keywords.md](keywords.md) 只列 L0;L1 指向本文 + [stdlib.md](stdlib.md) + [stdlib-modules.md](stdlib-modules.md)。
|
||
|
||
---
|
||
|
||
## 6. 实现备忘(暂不开发)
|
||
|
||
实现阶段仅需:
|
||
|
||
1. 落地 `lib/text.mq.md` 与 `lib/文本.mq.md`(及 table / 表)两套文件与函数名。
|
||
2. 更新导入示例与金样例;删除「仅中文库名」的单轨示例。
|
||
3. **不要**实现 `lang:`、默认语言、或 `std/text` 自动选语言。
|
||
|
||
若历史上加过 `Module.lang` / `lang:` 解析,应撤回,与本草案对齐。
|
||
|
||
---
|
||
|
||
## 7. 一句话
|
||
|
||
**标准库用文件名区分语言(导入即选择);JSON 为缩写特例,中英共用 `lib/json.mq.md`——无语言开关。**
|