241 lines
10 KiB
Markdown
241 lines
10 KiB
Markdown
---
|
||
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)*。
|