yq KYaml 格式详解：flow 风格 YAML 的编码规则、CLI 用法与源码实现

yq KYaml 格式详解flow 风格 YAML 的编码规则、CLI 用法与源码实现【免费下载链接】yqyq is a portable command-line YAML, JSON, XML, CSV, TOML, HCL and properties processor项目地址: https://gitcode.com/GitHub_Trending/yq/yq本文围绕 yq 仓库中的 KYaml 格式文档 pkg/yqlib/doc/usage/kyaml.md完整讲解 KYaml 的编码规则与全部示例并结合 编码器实现、格式偏好配置 和验收测试说明 KYaml 输出背后的源码逻辑。读完后你既能熟练使用yq -okyaml/-pkyaml也能理解“字符串为何总是双引号、锚点为何被展开、注释为何得以保留”的实现原理。什么是 KYamlKYaml在 yq 中缩写为ky是 YAML 的一个受限子集它只使用flow 风格集合花括号{}与方括号[]因此渲染出的 YAML 数据呈现出紧凑的、JSON 类似的形态同时仍保留 YAML 独有的能力——注释。官方文档 kyaml.md 对它的定位是KYaml is useful when you want YAML data rendered in a compact, JSON-like form while still supporting YAML features like comments.在 格式注册表 中KYaml 与 YAML 是并列的两种输出格式注册名分别为kyaml与别名kyvar KYamlFormat Format{kyaml, []string{ky}, func() Encoder { return NewKYamlEncoder(ConfiguredKYamlPreferences) }, // KYaml is stricter YAML func() Decoder { return NewYamlDecoder(ConfiguredYamlPreferences) }, }注意两处设计要点解码端直接复用 YAML 解码器。源码注释写明“KYaml is stricter YAML”——KYaml 是 YAML 的子集用 YAML 解析器解析 KYaml 输入即可编码端使用专属的kyamlEncoder负责 flow 风格渲染、强制逗号、字符串转义与注释保留。CLI 用法-okyaml与-pkyaml在 README 的参数说明 中kyaml|ky同时出现在输入与输出格式列表中-p, --input-format [auto|a|yaml|y|json|j|kyaml|ky|props|p|csv|c|tsv|t|xml|x|base64|uri|toml|hcl|h|lua|l|ini|i] -o, --output-format [auto|a|yaml|y|json|j|kyaml|ky|props|p|csv|c|tsv|t|xml|x|base64|uri|toml|hcl|h|shell|s|lua|l|ini|i]常用参数及取值参数作用取值/说明-okyaml或--output-formatkyaml以 KYaml 格式输出别名-oky-pkyaml或--input-formatkyaml将输入解析为 KYaml等价于按 YAML 解析别名-pky.ky/.kyaml文件扩展名可被 扩展名自动检测逻辑 识别-In缩进宽度KYaml 默认缩进为 2见下文偏好配置--unwrap-scalar标量直接输出为裸值由 cmd/unwrap_flag.go 定义对应KYamlPreferences.UnwrapScalar验收测试 acceptance_tests/output-format.sh 的testOutputKYaml约 L283-L312用yq e --output-formatkyaml与yq ea --output-formatkyaml双路径验证了流式与非流式模式下的输出一致acceptance_tests/inputs-format.sh 的testInputKYaml约 L157-L186则验证了把 KYaml 文本作为输入、再以 YAML 输出的完整往返round-trip。编码规则全示例以下示例全部来自 kyaml.md 原文档并与其背后的测试场景 kyaml_test.go 一一对应。1. 普通字符串标量始终双引号给定sample.ymlcatyq -okyaml . sample.yml输出cat字符串在 KYaml 输出中总是双引号包裹——这是该格式最基础、也最“JSON 化”的约定。2. flow 映射与序列给定a: b c: - dyq -okyaml . sample.yml输出{ a: b, c: [ d, ], }块风格block style的映射与列表被转换为带显式逗号、每条目一行的 flow 风格结构。3. 非字符串标量保留原生类型给定a: 12 b: true c: null d: true输出{ a: 12, b: true, c: null, d: true, }整数、布尔、null 按原生形式输出而值为true的字符串必须加引号避免被解析回布尔值——这正是“避免隐式类型转换歧义”的规则见下文源码formatScalar。4. 非标识符键需要加引号给定1a: b has space: c输出{ 1a: b, has space: c, }只有符合标识符规则的键才能裸写以数字开头或含空格的键会被双引号包裹。5. 引号内字符串的转义给定a: line1\nline2\t\q\输出{ a: line1\nline2\t\q\, }换行、制表符、双引号均转为\n、\t、\转义序列保证双引号字符串单行合法。6. 编码时保留注释给定与仓库示例文件 examples/kyaml.yml 一致# leading a: 1 # a line # head b b: 2 c: # head d - d # d line - e # trailing输出# leading { a: 1, # a line # head b b: 2, c: [ # head d d, # d line e, ], # trailing }这是 KYaml 相对 JSON 的核心优势头部注释、行内注释、尾部注释在 flow 风格下依然全部保留。验收测试testOutputKYaml的期望输出与示例完全相同可作为可运行的行为基准。7. 锚点与别名被展开KYaml 不支持输出锚点/别名它们会被展开为具体值base: base a: b copy: *base输出{ base: { a: b, }, copy: { a: b, }, }8. 嵌套列表与对象任意深度 flow 风格给定- name: a items: - id: 1 tags: - k: x v: y - k: x2 v: y2 - id: 2 tags: - k: z v: w输出[ { name: a, items: [ { id: 1, tags: [ { k: x, v: y, }, { k: x2, v: y2, }, ], }, { id: 2, tags: [ { k: z, v: w, }, ], }, ], }, ]列表与对象可以任意嵌套KYaml 一律使用 flow 风格集合呈现。输出规则速查规则行为字符串一律双引号包裹并转义非字符串标量按 tag 原样输出int/float/bool/null未知 tag 回退为带引号字符串键仅当匹配标识符规则时裸写否则加双引号集合始终 flow 风格{}/[]每条目一行且带尾随逗号锚点/别名不输出展开为具体值注释head / line / foot 三类注释全部保留空集合输出为紧凑的{}/[]源码剖析KYaml 是怎么渲染出来的偏好配置四个旋钮kyaml.go 定义了KYamlPreferences控制编码行为type KYamlPreferences struct { Indent int // 默认 2 ColorsEnabled bool // 默认 false启用后输出带 ANSI 着色 PrintDocSeparators bool // 默认 true多文档时打印 --- UnwrapScalar bool // 默认 true根节点为标量时直接输出裸值 }ConfiguredKYamlPreferences是全局实例编码工厂 NewKYamlEncoder 读取它生成编码器。UnwrapScalar解释了“为什么示例 1 中裸标量cat文档在测试里以带引号形式输出”——kyaml_test.go 的testKYamlScenario显式把UnwrapScalar置为false来断言文档中的双引号形式而 CLI 默认的UnwrapScalartrue行为则由TestKYamlEncoderEncodeUnwrapScalar验证标量直接输出cat\n。编码器主流程encoder_kyaml.go 的EncodeL34-L70按固定顺序渲染一个文档根节点的头部注释块 → 递归writeNode→ 行内注释 → 换行 → 尾部注释对应文档根节点的FootComment。若开启ColorsEnabled先渲染到临时缓冲再统一着色输出。关键的渲染逻辑flow 映射与尾随逗号writeMapping空映射输出{}否则写{逐对遍历键值节点每个条目按“头部注释 → 缩进 → 键 →:→ 值 →,→ 行内注释 → 换行 → 尾部注释”的顺序输出最后以缩进加}收尾。源码注释明确说明了尾随逗号的设计动机// Always emit a trailing comma; KYAML encourages explicit separators, // and this ensures all quoted strings have a trailing , as requested.键的裸写判定formatKey采用保守的正则^[A-Za-z_][A-Za-z0-9_-]*$——字母或下划线开头、只含字母数字下划线连字符的键才能裸写其余一律双引号转义。这与“示例 4”中1a和has space被加引号完全对应。标量的类型化输出formatScalar按节点 tag 分支——!!null输出null、!!bool输出小写值、!!int/!!float原样输出、!!str双引号转义未知 tag如!!timestamp回退为带引号字符串避免隐式类型歧义。kyaml_test.go 的TestKYamlEncoderScalarFallbackAndEscaping专门验证了!!timestamp回退为2020-01-01T00:00:00Z这一行为。字符串转义escapeDoubleQuotedString\→\\、→\、换行/回车/制表符 →\n/\r/\t小于0x20的控制字符写成 YAML 双引号支持的\uXXXX形式测试用例验证了0x01→\u0001。注释保留writeCommentBlock/writeInlineCommentL268-L318注释块按行补齐#前缀并做 CRLF 归一化行内注释只取第一行并前置一个空格。TestKYamlEncoderCommentBlockAndInlineComment覆盖了 CRLF 输入、已带#前缀、多行行内注释只取首行等细节。锚点不输出CanHandleAliases 返回false告知打印管线不要在 KYaml 中输出别名节点锚点内容会在打印前被展开。writeNode中仍保留了防御分支若仍遇到AliasNode直接递归渲染其指向的值空引用则输出null由TestKYamlEncoderWriteNodeAliasAndUnknown验证。解码端复用 YAML 解析如 format.go 所示KYamlFormat的解码工厂直接返回NewYamlDecoder(...)。inputs-format.sh 中的testInputKYaml展示了完整链路带注释的 KYaml 文本经-pkyaml -P读入后还原为块风格 YAML注释位置一一对应。文档与测试的共生关系一个值得注意的工程细节kyaml.md 这份文档本身是由测试生成的。TestKYamlFormatScenarios 在运行kyamlFormatScenarios断言的同时调用documentScenarios把每个场景的输入、命令、期望输出渲染成 Markdown写入usage/kyaml.md。这意味着文档中每一个示例都必然有对应的自动化断言行为变更会先让测试失败再更新文档kyamlFormatScenarios中skipDoc: true的场景如单独测试 int/bool/null 裸标量只在测试层存在不进入文档文档因此只保留有教学价值的示例。构建裁剪yq_nokyamlKYaml 编码器受构建标签控制带yq_nokyaml标签编译时no_kyaml.go 会让NewKYamlEncoder返回nil即该格式从可用格式列表中消失。仓库的 scripts/build-small-yq.sh 正是通过-tags yq_nolua yq_noini ... yq_nokyaml构建体积更小的 yq 变体。默认构建无该标签下 KYaml 始终可用。小结KYaml 是 yq 提供的“紧凑 flow 风格 YAML”格式以-okyaml输出时获得 JSON 类似的视觉紧凑性同时保留注释这一 YAML 独有能力以-pkyaml输入时走 YAML 解析器。其编码规则强制双引号字符串、尾随逗号、标识符键裸写、锚点展开、未知 tag 回退在 encoder_kyaml.go 中逐条可查并通过 kyaml_test.go 的场景化断言与验收测试 output-format.sh、inputs-format.sh 双重保障。【免费下载链接】yqyq is a portable command-line YAML, JSON, XML, CSV, TOML, HCL and properties processor项目地址: https://gitcode.com/GitHub_Trending/yq/yq创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考