- 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。
36 KiB
Executable File
markup, title, description
| markup | title | description |
|---|---|---|
| occlusion | lib/表 | 列表与字典。优先用「改」(路径 1-based,与access 取元同构);取/改位/切片为 0-based。 json 只管解析/序列化。 |
列表与字典。嵌套写入优先「改」;作者程序里读元用access 取元,不要新写脚注取元。
用明确的数据形态变换列表、字典和行记录。
能力与边界:access 与改的整数路径从一开始;取、切片、插入、删位等旧接口从零开始。更新返回新值,必须保存。行数只是长度别名;列转行、行转列明确转换形态。相等比较沿用运行时的类型和字典顺序规则。
本文件就是调用和开发手册:直接导入此文件,或用 marqdo call 按下面的函数标题调用。参数表说明类型和默认值;未填默认值的参数必须提供。返回表是渐进契约,后文说明失败与边界。
实现入口:src/host/collection.rs、src/host/collection_ops.rs
开发时保持中英文语义一致,先组合公开库;仅在 OS 或算法边界添加宿主原语并声明效应。修改后运行 marqdo check --narrative-ratio 本文件,并执行 tests/stdlib_tasks.rs 的真实任务。
改
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 入 | any | 必填 | 输入集合;None 用于创建新记录 |
| 于 | any | 必填 | 文本键、从一开始的下标,或由键与下标组成的嵌套路径 |
| 值 | any | 必填 | 待转换或保存的值;不会就地修改输入 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 把集合入在路径于上的那一元改成值 |
这里使用入、于、值。
调用效应:pure。
把集合入在路径于上的那一元改成值。
于可以是文本键、1-based 下标,或键/下标组成的路径列表(与access 取元嵌套同构)。
调用例:[表.改] 入=None 于="Authorization" 值="Bearer-x"
完成后返回*[把集合入在路径于上的那一元改成值](> host_collection_put in=入 at=于 value=值)*。
长度
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| xs | any | 必填 | 本操作要求的输入列表或集合 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | 列表或字典 xs 的长度 |
这里使用xs。
调用效应:pure。
列表或字典 xs 的长度。
完成后返回*调用 len*。
行数
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| xs | any | 必填 | 本操作要求的输入列表或集合 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | 列表 xs 的行数(同长度) |
这里使用xs。
调用效应:pure。
列表 xs 的行数(同长度)。
完成后返回*调用 len*。
取
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| xs | any | 必填 | 本操作要求的输入列表或集合 |
| i | number | 必填 | 从零开始的元素或行下标 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 从零起取 xs 的第 i 项(与内置 at 相同) |
这里使用xs、i。
调用效应:pure。
从零起取 xs 的第 i 项(与内置 at 相同)。越界 → None。
完成后返回*[调用 at](at(value=xs, index=i))*。
取行
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| xs | any | 必填 | 本操作要求的输入列表或集合 |
| i | number | 必填 | 从零开始的元素或行下标 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 从零起取 xs 的第 i 行 |
这里使用xs、i。
调用效应:pure。
从零起取 xs 的第 i 行。
完成后返回*[调用 at](at(value=xs, index=i))*。
追加
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| list | any | 必填 | 输入列表;更新返回新列表 |
| item | any | 必填 | 要插入、替换或比较的元素 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 在 list 末尾追加 item |
这里使用list、item。
调用效应:pure。
在 list 末尾追加 item。
完成后返回*[在 list 末尾追加 item](> host_list_append list=list item=item)*。
前插
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| list | any | 必填 | 输入列表;更新返回新列表 |
| item | any | 必填 | 要插入、替换或比较的元素 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 在 list 开头插入 item |
这里使用list、item。
调用效应:pure。
在 list 开头插入 item。
完成后返回*[在 list 开头插入 item](> host_list_prepend list=list item=item)*。
拼接
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| a | any | 必填 | 第一个列表;None 用作空列表种子 |
| b | any | 必填 | 追加到 a 后面的列表 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 拼接列表 a 与 b |
这里使用a、b。
调用效应:pure。
拼接列表 a 与 b。
完成后返回*[拼接列表 a 与 b](> host_list_concat a=a b=b)*。
插入
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| list | any | 必填 | 输入列表;更新返回新列表 |
| index | number | 必填 | 插入、替换或删除的位置,从零开始 |
| item | any | 必填 | 要插入、替换或比较的元素 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 在 list 的从零起 index 处插入 item |
这里使用list、index、item。
调用效应:pure。
在 list 的从零起 index 处插入 item。
完成后返回*[在 list 的从零起 index 处插入 item](> host_list_insert list=list index=index item=item)*。
改位
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| list | any | 必填 | 输入列表;更新返回新列表 |
| index | number | 必填 | 插入、替换或删除的位置,从零开始 |
| item | any | 必填 | 要插入、替换或比较的元素 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 从零起替换 list 的 index 为 item;日常嵌套改写请用「改」 |
这里使用list、index、item。
调用效应:pure。
从零起替换 list 的 index 为 item;日常嵌套改写请用「改」。
完成后返回*[从零起替换 list 的 index 为 item;日常嵌套改写请用「改」](> host_list_set_at list=list index=index item=item)*。
删位
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| list | any | 必填 | 输入列表;更新返回新列表 |
| index | number | 必填 | 插入、替换或删除的位置,从零开始 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 删去 list 从零起的 index |
这里使用list、index。
调用效应:pure。
删去 list 从零起的 index。
完成后返回*[删去 list 从零起的 index](> host_list_remove_at list=list index=index)*。
弹出
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| list | any | 必填 | 输入列表;更新返回新列表 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 去掉 list 末项(空表报错) |
这里使用list。
调用效应:pure。
去掉 list 末项(空表报错)。需要末值时先「末」。
得到**n = 调用 len**。
n> 0 完成后返回*[去掉 list 末项(空表报错)](> host_list_remove_at list=listindex=n- 1)*。-
完成后返回*[去掉 list 末项(空表报错)](> host_list_remove_at list=list index=0)*。
首
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| list | any | 必填 | 输入列表;更新返回新列表 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | list 的首项 |
这里使用list。
调用效应:pure。
list 的首项。
完成后返回*[list 的首项](> host_list_first list=list)*。
末
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| list | any | 必填 | 输入列表;更新返回新列表 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | list 的末项 |
这里使用list。
调用效应:pure。
list 的末项。
完成后返回*[list 的末项](> host_list_last list=list)*。
切片
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| list | any | 必填 | 输入列表;更新返回新列表 |
| start | number | 必填 | 切片起点,从零开始且包含端点 |
| end | any | None | 切片终点,从零开始且不包含端点;None 表示到末尾 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 对 list 做从零起的半开切片,从 start 到 end |
这里使用list、start、end=None。
调用效应:pure。
对 list 做从零起的半开切片,从 start 到 end。
完成后返回*[对 list 做从零起的半开切片,从 start 到 end](> host_list_slice list=list start=start end=end)*。
含有
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| list | any | 必填 | 输入列表;更新返回新列表 |
| item | any | 必填 | 要插入、替换或比较的元素 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | bool | list 是否含有 item |
这里使用list、item。
调用效应:pure。
list 是否含有 item。
完成后返回*[list 是否含有 item](> host_list_contains list=list item=item)*。
下标
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| list | any | 必填 | 输入列表;更新返回新列表 |
| item | any | 必填 | 要插入、替换或比较的元素 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | item 在 list 中从零起的下标;没有 → None |
这里使用list、item。
调用效应:pure。
item 在 list 中从零起的下标;没有 → None。
完成后返回*[item 在 list 中从零起的下标;没有 → None](> host_list_index_of list=list item=item)*。
反转
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| list | any | 必填 | 输入列表;更新返回新列表 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 反转 list |
这里使用list。
调用效应:pure。
反转 list。
完成后返回*[反转 list](> host_list_reverse list=list)*。
排序
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| list | any | 必填 | 输入列表;更新返回新列表 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 对 list 升序排序(优先 int/num/text) |
这里使用list。
调用效应:pure。
对 list 升序排序(优先 int/num/text)。
完成后返回*[对 list 升序排序(优先 int/num/text)](> host_list_sort list=list)*。
按键排序
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| list | any | 必填 | 输入列表;更新返回新列表 |
| key | text | 必填 | 本操作需要的字段名或键 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 对 map 列表 list 按字段 key 排序 |
这里使用list、key。
调用效应:pure。
对 map 列表 list 按字段 key 排序。
完成后返回*[对 map 列表 list 按字段 key 排序](> host_list_sort_by list=list key=key)*。
去重
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| list | any | 必填 | 输入列表;更新返回新列表 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 对 list 保序去重(保留首次) |
这里使用list。
调用效应:pure。
对 list 保序去重(保留首次)。
完成后返回*[对 list 保序去重(保留首次)](> host_list_unique list=list)*。
分块
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| list | any | 必填 | 输入列表;更新返回新列表 |
| size | number | 必填 | 每块包含的元素数,必须为正数 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 把 list 按 size 分块 |
这里使用list、size。
调用效应:pure。
把 list 按 size 分块。
完成后返回*[把 list 按 size 分块](> host_list_chunk list=list size=size)*。
拉链
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| a | any | 必填 | 各配对中第一项来自的列表 |
| b | any | 必填 | 各配对中第二项来自的列表 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 将 a 与 b 配对,取较短长度 |
这里使用a、b。
调用效应:pure。
将 a 与 b 配对,取较短长度。
完成后返回*[将 a 与 b 配对,取较短长度](> host_list_zip a=a b=b)*。
展平
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| list | any | 必填 | 输入列表;更新返回新列表 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 对 list 做一层展平 |
这里使用list。
调用效应:pure。
对 list 做一层展平。
完成后返回*[对 list 做一层展平](> host_list_flatten list=list)*。
清空
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| value | any | 必填 | 运行时值;具体规则见下方操作说明 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 按类型清空 value(空列表或空字典) |
这里使用value。
调用效应:pure。
按类型清空 value(空列表或空字典)。
完成后返回*[按类型清空 value(空列表或空字典)](> host_collection_clear value=value)*。
取键
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| map | any | 必填 | 输入文本键字典 |
| key | text | 必填 | 本操作需要的字段名或键 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 浅取 map 的 key;缺键 → None |
这里使用map、key。
调用效应:pure。
浅取 map 的 key;缺键 → None。作者侧优先access 取元。
完成后返回*[浅取 map 的 key;缺键 → None](> host_map_get map=map key=key)*。
设
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| map | any | 必填 | 输入文本键字典 |
| key | text | 必填 | 本操作需要的字段名或键 |
| value | any | 必填 | 运行时值;具体规则见下方操作说明 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | 浅设 map 的 key 为 value;嵌套请用「改」 |
这里使用map、key、value。
调用效应:pure。
浅设 map 的 key 为 value;嵌套请用「改」。
完成后返回*[浅设 map 的 key 为 value;嵌套请用「改」](> host_map_set map=map key=key value=value)*。
删键
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| map | any | 必填 | 输入文本键字典 |
| key | text | 必填 | 本操作需要的字段名或键 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | 从 map 删除 key |
这里使用map、key。
调用效应:pure。
从 map 删除 key。
完成后返回*[从 map 删除 key](> host_map_delete map=map key=key)*。
有键
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| map | any | 必填 | 输入文本键字典 |
| key | text | 必填 | 本操作需要的字段名或键 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | bool | map 是否有 key |
这里使用map、key。
调用效应:pure。
map 是否有 key。
完成后返回*[map 是否有 key](> host_map_has map=map key=key)*。
键表
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| map | any | 必填 | 输入文本键字典 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | map 的键表 |
这里使用map。
调用效应:pure。
map 的键表。
完成后返回*[map 的键表](> host_map_keys map=map)*。
值表
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| map | any | 必填 | 输入文本键字典 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | map 的值表 |
这里使用map。
调用效应:pure。
map 的值表。
完成后返回*[map 的值表](> host_map_values map=map)*。
项表
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| map | any | 必填 | 输入文本键字典 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | map 的键值对行表 |
这里使用map。
调用效应:pure。
map 的键值对行表。
完成后返回*[map 的键值对行表](> host_map_items map=map)*。
合并
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| a | any | 必填 | 基础记录;None 用作空记录种子 |
| b | any | 必填 | 合入 a 的记录;后面的值覆盖同名键 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | 合并 a 与 b(右侧覆盖左侧) |
这里使用a、b。
调用效应:pure。
合并 a 与 b(右侧覆盖左侧)。
完成后返回*[合并 a 与 b(右侧覆盖左侧)](> host_map_merge a=a b=b)*。
键数
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| map | any | 必填 | 输入文本键字典 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | map 的键数 |
这里使用map。
调用效应:pure。
map 的键数。
完成后返回*[map 的键数](> host_map_size map=map)*。
空表
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 空列表 |
调用效应:pure。
空列表。
完成后返回*[空列表](> host_list_concat a=None b=None)*。
空字典
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | 返回新的空字典,作为不可变更新的种子;它与空列表不同 |
调用效应:pure。
返回新的空字典,作为不可变更新的种子;它与空列表不同。
完成后返回*[返回新的空字典,作为不可变更新的种子;它与空列表不同](> host_map_merge a=None b=None)*。
序列
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 起 | number | 必填 | 序列的第一个数值 |
| 止 | number | 必填 | 序列不包含的终止边界 |
| 步长 | number | 1 | 非零序列步长;符号必须朝向终点 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 生成左闭右开的整数序列;允许负步长,拒绝零步长,最多一百万项。 |
这里使用起、止、步长=1。
调用效应:pure。
生成左闭右开的整数序列;允许负步长,拒绝零步长,最多一百万项。
完成后返回*[生成左闭右开的整数序列;允许负步长,拒绝零步长,最多一百万项](> host_table_range start=起 end=止 step=步长)*。
编号
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 列表 | list | 必填 | 输入列表;不可变更新返回新列表 |
| 起 | number | 0 | 第一条记录所用的索引值;默认从一开始 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 返回 index/value 记录列表;编号从 start 开始,输入不变。 |
这里使用列表、起=0。
调用效应:pure。
返回 index/value 记录列表;编号从 start 开始,输入不变。
完成后返回*[返回 index/value 记录列表;编号从 start 开始,输入不变](> host_table_enumerate list=列表 start=起)*。
提列
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 列表 | list | 必填 | 输入列表;不可变更新返回新列表 |
| 键 | text | 必填 | 要读取、比较或更新的字段名或存储键 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 逐行提取一个字段;缺少字段时报错,不悄悄变为空。 |
这里使用列表、键。
调用效应:pure。
逐行提取一个字段;缺少字段时报错,不悄悄变为空。
完成后返回*[逐行提取一个字段;缺少字段时报错,不悄悄变为空](> host_table_pluck list=列表 key=键)*。
投影
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 列表 | list | 必填 | 输入列表;不可变更新返回新列表 |
| 键表 | list | 必填 | 按顺序排列的字段名列表 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 按 keys 顺序保留字段;每个字段必须存在。 |
这里使用列表、键表。
调用效应:pure。
按 keys 顺序保留字段;每个字段必须存在。
完成后返回*[按 keys 顺序保留字段;每个字段必须存在](> host_table_project list=列表 keys=键表)*。
筛选
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 列表 | list | 必填 | 输入列表;不可变更新返回新列表 |
| 键 | text | 必填 | 要读取、比较或更新的字段名或存储键 |
| 值 | any | 必填 | 待转换或保存的值;不会就地修改输入 |
| 操作 | text | "eq" | 本接口支持的操作名 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 筛选匹配记录。op 为 eq/ne/gt/ge/lt/le/contains/in;这是固定操作名,不执行文本代码。 |
这里使用列表、键、值、操作="eq"。
调用效应:pure。
筛选匹配记录。op 为 eq/ne/gt/ge/lt/le/contains/in;这是固定操作名,不执行文本代码。
完成后返回*[筛选匹配记录](> host_table_where list=列表 key=键 value=值 op=操作)*。
分组
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 列表 | list | 必填 | 输入列表;不可变更新返回新列表 |
| 键 | text | 必填 | 要读取、比较或更新的字段名或存储键 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 按首次出现顺序返回 key/count/rows 记录;分组键保留原类型。 |
这里使用列表、键。
调用效应:pure。
直接调用此函数:
marqdo call lib/表.mq.md 分组 '列表=[{"team":"a","n":3},{"team":"b","n":1},{"team":"a","n":2}]' '键="team"' --effects none --json
按首次出现顺序返回 key/count/rows 记录;分组键保留原类型。
完成后返回*[按首次出现顺序返回 key/count/rows 记录;分组键保留原类型](> host_table_group_by list=列表 key=键)*。
按键去重
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 列表 | list | 必填 | 输入列表;不可变更新返回新列表 |
| 键 | text | 必填 | 要读取、比较或更新的字段名或存储键 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 每个字段值保留第一条记录,维持输入顺序。 |
这里使用列表、键。
调用效应:pure。
每个字段值保留第一条记录,维持输入顺序。
完成后返回*[每个字段值保留第一条记录,维持输入顺序](> host_table_unique_by list=列表 key=键)*。
聚合
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 列表 | list | 必填 | 输入列表;不可变更新返回新列表 |
| 键 | any | None | 要读取、比较或更新的字段名或存储键 |
| 操作 | text | "sum" | 本接口支持的操作名 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | 聚合标量列表或一个字段:sum/count/min/max/mean。空表求和与计数为零;空表最值与均值失败;整数求和检查溢出。 |
这里使用列表、键=None、操作="sum"。
调用效应:pure。
聚合标量列表或一个字段:sum/count/min/max/mean。空表求和与计数为零;空表最值与均值失败;整数求和检查溢出。
完成后返回*[聚合标量列表或一个字段:sum/count/min/max/mean](> host_table_aggregate list=列表 key=键 op=操作)*。
多键排序
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 列表 | list | 必填 | 输入列表;不可变更新返回新列表 |
| 键表 | list | 必填 | 按顺序排列的字段名列表 |
| 降序 | bool | False | 是否按多键降序排列 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 按 keys 的字段顺序稳定排序;descending 改变比较方向,相同键保持顺序。 |
这里使用列表、键表、降序=False。
调用效应:pure。
按 keys 的字段顺序稳定排序;descending 改变比较方向,相同键保持顺序。
完成后返回*[按 keys 的字段顺序稳定排序;descending 改变比较方向,相同键保持顺序](> host_table_sort_keys list=列表 keys=键表 descending=降序)*。
改字段名
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 列表 | list | 必填 | 输入列表;不可变更新返回新列表 |
| 字段 | map | 必填 | 附加到日志事件的结构化字段与值记录 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 用旧名到新名的字典改字段名;输出字段重名时报错。 |
这里使用列表、字段。
调用效应:pure。
用旧名到新名的字典改字段名;输出字段重名时报错。
完成后返回*[用旧名到新名的字典改字段名;输出字段重名时报错](> host_table_rename list=列表 fields=字段)*。
列转行
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 列 | map | 必填 | 列名与列表记录;各列长度必须一致 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 把列式字典转为行记录;各列必须是等长列表,不猜测普通对象字段。 |
这里使用列。
调用效应:pure。
把列式字典转为行记录;各列必须是等长列表,不猜测普通对象字段。
完成后返回*[把列式字典转为行记录;各列必须是等长列表,不猜测普通对象字段](> host_table_from_columns columns=列)*。
行转列
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 行 | list | 必填 | 行记录列表,不是隐式列式表 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | 把字段集合相同的行记录转为列式字典;空输入返回空字典。 |
这里使用行。
调用效应:pure。
把字段集合相同的行记录转为列式字典;空输入返回空字典。
完成后返回*[把字段集合相同的行记录转为列式字典;空输入返回空字典](> host_table_to_columns rows=行)*。
连接
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 左 | list | 必填 | 第一个操作数;适用范围见本操作说明 |
| 右 | list | 必填 | 第二个操作数;适用范围见本操作说明 |
| 键 | text | 必填 | 要读取、比较或更新的字段名或存储键 |
| 右键 | text | 必填 | 右侧记录中用于匹配的字段 |
| 模式 | text | "inner" | 连接方式:inner 或 left |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 按字段相等连接;保持左表和右表匹配顺序。mode 为 inner/left;右侧重名字段加 right_ 前缀,仍冲突则失败。 |
这里使用左、右、键、右键、模式="inner"。
调用效应:pure。
按字段相等连接;保持左表和右表匹配顺序。mode 为 inner/left;右侧重名字段加 right_ 前缀,仍冲突则失败。
完成后返回*[按字段相等连接;保持左表和右表匹配顺序](> host_table_join a=左 b=右 key=键 right_key=右键 mode=模式)*。
转字段类型
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 行 | list | 必填 | 行记录列表,不是隐式列式表 |
| 规则 | map | 必填 | 字段与类型记录,采用标准契约类型词汇 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 按 schema 转换 text/int/number/bool/any 字段;缺失或无效值报告行号和字段,保留其他字段。 |
这里使用行、规则。
调用效应:pure。
按 schema 转换 text/int/number/bool/any 字段;缺失或无效值报告行号和字段,保留其他字段。
完成后返回*[按 schema 转换 text/int/number/bool/any 字段;缺失或无效值报告行号和字段,保留其他字段](> host_table_cast rows=行 schema=规则)*。
并集
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 左 | list | 必填 | 第一个操作数;适用范围见本操作说明 |
| 右 | list | 必填 | 第二个操作数;适用范围见本操作说明 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 保持首次出现顺序的并集;值相等规则与去重一致,区分类型。 |
这里使用左、右。
调用效应:pure。
保持首次出现顺序的并集;值相等规则与去重一致,区分类型。
完成后返回*[保持首次出现顺序的并集;值相等规则与去重一致,区分类型](> host_table_union a=左 b=右)*。
交集
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 左 | list | 必填 | 第一个操作数;适用范围见本操作说明 |
| 右 | list | 必填 | 第二个操作数;适用范围见本操作说明 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 保持输入顺序的交集,去除重复值。 |
这里使用左、右。
调用效应:pure。
保持输入顺序的交集,去除重复值。
完成后返回*[保持输入顺序的交集,去除重复值](> host_table_intersection a=左 b=右)*。
差集
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 左 | list | 必填 | 第一个操作数;适用范围见本操作说明 |
| 右 | list | 必填 | 第二个操作数;适用范围见本操作说明 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 保留左表中不在右表的值,维持顺序并去重。 |
这里使用左、右。
调用效应:pure。
保留左表中不在右表的值,维持顺序并去重。
完成后返回*[保留左表中不在右表的值,维持顺序并去重](> host_table_difference a=左 b=右)*。
尝试转类型
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 行 | list | 必填 | 行记录列表,不是隐式列式表 |
| 规则 | map | 必填 | 字段与类型记录,采用标准契约类型词汇 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | 可恢复地转换字段;无效字段返回结果记录,不中断调用方。 |
这里使用行、规则。
调用效应:pure。
可恢复地转换字段;无效字段返回结果记录,不中断调用方。
完成后返回*[可恢复地转换字段;无效字段返回结果记录,不中断调用方](> host_table_try_cast rows=行 schema=规则)*。
校验记录
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 行 | list | 必填 | 行记录列表,不是隐式列式表 |
| 规则 | map | 必填 | 字段与类型记录,采用标准契约类型词汇 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | 按核心渐进式类型校验必需字段,结果错误含 details 行号与字段诊断;int 是核心 number 别名,严格整数转换使用转字段类型。 |
这里使用行、规则。
调用效应:pure。
按核心渐进式类型校验必需字段,结果错误含 details 行号与字段诊断;int 是核心 number 别名,严格整数转换使用转字段类型。
完成后返回*[按核心渐进式类型校验必需字段,结果错误含 details 行号与字段诊断;int 是核心 number 别名,严格整数转换使用转字段类型](> host_table_validate rows=行 schema=规则)*。
查找首项
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 列表 | list | 必填 | 按原有顺序检查的行记录列表,不会就地修改 |
| 键 | text | 必填 | 每行需要读取并比较的字段名 |
| 值 | any | 必填 | 比较右值;in 操作在此集合中测试成员关系 |
| 操作 | text | "eq" | eq、ne、gt、ge、lt、le、contains 或 in;无效操作会失败 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 首个匹配行;没有匹配时为空值 |
这里使用列表、键、值、操作="eq"。
调用效应:pure。
复用同一筛选规则,保持原行顺序且不修改输入;缺失字段或无效操作仍会产生诊断。
得到**selected = [调用 筛选](筛选(列表=列表, 键=键, 值=值, 操作=操作))**。
完成后返回*调用 首*。
任一满足
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 列表 | list | 必填 | 按原有顺序检查的行记录列表,不会就地修改 |
| 键 | text | 必填 | 每行需要读取并比较的字段名 |
| 值 | any | 必填 | 比较右值;in 操作在此集合中测试成员关系 |
| 操作 | text | "eq" | eq、ne、gt、ge、lt、le、contains 或 in;无效操作会失败 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | bool | 是否至少一行匹配;空列表为假 |
这里使用列表、键、值、操作="eq"。
调用效应:pure。
复用同一筛选规则,保持原行顺序且不修改输入;缺失字段或无效操作仍会产生诊断。
得到**selected = [调用 筛选](筛选(列表=列表, 键=键, 值=值, 操作=操作))。
得到matched = 调用 len**。
完成后返回matched > 0。
全部满足
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 列表 | list | 必填 | 按原有顺序检查的行记录列表,不会就地修改 |
| 键 | text | 必填 | 每行需要读取并比较的字段名 |
| 值 | any | 必填 | 比较右值;in 操作在此集合中测试成员关系 |
| 操作 | text | "eq" | eq、ne、gt、ge、lt、le、contains 或 in;无效操作会失败 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | bool | 是否每行都匹配;空列表为真 |
这里使用列表、键、值、操作="eq"。
调用效应:pure。
复用同一筛选规则,保持原行顺序且不修改输入;缺失字段或无效操作仍会产生诊断。
得到**selected = [调用 筛选](筛选(列表=列表, 键=键, 值=值, 操作=操作))。
得到matched = 调用 len。
得到total = 调用 len**。
完成后返回matched == total。
分组汇总
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 列表 | list | 必填 | 输入列表;不可变更新返回新列表 |
| 分组键 | text | 必填 | 要读取、比较或更新的字段名或存储键 |
| 字段 | text | 必填 | 各分组内需要聚合的数值字段 |
| 操作 | text | "sum" | 本接口支持的操作名 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 批量按键分组并聚合一个字段,返回 key/count/value 行记录,保持首次分组顺序;操作规则同聚合,避免在作者循环中反复复制增长的结果列表。 |
这里使用列表、分组键、字段、操作="sum"。
调用效应:pure。
批量按键分组并聚合一个字段,返回 key/count/value 行记录,保持首次分组顺序;操作规则同聚合,避免在作者循环中反复复制增长的结果列表。
完成后返回*[批量按键分组并聚合一个字段,返回 key/count/value 行记录,保持首次分组顺序;操作规则同聚合,避免在作者循环中反复复制增长的结果列表](> host_table_summarize list=列表 key=分组键 field=字段 op=操作)*。
键值转记录
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 键值对 | list | 必填 | 有序行记录,每行含文本 key 与任意 value 字段;其他字段不参与构造 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | map | 新记录;首次出现的键决定顺序,后续同名键替换其值 |
调用效应:pure。
输入键值对采用普通 @ 行记录表,把过宽的横向记录改写成可逐行阅读的 key/value 数据。
适合提示章节、配置片段和具名字段较多的记录;这里复用本库既有的不可变更新,
不解析 JSON 文本,也不另造表格方言。空列表得到空记录,缺少或无效的键交给改操作报告,
不会为了制造字典而添加一个无意义的占位列。
先准备记录 = 创建新的空记录,再按行读取字段,使每一项的来源都保持可见。
- [把每条具名字段写入新记录](遍历 键值对 为 键值行)
读取键 = 取出本行的字段名),
以及值 = 取出本行的字段值)。
然后保留记录 = [设置字段而不修改输入行](改(入=
记录, 于=键, 值=值))。
处理完有序行后,返回记录。同名字段保留第一次出现的位置并更新其值; 原来的键值对仍可继续使用,本操作没有文件、网络或插件副作用。