--- markup: occlusion import: table: lib/table.mq.md title: Marqdo 可读语法全景 description: 一页看完全部现行语法:遮蔽、调用、取值、循环、分支、表格、契约 --- 从仓库根目录执行:`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="名字是`名`,π 约等于 `π`")**。 反引号取值,正文里的反引号是插值: 我们先**长度 = [名字长度](len(`名`))**,供下一步使用。 随后我们**[显示当前步骤的结果](> 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 | 我们先**取第一 = [第一颗](access(`篮子`, "1"))**,供下一步使用。 我们先**取配置 = [拿铁多少钱](access(`饮品价`, "拿铁"))**,供下一步使用。 我们先**个数 = [篮子有几颗](table.len(`篮子`))**,供下一步使用。 我们先**表取 = [用 table.get 读同一个键](table.get(`饮品价`, "美式"))**,供下一步使用。 随后我们**[显示当前步骤的结果](> print text="access 取列表第 1 项:`取第一`")**。 随后我们**[显示当前步骤的结果](> print text="access 取 Map 的键:`取配置`")**。 随后我们**[显示当前步骤的结果](> print text="table.len 数个数:`个数`")**。 随后我们**[显示当前步骤的结果](> print text="table.get 读键:`表取`")**。 —— 5. 遮蔽:把实现藏进括号 —— 描述给人读,`()` 里才是机器执行的部分。 推荐把赋值写进叙述句:`先**值 = [取得需要的结果](实际表达式)**,再使用这个值。` 粗体给出执行位置,方括号解释意图,圆括号保留实际逻辑。三者共同形成可读程序; 普通正文里的导航链接不会因此自动执行。下方也保留表格绑定形式,方便比较数据与操作的职责。 我们先**留存 = [客户留存率,模拟数据](0.42)**,供下一步使用。 随后我们**[显示当前步骤的结果](> print text="遮蔽的值:`留存`")**。 未接通的功能用空载荷申报(会得到一条 warning,提醒写清返回值): 我们先**待接 = [搜索接入,接口未接,待开发]()**,供下一步使用。 随后我们**[显示当前步骤的结果](> print text="空载荷桩的值:`待接`")**。 —— 6. 循环 —— - [篮子里的每个果子](遍历 `篮子` 为 `果`) 随后我们**[显示当前步骤的结果](> print text="果子:`果`")**。 我们先**n = 3**,供下一步使用。 - `n` > 0 随后我们**[显示当前步骤的结果](> print text="倒数 `n`")**。 我们先**n = (`n` - 1)**,供下一步使用。 —— 7. 分支 —— 我们先**分数 = 86**,供下一步使用。 1. `分数` >= 90 随后我们**[显示当前步骤的结果](> print text="等级 A")**。 2. `分数` >= 60 随后我们**[显示当前步骤的结果](> print text="等级 B")**。 3. * 随后我们**[显示当前步骤的结果](> 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. `档位` == 1 此档位使用**率 = 0.03**。 2. `档位` == 3 此档位使用**率 = 0.2**。 3. * 其余输入沿用**率 = 0.1**。 选定税率后,我们返回*[按本例规则计算税额](金额 * 率)*。 ## 加 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | a | any | required | 左操作数;与 b 使用兼容的加法语义 | | b | any | required | 右操作数;与 a 使用兼容的加法语义 | | 返回 | 类型 | 说明 | |---|---|---| | result | any | 两个操作数按原生加法语义得到的新值 | 输入`a`和`b`,直接组合两个已提供的值。本例用整数调用以展示位置实参、逗号分隔和嵌套调用;函数不会修改调用者变量,也不读取打印输出。需要类型转换时在调用前显式完成,不让这个简单函数猜测字符串是否代表数字。 得到两个输入后,我们返回*[按相同规则相加两个操作数](a + b)*。 ## 加一 号 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | n | any | required | 参与加一的输入值;本例以数字演示 | | 返回 | 类型 | 说明 | |---|---|---| | result | any | 输入加一的新值,函数名中的空格仍保留 | 输入`n`之后,按原生加法与一相加。这个函数刻意保留带空格的名称,以展示可读名称与命令行参数引用之间的关系。调用者仍通过完整标题定位它;空格不代表参数,也不需要额外的隐藏入口。 完成这次计算后,我们返回*[把输入推进一位](n + 1)*。