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

88 lines
2.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
markup: occlusion
title: 代码即文档 · 周末咖啡手账
description: >-
一份可读可跑的周末手账:菜单是表,计价写在段落里,结账读起来像日记。
---
周六的咖啡馆手账——下面既是给人看的说明,也是可以 `marqdo run` 的程序。
**说明**性的加粗只是强调;真正算账的步骤也用粗体写在句子里,算完的值用斜体交回去。
---
## 单价
一杯标价为`价`的饮品,默认`杯数`=1。先把**总额 = 价 * 杯数**算清,再返回*总额*。
## 会员折
会员单要原价`原价`;店里默认八五折,记作`折扣`=0.85。
先算**应付 = 原价 * 折扣**,再返回*应付*。
## 结账摘要
客人点了`品名`,单价`价`,杯数`杯数`=1;是否`会员`=False。
按杯数问单价:**小计 = 单价 价=`价` 杯数=`杯数`**。
1. `会员`
**实付 = 会员折 原价=`小计`**
**标签 = "会员价"**
2. *
**实付 = 小计**
**标签 = "原价"**
对账时拼成一句人话:
**文案 = 品名 + " ×" + 杯数 + " → " + 标签 + " " + 实付**
*文案*
## 印章加一
积分卡上的`印`,每喝一杯就**印 = 印 + 1**,接着返回*印*。
# main
今日黑板价目——表格给人扫一眼,程序当字典用:
`菜单` =
| 美式 | 拿铁 | 燕麦拿铁 |
|------|------|----------|
| 18 | 28 | 32 |
---
上午来了位会员,点两杯拿铁。品名写进`名`,价钱从菜单里取:
**名 = "拿铁"**
**价 = [名](access(菜单, `名`))**
**摘要 = [结账摘要] 品名=`名` 价=`价` 杯数=2 会员=True**
**打印 内容=`摘要`**
旁桌只要一杯普通美式,对照一下原价:
**对照 = [结账摘要] 品名="美式" 价=[美式](access(菜单, "美式"))**
**打印 内容=`对照`**
---
下午把外卖单抄成行表,一行一行结:
`今日订单` =
| @ | 品名 | 单价 | 杯数 | 会员 |
|---|------|------|------|------|
| 1 | 燕麦拿铁 | 32 | 1 | True |
| 2 | 美式 | 18 | 2 | False |
- [行](遍历 今日订单 为 行)
**一行 = 结账摘要 品名=[品名](access(行, "品名")) 价=[单价](access(行, "单价")) 杯数=[杯数](access(行, "杯数")) 会员=[会员](access(行, "会员"))**
**打印 内容=`一行`**
打烊前给积分卡盖一个章:
**印 = 41**
**印 = 印章加一 印=`印`**
**打印 内容=`印`**