Lumesh Shell Map 模块文档
概述
Map 模块提供了一系列用于操作映射表（键值对集合）的函数，支持创建、查询、修改和转换等操作。所有函数都通过 map. 前缀调用，例如 map.keys(my_map)。
函数分类
检查类函数
has
功能: 检查映射表是否包含指定键
语法:
map.has(key, target_map)
参数:
key: String - 要检查的键名target_map: Map - 目标映射表
返回值: Boolean - 如果键存在返回 true，否则返回 false
示例:
let my_map = {a: 1, b: 2};
map.has("a", my_map) # 返回 true
获取类函数
可使用顶级函数 get 按路径获取值。
items
功能: 获取映射表的所有键值对列表
语法:
map.items(target_map)
参数:
target_map: Map - 目标映射表
返回值: List - 由[key, value]组成的列表
示例:
map.items({x: 10, y: 20})
# 返回 [["x", 10], ["y", 20]]
keys
功能: 获取映射表的所有键列表
语法:
map.keys(target_map)
参数:
target_map: Map - 目标映射表
返回值: List - 包含所有键的字符串列表
示例:
map.keys({name: "Alice", age: 30})
# 返回 ["name", "age"]
values
功能: 获取映射表的所有值列表
语法:
map.values(target_map)
参数:
target_map: Map - 目标映射表
返回值: List - 包含所有值的列表
示例:
map.values({a: 1, b: 2})
# 返回 [1, 2]
修改类函数
insert
功能: 向映射表插入新的键值对
语法:
map.insert(key, value, target_map)
参数:
key: String - 要插入的键value: Any - 要插入的值target_map: Map - 目标映射表
返回值: Map - 包含新键值对的新映射表（原映射表不变）
示例:
let orig = {a: 1};
let new = map.insert("b", 2, orig);
# new 为 {a: 1, b: 2}
remove
功能: 从映射表移除指定键
语法:
map.remove(key, target_map)
参数:
key: String - 要移除的键target_map: Map - 目标映射表
返回值: Map - 移除指定键后的新映射表
示例:
map.remove("a", {a: 1, b: 2})
# 返回 {b: 2}
创建类函数
from_items
功能: 从键值对列表创建映射表
语法:
map.from_items(item_list)
参数:
item_list: List - 包含[key, value]对的列表
返回值: Map - 新建的映射表
示例:
map.from_items([["x", 10], ["y", 20]])
# 返回 {x: 10, y: 20}
转换类函数
union
功能: 合并两个映射表（后者覆盖前者）
语法:
map.union(map1, map2)
参数:
map1: Map - 第一个映射表map2: Map - 第二个映射表
返回值: Map - 合并后的新映射表
示例:
map.union({a:1}, {b:2})
# 返回 {a:1, b:2}
intersect
功能: 获取两个映射表的键交集（保留第一个映射表的值）
语法:
map.intersect(map1, map2)
参数:
map1: Map - 第一个映射表map2: Map - 第二个映射表
返回值: Map - 只包含共同键的新映射表
示例:
map.intersect({a:1,b:2}, {a:3})
# 返回 {a:1}
difference
功能: 获取第一个映射表独有的键值对
语法:
map.difference(map1, map2)
参数:
map1: Map - 第一个映射表map2: Map - 第二个映射表
返回值: Map - 只包含第一个映射表独有键的新映射表
示例:
map.difference({a:1,b:2}, {a:1})
# 返回 {b:2}
deep_merge
功能: 深度递归合并多个映射表
语法:
map.deep_merge(map1, map2, ...)
参数:
map1,map2, …: Map - 要合并的映射表（至少两个）
返回值: Map - 深度合并后的新映射表
示例:
let base = {a: {x: 1}};
let update = {a: {y: 2}};
map.deep_merge(base, update)
# 返回 {a: {x:1, y:2}}
循环类函数
map
功能: 使用函数转换映射表的键和值
语法:
map.map(key_func, [value_func], target_map)
参数:
key_func: Function - 处理键的函数（接受原键，返回新键）value_func: Function (可选) - 处理值的函数（接受原值，返回新值）target_map: Map - 目标映射表
返回值: Map - 转换后的新映射表
示例:
let m = {a: 1, b: 2};
# 只转换键
map.map(k -> k + "_new", m)
# 返回 {a_new:1, b_new:2}
# 同时转换键和值
map.map(k -> k + "_k", v -> v * 2, m)
# 返回 {a_k:2, b_k:4}
使用建议
- 所有修改操作（如
insert,remove）都会返回新映射表，原始映射表保持不变 - 深度操作（如
deep_merge）可以处理任意层级的嵌套结构 - 使用
get_path访问深层嵌套值比链式get更简洁 map.map可以配合匿名函数实现复杂的转换逻辑
错误处理
- 参数类型不匹配时会返回类型错误
- 访问不存在的路径时
get_path会报错 - 所有函数对非映射表参数都会返回
None（除了会报错的情况）