Files
marqdo/examples/syntax-tour/index.mq.md

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