wezterm 配置 Lua 中的 YAML 解析wezterm.serde.yaml_decode使用指南与源码剖析【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/weztermwezterm.serde.yaml_decode(string)是 wezterm 内置 Lua APIwezterm.serde模块提供的 YAML 解码函数它把一段 YAML 文本解析为等价的 Lua 值用于在配置脚本中读取 YAML 格式的数据。读完本文你将掌握该函数的签名、返回值类型映射规则、底层解析实现并能借助配套的yaml_encode与同模块的json_decode、toml_decode在 wezterm 配置中完成多格式数据的读写互通。wezterm.serde模块模块索引是 wezterm 的 nightly 版本{{since(nightly)}}即 2023 年 9 月之后的 nightly 构建见 变更记录 中对 #4969 的引入说明中新增的序列化/反序列化工具模块核心实现在 lua-api-crates/serde-funcs/src/lib.rs。函数签名与基本用法yaml_decode的签名定义在官方文档 yaml_decode.md 中wezterm.serde.yaml_decode(string) - lua values它接收一个字符串参数将该字符串按 YAML 语法解析并返回对应的 Lua 值。官方文档给出的最小示例 wezterm.serde.yaml_decode(---\n# comment\nfoo: bar) { foo: bar, }输入字符串以文档分隔符---开头YAML 文档起始标记可省略第二行是注释第三行声明一个键值对foo: bar解析结果是一个 Lua table{ foo bar }。注意输出中的键foo带引号说明返回的是键值对映射表object而不是数组。更完整的调用示例local wezterm require wezterm local config_data wezterm.serde.yaml_decode([[ --- title: WezTerm 配置 width: 1200 height: 800 enabled: true tags: - dev - terminal ]]) -- config_data.title WezTerm 配置 -- config_data.width 1200 -- config_data.height 800 -- config_data.enabled true -- config_data.tags[1] dev -- config_data.tags[2] terminal这里使用 Lua 的长括号字符串[[ ... ]]直接嵌入多行 YAML避免手写转义非常适合在配置文件中嵌入外部格式的数据。返回值类型映射规则从源码看解析后的 YAML 值会先被serde_yaml解析为serde_json::ValueJValue再通过json_value_to_lua_value递归转换为 Lua 值。转换函数位于 lib.rs类型映射关系如下YAML 值中间表示JValue转换后的 Lua 值null/~/ 空Nullnil布尔值true/falseBoolboolean整数如42、-3Numberas_i64成功integer浮点数如3.14、1e3Numberas_i64失败number字符串Stringstring序列- itemArray以1开头的连续索引 table数组映射key: valueObject字符串键的映射 table既无法表示为 i64 也无法表示为 f64 的数值—抛错cannot represent ... as either i64 or f64要点解析整数与浮点严格区分YAML 中的42转成 Lua 的integer而4.5转成number。这与 wezterm 配置系统对数字类型的严格区分整数键控表格、单元格索引等场景保持一致。数组索引从 1 开始源码用tbl.set(idx 1, ...)填充序列元素符合 Lua 的 1 起始索引惯例。映射键转为字符串Object分支将每个键key.into_lua(lua)?转成字符串后写入 table因此1: x这类数字键也会以字符串键形式呈现。YAML 特有的类型标注被 YAML 1.1 语义解析例如!!str 123会解析为字符串!!int 42会解析为整数最终按上述规则落到对应的 Lua 类型。底层实现原理从 YAML 文本到 Lua 值yaml_decode的完整实现位于 lib.rsfn yaml_decode(lua: Lua, text: String) - mlua::ResultLuaValue_ { let value: JValue serde_yaml::from_str(text).map_err(|err| mlua::Error::external(format!({err:#})))?; json_value_to_lua_value(lua, value) }处理链路分两段serde_yaml::from_str阶段把 YAML 文本解析为serde_json::Value。依赖声明在 serde-funcs/Cargo.toml 中serde_yaml.workspace true。这一步负责 YAML 语法层缩进结构、---文档标记、#注释、锚点/别名、流式集合[]/{}、多行字符串|/块等都在这层处理。json_value_to_lua_value阶段按上文表格把JValue递归转换为mlua::LuaValue数组使用create_table_with_capacity(len, 0)预分配映射使用create_table_with_capacity(0, len)预分配。由于 YAML 是 JSON 的超集先归一到 JSON 中间表示再统一转换使得yaml_decode、json_decode、toml_decode三条解码路径共用同一个转换函数实现高度复用。编码侧yaml_encode等则走反向路径lua_value_to_json_value将 Lua 值转为JValue再交给对应序列化器lib.rs。错误处理解析失败时底层serde_yaml返回的错误会被包装为mlua::Error::external抛给 Lua 侧。例如-- 语法错误数组元素后出现键值对 local ok, err pcall(wezterm.serde.yaml_decode, a: 1\n- 2) if not ok then wezterm.log_error(YAML 解析失败: .. tostring(err)) return end单个元素数组被 Lua 映射为单值如yaml_decode([a])这一点与 Lua 表的数组/单元素语义一致顶层为null的输入返回nil空字符串属于合法 YAML解析结果为nil建议在配置脚本中使用pcall包裹不可信或外部输入的解码调用避免解析异常中断整个配置文件加载。与编码函数yaml_encode配合使用wezterm.serde模块同时提供反向的yaml_encode见 yaml_encode.md wezterm.serde.yaml_encode({foo bar}) foo: bar\n两者的互逆性被仓库内的单元测试显式验证。测试test_yaml_encode_decodelib.rs构造了一个包含字符串、整数、浮点数、数组和嵌套映射的复合值先yaml_encode再yaml_decode断言往返后的结果与原始 JSON 值完全相等let j0 json!({ key2str: value1, key2int: 4, key2float: 4.5, key2arr: vec![2, 3], key2dict: {a: a_value, b: 3}}); // ... let s yaml_encode(lua, v0.clone()).unwrap(); let j1: JValue serde_yaml::from_str(s).unwrap(); assert_eq!(j0, j1); let v1 yaml_decode(lua, s).unwrap(); let j1 lua_value_to_json_value(v1, mut HashSet::new()).unwrap(); assert_eq!(j0, j1);这为编码再解码的可逆性提供了直接的测试佐证也说明该函数适合作为 YAML 数据生成/消费的完整闭环。与json_decode、toml_decode的关系yaml_decode并非孤立函数。register入口lib.rs在wezterm.serde子模块下一次性注册了三组解码/编码函数解码json_decode、yaml_decode、toml_decode编码json_encode、yaml_encode、toml_encode美化编码json_encode_pretty、toml_encode_prettyYAML 无 pretty 变体其默认输出本身即带缩进三者底层共享同一套 Lua/JValue 转换逻辑仅序列化器不同。这意味着你的配置脚本可以统一用一组转换规则自由地在这三种数据格式之间搬运结构化数据例如读取 YAML 主题文件后转为 JSON 再写入诊断日志local wezterm require wezterm local theme wezterm.serde.yaml_decode(wezterm.config_dir .. /my-theme.yaml) wezterm.log_info(wezterm.serde.json_encode_pretty(theme))实战应用场景配置数据外置把复杂的表格数据如键位映射、配色方案、SSH 主机列表放在独立的.yaml文件中配置脚本启动时用yaml_decode加载避免 Lua 语法与 YAML 语法混写。与生态工具互操作许多现代 CLI 工具以 YAML 输出结构化数据如kubectl get -o yaml、docker compose config可在 wezterm 的启动任务或快捷键回调中捕获输出并解码再驱动 wezterm 行为。配置值预处理解码后的普通 Lua 表可以直接作为config表字段的候选值或进一步传给wezterm.color等模块做二次处理。数据往返调试结合yaml_encode做改表→编码→落盘的持久化小工具测试用例已验证其往返一致性。注意事项版本前提wezterm.serde是 nightly 特性文档标注since(nightly)稳定版构建不包含该模块调用会报 attempt to index a nil value (field serde)。使用前可在require wezterm后判断wezterm.serde ~ nil。哈希表顺序YAML 映射转为 Lua table 后pairs遍历顺序不保证与源文本一致序列化时应避免依赖键顺序。不支持任意 Lua 类型回写编码侧对function、thread等类型会抛出FromLuaConversionError见 lib.rs解码侧自然不会产生这类类型YAML 能表达的仅是标量、序列与映射三种结构。顶层标量与文档标记---可写可不写顶层为标量如yaml_decode(42)返回42顶层为序列如yaml_decode(- a\n- b)返回数组 table。总结wezterm.serde.yaml_decode以一行核心调用把成熟的serde_yaml解析能力接入 wezterm 的 Lua 配置环境通过统一的 JSON 中间表示完成到 Lua 值的类型映射。它与yaml_encode、json_decode、toml_decode等函数共享同一套转换框架配合单元测试中的往返验证可以放心地用于配置数据的外置加载与格式互转。若需更深入了解实现细节可继续阅读模块源码 lua-api-crates/serde-funcs/src/lib.rs 及配套文档 wezterm.serde 模块索引。【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
wezterm 配置 Lua 中的 YAML 解析wezterm.serde.yaml_decode使用指南与源码剖析【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/weztermwezterm.serde.yaml_decode(string)是 wezterm 内置 Lua APIwezterm.serde模块提供的 YAML 解码函数它把一段 YAML 文本解析为等价的 Lua 值用于在配置脚本中读取 YAML 格式的数据。读完本文你将掌握该函数的签名、返回值类型映射规则、底层解析实现并能借助配套的yaml_encode与同模块的json_decode、toml_decode在 wezterm 配置中完成多格式数据的读写互通。wezterm.serde模块模块索引是 wezterm 的 nightly 版本{{since(nightly)}}即 2023 年 9 月之后的 nightly 构建见 变更记录 中对 #4969 的引入说明中新增的序列化/反序列化工具模块核心实现在 lua-api-crates/serde-funcs/src/lib.rs。函数签名与基本用法yaml_decode的签名定义在官方文档 yaml_decode.md 中wezterm.serde.yaml_decode(string) - lua values它接收一个字符串参数将该字符串按 YAML 语法解析并返回对应的 Lua 值。官方文档给出的最小示例 wezterm.serde.yaml_decode(---\n# comment\nfoo: bar) { foo: bar, }输入字符串以文档分隔符---开头YAML 文档起始标记可省略第二行是注释第三行声明一个键值对foo: bar解析结果是一个 Lua table{ foo bar }。注意输出中的键foo带引号说明返回的是键值对映射表object而不是数组。更完整的调用示例local wezterm require wezterm local config_data wezterm.serde.yaml_decode([[ --- title: WezTerm 配置 width: 1200 height: 800 enabled: true tags: - dev - terminal ]]) -- config_data.title WezTerm 配置 -- config_data.width 1200 -- config_data.height 800 -- config_data.enabled true -- config_data.tags[1] dev -- config_data.tags[2] terminal这里使用 Lua 的长括号字符串[[ ... ]]直接嵌入多行 YAML避免手写转义非常适合在配置文件中嵌入外部格式的数据。返回值类型映射规则从源码看解析后的 YAML 值会先被serde_yaml解析为serde_json::ValueJValue再通过json_value_to_lua_value递归转换为 Lua 值。转换函数位于 lib.rs类型映射关系如下YAML 值中间表示JValue转换后的 Lua 值null/~/ 空Nullnil布尔值true/falseBoolboolean整数如42、-3Numberas_i64成功integer浮点数如3.14、1e3Numberas_i64失败number字符串Stringstring序列- itemArray以1开头的连续索引 table数组映射key: valueObject字符串键的映射 table既无法表示为 i64 也无法表示为 f64 的数值—抛错cannot represent ... as either i64 or f64要点解析整数与浮点严格区分YAML 中的42转成 Lua 的integer而4.5转成number。这与 wezterm 配置系统对数字类型的严格区分整数键控表格、单元格索引等场景保持一致。数组索引从 1 开始源码用tbl.set(idx 1, ...)填充序列元素符合 Lua 的 1 起始索引惯例。映射键转为字符串Object分支将每个键key.into_lua(lua)?转成字符串后写入 table因此1: x这类数字键也会以字符串键形式呈现。YAML 特有的类型标注被 YAML 1.1 语义解析例如!!str 123会解析为字符串!!int 42会解析为整数最终按上述规则落到对应的 Lua 类型。底层实现原理从 YAML 文本到 Lua 值yaml_decode的完整实现位于 lib.rsfn yaml_decode(lua: Lua, text: String) - mlua::ResultLuaValue_ { let value: JValue serde_yaml::from_str(text).map_err(|err| mlua::Error::external(format!({err:#})))?; json_value_to_lua_value(lua, value) }处理链路分两段serde_yaml::from_str阶段把 YAML 文本解析为serde_json::Value。依赖声明在 serde-funcs/Cargo.toml 中serde_yaml.workspace true。这一步负责 YAML 语法层缩进结构、---文档标记、#注释、锚点/别名、流式集合[]/{}、多行字符串|/块等都在这层处理。json_value_to_lua_value阶段按上文表格把JValue递归转换为mlua::LuaValue数组使用create_table_with_capacity(len, 0)预分配映射使用create_table_with_capacity(0, len)预分配。由于 YAML 是 JSON 的超集先归一到 JSON 中间表示再统一转换使得yaml_decode、json_decode、toml_decode三条解码路径共用同一个转换函数实现高度复用。编码侧yaml_encode等则走反向路径lua_value_to_json_value将 Lua 值转为JValue再交给对应序列化器lib.rs。错误处理解析失败时底层serde_yaml返回的错误会被包装为mlua::Error::external抛给 Lua 侧。例如-- 语法错误数组元素后出现键值对 local ok, err pcall(wezterm.serde.yaml_decode, a: 1\n- 2) if not ok then wezterm.log_error(YAML 解析失败: .. tostring(err)) return end单个元素数组被 Lua 映射为单值如yaml_decode([a])这一点与 Lua 表的数组/单元素语义一致顶层为null的输入返回nil空字符串属于合法 YAML解析结果为nil建议在配置脚本中使用pcall包裹不可信或外部输入的解码调用避免解析异常中断整个配置文件加载。与编码函数yaml_encode配合使用wezterm.serde模块同时提供反向的yaml_encode见 yaml_encode.md wezterm.serde.yaml_encode({foo bar}) foo: bar\n两者的互逆性被仓库内的单元测试显式验证。测试test_yaml_encode_decodelib.rs构造了一个包含字符串、整数、浮点数、数组和嵌套映射的复合值先yaml_encode再yaml_decode断言往返后的结果与原始 JSON 值完全相等let j0 json!({ key2str: value1, key2int: 4, key2float: 4.5, key2arr: vec![2, 3], key2dict: {a: a_value, b: 3}}); // ... let s yaml_encode(lua, v0.clone()).unwrap(); let j1: JValue serde_yaml::from_str(s).unwrap(); assert_eq!(j0, j1); let v1 yaml_decode(lua, s).unwrap(); let j1 lua_value_to_json_value(v1, mut HashSet::new()).unwrap(); assert_eq!(j0, j1);这为编码再解码的可逆性提供了直接的测试佐证也说明该函数适合作为 YAML 数据生成/消费的完整闭环。与json_decode、toml_decode的关系yaml_decode并非孤立函数。register入口lib.rs在wezterm.serde子模块下一次性注册了三组解码/编码函数解码json_decode、yaml_decode、toml_decode编码json_encode、yaml_encode、toml_encode美化编码json_encode_pretty、toml_encode_prettyYAML 无 pretty 变体其默认输出本身即带缩进三者底层共享同一套 Lua/JValue 转换逻辑仅序列化器不同。这意味着你的配置脚本可以统一用一组转换规则自由地在这三种数据格式之间搬运结构化数据例如读取 YAML 主题文件后转为 JSON 再写入诊断日志local wezterm require wezterm local theme wezterm.serde.yaml_decode(wezterm.config_dir .. /my-theme.yaml) wezterm.log_info(wezterm.serde.json_encode_pretty(theme))实战应用场景配置数据外置把复杂的表格数据如键位映射、配色方案、SSH 主机列表放在独立的.yaml文件中配置脚本启动时用yaml_decode加载避免 Lua 语法与 YAML 语法混写。与生态工具互操作许多现代 CLI 工具以 YAML 输出结构化数据如kubectl get -o yaml、docker compose config可在 wezterm 的启动任务或快捷键回调中捕获输出并解码再驱动 wezterm 行为。配置值预处理解码后的普通 Lua 表可以直接作为config表字段的候选值或进一步传给wezterm.color等模块做二次处理。数据往返调试结合yaml_encode做改表→编码→落盘的持久化小工具测试用例已验证其往返一致性。注意事项版本前提wezterm.serde是 nightly 特性文档标注since(nightly)稳定版构建不包含该模块调用会报 attempt to index a nil value (field serde)。使用前可在require wezterm后判断wezterm.serde ~ nil。哈希表顺序YAML 映射转为 Lua table 后pairs遍历顺序不保证与源文本一致序列化时应避免依赖键顺序。不支持任意 Lua 类型回写编码侧对function、thread等类型会抛出FromLuaConversionError见 lib.rs解码侧自然不会产生这类类型YAML 能表达的仅是标量、序列与映射三种结构。顶层标量与文档标记---可写可不写顶层为标量如yaml_decode(42)返回42顶层为序列如yaml_decode(- a\n- b)返回数组 table。总结wezterm.serde.yaml_decode以一行核心调用把成熟的serde_yaml解析能力接入 wezterm 的 Lua 配置环境通过统一的 JSON 中间表示完成到 Lua 值的类型映射。它与yaml_encode、json_decode、toml_decode等函数共享同一套转换框架配合单元测试中的往返验证可以放心地用于配置数据的外置加载与格式互转。若需更深入了解实现细节可继续阅读模块源码 lua-api-crates/serde-funcs/src/lib.rs 及配套文档 wezterm.serde 模块索引。【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
