- 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。
9.3 KiB
Executable File
表格语义打磨:列表 · 字典 · 嵌套 · 脚注取元(未来规划)
| 状态 | T0–T5 已落地(单元格表达式见 table-cell-expressions.md) |
| 日期 | 2026-08-12 |
| 相关 | markdown-mapping.md §9 · table-cell-expressions.md · objects.md · stdlib.md(lib/table) · keywords.md |
| 现状金样 | tests/structure/collection.mq.md |
1. 问题
1.1 今日表格 =「竖表 → 列表」
`篮子` =
| 果 |
|----|
| 苹果 |
| 梨 |
| 桃 |
语义(已落地):绑定为列表(列值);表头名供 [`果`](`篮子`) 遍历。
单列表头是当前唯一一等集合外形;没有一等「横表 = 字典」。
1.2 缺字典外形与嵌套
用户期望:GFM 表的两种几何对应两种结构,并允许嵌套——这样「多行表格」才有稳定、可教的含义。
1.3 不能按下标 / 键直接取元
今日要从列表取第 n 项,往往只能遍历或走 lib/table(row_at 等),语言级缺少与 Markdown 同构的取元语法。字典亦然。
2. 目标
- 竖表继续表示列表(兼容现有金样)。
- 横表(多列表头 + 数据行)表示字典及「字典 ↔ 列表」嵌套。
- 用 Markdown 脚注外形 做列表下标 / 字典键的取元(表达式级)。
- 不引入
[]下标关键字风暴;少而精,与「标记即语法」一致。
非目标:
- 完整电子表格公式引擎
- 用表声明对象字段 schema(仍见 objects 非目标;与数据集合分开)
- 破坏现有单列竖表金样
3. 表格几何 → 值(锁定提案)
判定在 绑定右侧的 GFM 表 上做(`名` = 后接表)。
3.1 竖表 → 列表(现状,保留)
形状: 恰好 1 列。
`篮子` =
| 果 |
|----|
| 苹果 |
| 梨 |
| 桃 |
| 结果 | 说明 |
|---|---|
| 值 | List:["苹果","梨","桃"] |
| 表头 | 元素逻辑名(foreach 绑定名);不进入列表元素 |
3.2 横表单数据行 → 字典
形状: ≥2 列,且 恰好 1 行数据(表头 + 分隔 + 一行)。
`分类` =
| 苹果 | 黄瓜 | 鼠标 |
|------|------|------|
| 水果 | 蔬菜 | 数码用品 |
| 结果 | 说明 |
|---|---|
| 值 | Map:苹果→水果, 黄瓜→蔬菜, 鼠标→数码用品 |
| 键 | 表头单元格文本(规范化空白后) |
| 值 | 唯一数据行对应列 |
3.3 横表多数据行 → 字典套列表(默认)
形状: ≥2 列,且 ≥2 行数据。
`货架` =
| 苹果 | 黄瓜 |
|------|------|
| 红富士 | 青瓜 |
| 嘎啦 | 黄瓜条 |
默认语义(锁定):列向聚合
{
"苹果": ["红富士", "嘎啦"],
"黄瓜": ["青瓜", "黄瓜条"]
}
即:键 = 表头,值 = 该列数据行组成的列表。
这与竖表「一列 = 一列表」在多列时自然推广,嵌套外形稳定。
备选语义(不默认):行向记录列表
[
{"苹果":"红富士","黄瓜":"青瓜"},
{"苹果":"嘎啦","黄瓜":"黄瓜条"}
]
更像 SQL / CSV。若未来需要,用显式标记区分(见 §3.5),不得与默认列向字典静默混用。
3.4 单列多行 vs 多列
| 列数 | 数据行 | 值类型 |
|---|---|---|
| 1 | ≥0 | List |
| ≥2 | 1 | Map(标量值) |
| ≥2 | ≥2 | Map(值均为 List) |
| ≥2 | 0 | Map(键存在,值空列表或错误——开工时锁定为「空列表」) |
3.5 显式形态标记(行向记录)— 已落地
首列表头为下列之一时,整表改为行向(不静默混用列向默认):
| 标记 | 说明 |
|---|---|
@ |
ASCII 短标记 |
行 |
中文 |
row |
英文 |
规则:
- 标记列不进入记录字段(数据格可写行号给人看)。
- 其余列 → 每行一个
Map;整体为List。 - 须至少有一列字段(仅
| 行 |→ 诊断)。 - 数据行数任意(含 0 → 空列表;1 行仍是
Listof oneMap,不是列向Map)。
`订单` =
| 行 | 品名 | 数量 |
|----|------|------|
| 1 | 苹果 | 2 |
| 2 | 梨 | 3 |
→ [{品名: 苹果, 数量: 2}, {品名: 梨, 数量: 3}]。取元:`订单`[^1][^品名]。
4. 脚注取元(历史 · 过渡保留)
主语法已切换为链接形
[键](集合),见 collection-access-link.md。
本节集合[^键]仍由运行时接受;新代码请写链接形。
4.1 为何曾用脚注外形
- Markdown 已有
[^…]引用形态,读者不陌生。 - 避免
篮子[0]与链接 / 图片语法纠缠。 - 与「标识符反引号」组合清晰:
`篮子`[^1]。
4.2 列表:按下标
*`第一` = `篮子`[^1] *
> print text=`第一`
| 约定 | 选择(提案) |
|---|---|
| 下标基准 | 1-based(与 Markdown / 人类表格行语感一致;脚注 [^1] 即第一项) |
[^0] |
报错(保留 0 不用)或日后表示「最后一项」—— v1 报错 |
| 越界 | 清晰诊断 path:line:col |
4.3 字典:按键
键为脚注标签文本(推荐与表头一致;允许纯数字键,如基矢标签 00)。基名可写 `概率`[^00] 或 概率[^00](紧跟 [^ 时可省略反引号):
*`种` = `分类`[^苹果] *
*`p00` = `概率`[^00] *
> print text=`种`
| 规则 | 说明 |
|---|---|
[^苹果] |
键文本 苹果 |
[^00] / [^1] |
键文本 00 / 1(不是「第 n 个 map 条目」) |
| 含空格的键 | 允许 [^数码用品];极端键用引号策略开工前定 |
| 缺失键 | 报错或 None——建议 v1 报错(少静默) |
4.4 嵌套取元
列向字典套列表:
*`货架` = …多行横表… *
*`第一种苹果` = `货架`[^苹果][^1] *
从左到右:先键、再下标。
类型不对(对 List 用非数字键名脚注)→ 诊断。Map 上的纯数字标签按键名解析。
4.5 与 GFM「定义脚注」正文
标准 Markdown 文末 [^1]: 说明 是注释/文献,不是取元。
规则:
- 表达式位置的
`名`[^…]→ 取元。 - 文末脚注定义块 → 仍作注释(或不支持,避免混用)。
- 不要求为每个
[^1]写定义;Marqdo 取元不依赖定义块。
4.6 与 lib/table 关系
| 层 | 职责 |
|---|---|
| 语言脚注取元 | 一等、短、金样覆盖 |
lib/table |
行列切片、整表变换;可逐步把 row_at 文档改为「等价于脚注」 |
5. foreach 与字典
今日:[果](篮子) / [`果`](`篮子`) 遍历列表(裸名与反引号均可)。
扩展草案:
| 集合 | 遍历 |
|---|---|
| List | 不变,项为元素 |
| Map | [`键`](`映射`) 遍历键;或 [`对`](`映射`) 若引入对类型—— v1 建议 遍历键,值用 `映射`[^…] / 辅助 |
具体键值对遍历语法开工前写一小段进 mapping;避免与链接外形 [`x`](`y`) 冲突(今日已是 foreach)。
6. 推荐落地顺序
T0 横表单行 → Map;金样;竖表回归 ✅
T1 横表多行 → Map of List(列向);嵌套金样 ✅
T2 脚注取元:List [^n]、Map [^键]、链式 ✅
T3 文档:markdown-mapping §9;Skill / examples;table 库 ✅
T4 行向记录表:首列 `@` / `行` / `row` ✅
T5 数据单元格 = 表达式(同调用实参值语法) ✅
验收:
tests/structure/collection.mq.md行为不变。- 新金样:
collection-map.mq.md、collection-map-list.mq.md、footnote-index.mq.md。 - 错误下标 / 缺键带
line:col。 - 双后端(tree / bytecode)一致。
- T5: 单元格
`var`/ 算术;URL 与gpt-4o-mini仍为文本;设计见 table-cell-expressions.md。
7. 教学对照(写入 Skill 的素材)
| 几何 | 含义 | 取元 |
|---|---|---|
| 单列竖表 | 列表 | `a`[^1] |
| 多列 + 一行 | 字典 | `m`[^键] |
| 多列 + 多行 | 字典 → 列表 | `m`[^键][^1] |
首列 @/行/row |
记录列表 | `r`[^1][^字段] |
竖表表头是「元素名」;横表表头是「键名」——几何决定角色,减少「这张表到底是啥」的歧义。
8. 开放点
- 表头重复列名:报错还是后缀
_2?建议 报错。 - 数字表头:字典键为文本
"1"还是整数?建议 文本(与单元格一致)。 - 脚注 1-based 与宿主语言习惯(0-based)的文档警示。
- 字节码:
Index/KeyGet操作码是否与 T2 同批。
9. 与其它规划的关系
| 文档 | 关系 |
|---|---|
| object-inheritance.md | 正交;表不表示类字段 schema |
| agent-streaming.md | 正交;事件列表可用竖表金样演示 foreach |
| okf-near-match.md | 正交 |