Files
marqdo/doc/roadmap/tables-maps-footnotes.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

9.3 KiB
Executable File
Raw Permalink Blame History

表格语义打磨:列表 · 字典 · 嵌套 · 脚注取元(未来规划)

状态 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. 目标

  1. 竖表继续表示列表(兼容现有金样)。
  2. 横表(多列表头 + 数据行)表示字典及「字典 ↔ 列表」嵌套。
  3. 用 Markdown 脚注外形 做列表下标 / 字典键的取元(表达式级)。
  4. 不引入 [] 下标关键字风暴;少而精,与「标记即语法」一致。

非目标:

  • 完整电子表格公式引擎
  • 用表声明对象字段 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 英文

规则:

  1. 标记列不进入记录字段(数据格可写行号给人看)。
  2. 其余列 → 每行一个 Map;整体为 List。
  3. 须至少有一列字段(仅 | 行 | → 诊断)。
  4. 数据行数任意(含 0 → 空列表;1 行仍是 List of one Map,不是列向 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  数据单元格 = 表达式(同调用实参值语法)  ✅

验收:

  1. tests/structure/collection.mq.md 行为不变。
  2. 新金样:collection-map.mq.md、collection-map-list.mq.md、footnote-index.mq.md。
  3. 错误下标 / 缺键带 line:col。
  4. 双后端(tree / bytecode)一致。
  5. T5: 单元格 `var` / 算术;URL 与 gpt-4o-mini 仍为文本;设计见 table-cell-expressions.md。

7. 教学对照(写入 Skill 的素材)

几何 含义 取元
单列竖表 列表 `a`[^1]
多列 + 一行 字典 `m`[^键]
多列 + 多行 字典 → 列表 `m`[^键][^1]
首列 @/行/row 记录列表 `r`[^1][^字段]

竖表表头是「元素名」;横表表头是「键名」——几何决定角色,减少「这张表到底是啥」的歧义。


8. 开放点

  1. 表头重复列名:报错还是后缀 _2?建议 报错。
  2. 数字表头:字典键为文本 "1" 还是整数?建议 文本(与单元格一致)。
  3. 脚注 1-based 与宿主语言习惯(0-based)的文档警示。
  4. 字节码:Index / KeyGet 操作码是否与 T2 同批。

9. 与其它规划的关系

文档 关系
object-inheritance.md 正交;表不表示类字段 schema
agent-streaming.md 正交;事件列表可用竖表金样演示 foreach
okf-near-match.md 正交