- 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。
10 KiB
Executable File
markup, import, title, description
| markup | import | title | description | ||
|---|---|---|---|---|---|
| occlusion |
|
Marqdo 可读语法全景 | 一页看完全部现行语法:遮蔽、调用、取值、循环、分支、表格、契约 |
从仓库根目录执行:marqdo call examples/syntax-tour/index.mq.md main --effects output.write --json。
main
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | 本次演示实际得到的名字长度、求和结果、嵌套调用值及空载荷值 |
从本节开始按顺序执行一份完整程序;命令行可以直接 call 本文件的 main 得到计算记录;View 或 run 另行展示打印步骤。call 需要 output.write 授权,因为本例确实执行打印,但它的业务结果以返回记录为准。下方辅助函数也可以按自己的标题独立调用,不需要先理解一套另外维护的工具签名。执行位置中的变量会保存本轮实际结果,说明文字则交代这些结果为什么出现在这里。
变量、参数和字段名有不同职责。变量保存已经得到的值,参数把外部输入交给函数,字段名标识记录中的数据;看见同样的文字不能把三者混为一谈。读取已有值时使用反引号,文本字面值加引号,命令选项也遵守这个规则。表格先说明形态,再绑定为值;字段与返回契约则紧接对应标题,帮助读者在看实现前决定如何调用。
本例没有文件写入、网络请求或外联解释器。空载荷是刻意保留的教学桩:它返回空值并给出 warning,用来展示待补充逻辑如何被看见,而不是模拟搜索已经完成。默认分支也只是此例选择的业务规则,不代表库能够自行推断所有未知输入。循环会改变示例中的计数变量,返回会立即结束函数,所以所有后续演示都安排在最终返回之前。
一列表是列表,一行多列是记录;行记录集合使用首列标记区分。表头标识业务字段,标记列不成为业务值。需要按列保存多行数据时,应明确选择对应形态,不能只凭视觉排列猜运行时结构。
程序最后返回真实中间值,便于调用方逐项验证。打印文字是给人观察的另一条通道,不应再被解析成下一步的输入。要改变演示数据,先检查对应契约和索引约定,再重复实际调用;不能仅凭标签读起来正确就认定其中实现符合描述。
—— 1. 变量与插值 ——
我们先π = 3.14159,供下一步使用。 我们先名 = "Marqdo",供下一步使用。 我们先开 = True,供下一步使用。
随后我们**[显示当前步骤的结果](> print text="名字是名,π 约等于 π")**。
反引号取值,正文里的反引号是插值:
我们先长度 = 名字长度,供下一步使用。
随后我们**[显示当前步骤的结果](> print text="名 的长度是 长度")**。
—— 2. 函数:参数、返回、契约 ——
税率函数接收档位与金额,返回应缴税额。
随后我们**[执行 计税](> 计税 档位=2 金额=100)**。
税率表 =
| 档位 | 税率 |
|---|---|
| 1 | 0.03 |
| 2 | 0.1 |
| 3 | 0.2 |
—— 3. 调用形式 ——
随后我们**[显示当前步骤的结果](> print text="形态一:> 前缀 + 具名实参")**。
我们先甲 = 加(1 2),验证空格分隔的位置参数。 我们先乙 = [计算并保存 乙](加(1, 2)),供下一步使用。 我们先丙 = [计算并保存 丙](加(加(1, 2), 10)),供下一步使用。 丁 = 加一 号(31)
随后我们**[显示当前步骤的结果](> print text="形态二 括号位置实参:甲")。
随后我们[显示当前步骤的结果](> print text="形态三 括号逗号:乙")。
随后我们[显示当前步骤的结果](> print text="形态四 嵌套:丙")。
随后我们[显示当前步骤的结果](> print text="形态五 带空格的函数名:丁")**。
—— 4. 取值:access / at / get ——
篮子 =
| 果 |
|---|
| 苹果 |
| 梨 |
饮品价 =
| 拿铁 | 美式 |
|---|---|
| 28 | 18 |
我们先取第一 = 第一颗),供下一步使用。 我们先取配置 = 拿铁多少钱),供下一步使用。 我们先个数 = 篮子有几颗,供下一步使用。 我们先表取 = 用 table.get 读同一个键),供下一步使用。
随后我们**[显示当前步骤的结果](> print text="access 取列表第 1 项:取第一")。
随后我们[显示当前步骤的结果](> print text="access 取 Map 的键:取配置")。
随后我们[显示当前步骤的结果](> print text="table.len 数个数:个数")。
随后我们[显示当前步骤的结果](> print text="table.get 读键:表取")**。
—— 5. 遮蔽:把实现藏进括号 ——
描述给人读,() 里才是机器执行的部分。
推荐把赋值写进叙述句:先**值 = [取得需要的结果](实际表达式)**,再使用这个值。
粗体给出执行位置,方括号解释意图,圆括号保留实际逻辑。三者共同形成可读程序;
普通正文里的导航链接不会因此自动执行。下方也保留表格绑定形式,方便比较数据与操作的职责。
我们先留存 = 客户留存率,模拟数据,供下一步使用。
随后我们**[显示当前步骤的结果](> print text="遮蔽的值:留存")**。
未接通的功能用空载荷申报(会得到一条 warning,提醒写清返回值):
我们先待接 = 搜索接入,接口未接,待开发,供下一步使用。
随后我们**[显示当前步骤的结果](> print text="空载荷桩的值:待接")**。
—— 6. 循环 ——
- [篮子里的每个果子](遍历
篮子为果) 随后我们**[显示当前步骤的结果](> print text="果子:果")**。
我们先n = 3,供下一步使用。
n> 0 随后我们**[显示当前步骤的结果](> print text="倒数n")。 我们先n = (n- 1)**,供下一步使用。
—— 7. 分支 ——
我们先分数 = 86,供下一步使用。
分数>= 90 随后我们**[显示当前步骤的结果](> print text="等级 A")**。分数>= 60 随后我们**[显示当前步骤的结果](> print text="等级 B")**。-
随后我们**[显示当前步骤的结果](> print text="等级 C")**。
—— 8. 表格的三态 ——
竖表(单列)→ List:
城市 =
| 城 |
|---|
| 北京 |
| 上海 |
横表(1 行)→ Map:
配置 =
| 超时 | 重试 |
|---|---|
| 30 | 2 |
行向(首列 行)→ List of Map:
订单 =
| 行 | 品名 | 数量 |
|---|---|---|
| 1 | 苹果 | 2 |
| 2 | 梨 | 3 |
- [每条订单](遍历
订单为单) 随后我们**[显示当前步骤的结果](> print text="订单:单")**。
随后我们**[显示当前步骤的结果](> print text="配置超时是 配置")**。
—— 9. 值类型 ——
我们先整数 = 42,供下一步使用。 我们先小数 = 1.5,供下一步使用。 我们先真值 = True,供下一步使用。 我们先空值 = None,供下一步使用。 我们先串 = "引号里的文本",供下一步使用。
随后我们**[显示当前步骤的结果](> print text="整数 整数 小数 小数 真值 真值 空值 空值")。
随后我们[显示当前步骤的结果](> print text=串)**。
—— 10. 收尾 ——
随后我们**[显示当前步骤的结果](> print text="演示结束:执行位置决定是否运行,动作标签说明目的,括号保存实际逻辑。")**。
summary =
| name_length | sum | comma_sum | nested_sum | spaced_name | unfinished |
|---|---|---|---|---|---|
长度 |
甲 |
乙 |
丙 |
丁 |
待接 |
完成所有演示后,我们返回summary,供调用方直接检查数值与未完成项。
计税
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 档位 | any | required | 税率档位;1 取 3%,3 取 20%,其他值沿用本例 10% |
| 金额 | any | required | 待计税金额;需要支持与选定税率相乘 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 金额乘以本例选定税率;不包含额外舍入 |
输入档位与金额,先按明确的分支选择税率,再计算同一份输入的税额。这是教学规则,不读取外部税表,也不把未知档位推断成新的税率。返回值由乘法得到,调用方根据自己的金额单位继续处理。
本函数不做货币舍入、不写日志或文件。普通数值可以直接传入;不支持乘法的值保留原生诊断,而不是悄悄当作零。观察选中哪个分支,比只看最后的打印标记更容易核对规则。
先率 = 0.1作为本例的默认税率。
档位== 1 此档位使用率 = 0.03。档位== 3 此档位使用率 = 0.2。-
其余输入沿用率 = 0.1。 选定税率后,我们返回*[按本例规则计算税额](金额 * 率)*。
加
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| a | any | required | 左操作数;与 b 使用兼容的加法语义 |
| b | any | required | 右操作数;与 a 使用兼容的加法语义 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 两个操作数按原生加法语义得到的新值 |
输入a和b,直接组合两个已提供的值。本例用整数调用以展示位置实参、逗号分隔和嵌套调用;函数不会修改调用者变量,也不读取打印输出。需要类型转换时在调用前显式完成,不让这个简单函数猜测字符串是否代表数字。
得到两个输入后,我们返回*[按相同规则相加两个操作数](a + b)*。
加一 号
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| n | any | required | 参与加一的输入值;本例以数字演示 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 输入加一的新值,函数名中的空格仍保留 |
输入n之后,按原生加法与一相加。这个函数刻意保留带空格的名称,以展示可读名称与命令行参数引用之间的关系。调用者仍通过完整标题定位它;空格不代表参数,也不需要额外的隐藏入口。
完成这次计算后,我们返回*[把输入推进一位](n + 1)*。