Files
marqdo/examples/code-as-docs/index.mq.md
T
cflmy 4488a3cb70 feat(migrate): M7 迁移与版本门 — per-file markup + migrate labels + 全仓迁移
原计划的"翻转默认 + 旧形硬报错"不可行:`[键](集合)` 与 `[描述](实现)` 外形相同,
翻转会让 506 处取元静默变义,硬报错又拿不到证据。改为**按文件声明**。

一、per-file markup
- frontmatter `markup: occlusion`(或 `标记: 遮蔽`)决定该文件模式
- load.rs 先取模式,用 parse::expr::with_markup(线程局部压栈)包住解析
- 同一进程可同时加载两种模式的文件(imports);MARQDO_MARKUP 仍作进程默认
- 好处:迁移逐文件、可增量、可回滚,不存在半迁移的静默错义

二、`marqdo migrate labels [--write|--json]`
改写规则:
  [键](集合)      → [键](access(集合, "键"))
  [`名`](集合)    → [名](access(集合, `名`))
  - [项](集合)    → - [项](遍历 集合 为 项)

安全模型:改写 → 重解析 → 证明等价 → 才写
- 原文件按 classic 解析得 AST-A;改写后按 occlusion 解析得 AST-B
- 反归一化 B(标签与键同名且 payload 为 access 的遮蔽还原成 Index)
- Debug(A) == Debug(反归一化(B))(抹掉行号)才写入,否则原文件一字不动

只改代码行(LineKind::Code);表格行只改 **…** 单元格,散文 markdown 链接不碰;
链式索引由内向外改写,已迁移的有守卫不二次改。

三、access 提升为宿主函数 HostFn::Access(u16 id 212)
与旧取元逐字一致(Map 按键 / List 1-based / 缺键 missing map key);
进 HostFn 是为了两个后端共用同一实现,interp 里的特例已删除。

四、顺带修的两处真实语义缺陷
1. payload 继承外层"文本模式":`f text=[k](access(c,k))` 中 access 不被当调用
   → `()` 内永远允许 callee(args)
2. 遮蔽形状判定过宽:`[问候] ([格式化] "Bo")` 误判为遮蔽
   → 要求 `]` 后紧跟 `(`,否则落回方括号调用

五、全仓迁移结果
migrate labels: 256 index, 23 loop, 80 file written;0 文件被等价性拒绝;
迁移后 cargo test --release → 604 passed / 0 failed;再跑迁移幂等。

等价性检查先后抓出 4 类改写 bug(表格散文链接、payload 文本模式、链式索引、
遮蔽与方括号调用混淆),每类都是先拦下再修工具,未污染文件。

测试:6 个单测 + 3 个集成(干跑不写盘 / 写入后运行输出不变且幂等 /
等价失败文件不动);全量 604 passed / 0 failed(M3 后 595 + 9);双后端一致。

文档:doc/design/change-m7-migration.md
2026-10-22 15:33:31 +08:00

2.3 KiB
Raw Permalink Blame History

markup, title, description
markup title description
occlusion 代码即文档 · 周末咖啡手账 一份可读可跑的周末手账:菜单是表,计价写在段落里,结账读起来像日记。

周六的咖啡馆手账——下面既是给人看的说明,也是可以 marqdo run 的程序。 说明性的加粗只是强调;真正算账的步骤也用粗体写在句子里,算完的值用斜体交回去。


单价

一杯标价为价的饮品,默认杯数=1。先把总额 = 价 * 杯数算清,再返回总额。

会员折

会员单要原价原价;店里默认八五折,记作折扣=0.85。 先算应付 = 原价 * 折扣,再返回应付。

结账摘要

客人点了品名,单价价,杯数杯数=1;是否会员=False。

按杯数问单价:小计 = 单价 价=价 杯数=杯数。

  1. 会员 实付 = 会员折 原价=小计 标签 = "会员价"

实付 = 小计 标签 = "原价"

对账时拼成一句人话:

文案 = 品名 + " ×" + 杯数 + " → " + 标签 + " " + 实付 文案

印章加一

积分卡上的印,每喝一杯就印 = 印 + 1,接着返回印。

main

今日黑板价目——表格给人扫一眼,程序当字典用:

菜单 =

美式 拿铁 燕麦拿铁
18 28 32

上午来了位会员,点两杯拿铁。品名写进名,价钱从菜单里取:

名 = "拿铁" 价 = [名](access(菜单, 名)) 摘要 = [结账摘要] 品名=名 价=价 杯数=2 会员=True 打印 内容=摘要

旁桌只要一杯普通美式,对照一下原价:

对照 = [结账摘要] 品名="美式" 价=美式) 打印 内容=对照


下午把外卖单抄成行表,一行一行结:

今日订单 =

@ 品名 单价 杯数 会员
1 燕麦拿铁 32 1 True
2 美式 18 2 False
  • [行](遍历 今日订单 为 行) 一行 = 结账摘要 品名=品名) 价=单价) 杯数=杯数) 会员=会员) 打印 内容=一行

打烊前给积分卡盖一个章:

印 = 41 印 = 印章加一 印=印 打印 内容=印