shyaml 0.6.2

通用浏览结构和显示简单值

简单查询简单属性

$ cat test.yaml | shyaml get-value name
MyName !! héhé

使用“.”在键标签之间查询嵌套属性

$ cat test.yaml | shyaml get-value subvalue.how-much
1.1

获取属性类型

$ cat test.yaml | shyaml get-type name
str
$ cat test.yaml | shyaml get-type subvalue.how-much
float

获取结构或序列的长度

$ cat test.yaml | shyaml get-length subvalue
5
$ cat test.yaml | shyaml get-length subvalue.things
3

但这在其他类型上不起作用

$ cat test.yaml | shyaml get-length name
Error: get-length does not support 'str' type. Please provide or select a sequence or struct.

解析结构

从结构属性获取子YAML

$ cat test.yaml | shyaml get-type subvalue
struct
$ cat test.yaml | shyaml get-value subvalue  ## docshtest: ignore-if LIBYAML
how-much: 1.1
how-many: 2
things:
- first
- second
- third
maintainer: Valentin Lab
description: 'Multiline description:

  Line 1

  Line 2

  '

仅通过键进行迭代

$ cat test.yaml | shyaml keys
name
subvalue
subvalue.how-much
subvalue.how-much\more
subvalue.how-much\.more

仅通过键进行迭代（\0终止的字符串）

$ cat test.yaml | shyaml keys-0 subvalue | xargs -0 -n 1 echo "VALUE:"
VALUE: how-much
VALUE: how-many
VALUE: things
VALUE: maintainer
VALUE: description

仅通过值进行迭代（\0终止的字符串强烈推荐）

$ cat test.yaml | shyaml values-0 subvalue |
  while IFS='' read -r -d $'\0' value; do
      echo "RECEIVED: '$value'"
  done
RECEIVED: '1.1'
RECEIVED: '2'
RECEIVED: '- first
- second
- third
'
RECEIVED: 'Valentin Lab'
RECEIVED: 'Multiline description:
Line 1
Line 2
'

通过键和值进行迭代（\0终止的字符串强烈推荐）

$ read-0() {
    while [ "$1" ]; do
        IFS=$'\0' read -r -d '' "$1" || return 1
        shift
    done
  } &&
  cat test.yaml | shyaml key-values-0 subvalue |
  while read-0 key value; do
      echo "KEY: '$key'"
      echo "VALUE: '$value'"
      echo
  done
KEY: 'how-much'
VALUE: '1.1'

KEY: 'how-many'
VALUE: '2'

KEY: 'things'
VALUE: '- first
- second
- third
'

KEY: 'maintainer'
VALUE: 'Valentin Lab'

KEY: 'description'
VALUE: 'Multiline description:
Line 1
Line 2
'
<BLANKLINE>

注意，您将使用get-values获得相同的结果。 get-values将支持序列和结构，而key-values仅支持结构。（有关哪些功能支持什么的完整表格，您可以在用法行中查看）

此外，如果您在非结构如上请求键、值或键值，您将收到一个错误

$ cat test.yaml | shyaml keys name
Error: keys does not support 'str' type. Please provide or select a struct.
$ cat test.yaml | shyaml values subvalue.how-many
Error: values does not support 'int' type. Please provide or select a struct.
$ cat test.yaml | shyaml key-values subvalue.how-much
Error: key-values does not support 'float' type. Please provide or select a struct.

解析序列

使用get-value查询序列

$ cat test.yaml | shyaml get-value subvalue.things
- first
- second
- third

并以Python样式的索引访问单个元素

$ cat test.yaml | shyaml get-value subvalue.things.0
first
$ cat test.yaml | shyaml get-value subvalue.things.-1
third
$ cat test.yaml | shyaml get-value subvalue.things.5
Error: invalid path 'subvalue.things.5', index 5 is out of range (3 elements in sequence).

请注意，这只适用于整数（前面或后面有减号）

$ cat test.yaml | shyaml get-value subvalue.things.foo
Error: invalid path 'subvalue.things.foo', non-integer index 'foo' provided on a sequence.

更有用，一次解析列表使用get-values

$ cat test.yaml | shyaml get-values subvalue.things
first
second
third

请注意，操作称为get-values，并且输出由换行符（这取决于操作系统）分隔，这可能会在您正在解析包含换行符的值时造成混乱。希望shyaml有一个名为get-values-0的操作来通过\0字符终止字符串，这允许完全支持任何类型的值，包括YAML。get-values为struct类型输出键和值，而对于sequence类型则只输出值

$ cat test.yaml | shyaml get-values-0 subvalue |
  while IFS='' read -r -d '' key &&
        IFS='' read -r -d '' value; do
      echo "'$key' -> '$value'"
  done
'how-much' -> '1.1'
'how-many' -> '2'
'things' -> '- first
- second
- third
'
'maintainer' -> 'Valentin Lab'
'description' -> 'Multiline description:
Line 1
Line 2
'

请注意，如果get-values{,-0}实际上在struct上工作，则使用等效的key-values{,0}可能更明确。应该注意，key-values{,0}并不完全相同，因为它旨在仅与struct一起使用，并且如果不这样做会报错。

您还应注意到显示的值是YAML兼容的。因此，如果它们是复杂的，您可以重新使用shyaml来解析它们的内容。

当然，get-values应仅对序列元素调用

$ cat test.yaml | shyaml get-values name
Error: get-values does not support 'str' type. Please provide or select a sequence or struct.

解析YAML文档流

YAML输入可以是文档流，然后操作将应用于每个文档

$ i=0; while true; do
      ((i++))
      echo "ingests:"
      echo " - data: xxx"
      echo "   id: tag-$i"
      if ((i >= 3)); then
          break
      fi
      echo "---"
done | shyaml get-value ingests.0.id | tr '\0' '&'
tag-1&tag-2&tag-3

请注意，如果未使用-y模式，则默认使用NUL字符来分隔输出迭代。您可以使用它来分隔每个输出。-y模式将使用传统的YAML方式来分隔文档（这是---）。

所以

$ i=0; while true; do
      ((i++))
      echo "ingests:"
      echo " - data: xxx"
      echo "   id: tag-$i"
      if ((i >= 3)); then
          break
      fi
      echo "---"
done | shyaml get-value -y ingests.0.id  ## docshtest: ignore-if LIBYAML
tag-1
...
---
tag-2
...
---
tag-3
...

请注意，不支持使用任何可以输出多个值的查询（如所有可以后缀为*-0的查询）与多文档YAML一起使用

$ i=0; while true; do
      ((i++))
      echo "ingests:"
      echo " - data: xxx"
      echo "   id: tag-$i"
      if ((i >= 3)); then
          break
      fi
      echo "---"
done | shyaml keys ingests.0 >/dev/null
Error: Source YAML is multi-document, which doesn't support any other action than get-type, get-length, get-value

你可能会注意到，输出似乎被缓冲。前面的内容仅在末尾一次性显示。如果你需要YAML文档的连续流，则需要命令行选项 -L 来强制按行逐行读取文件，以确保每个文档都能尽快正确解析。这意味着一旦检测到YAML文档的结尾（--- 或 EOF）

如果没有 -L，在我们杀死 shyaml 进程之前

$ i=0; while true; do
      ((i++))
      echo "ingests:"
      echo " - data: xxx"
      echo "   id: tag-$i"
      if ((i >= 2)); then
          break
      fi
      echo "---"
      sleep 10
done 2>/dev/null | shyaml get-value ingests.0.id & pid=$! ; sleep 2; kill $pid

如果使用 -L，在我们杀死 shyaml 进程之前

$ i=0; while true; do
      ((i++))
      echo "ingests:"
      echo " - data: xxx"
      echo "   id: tag-$i"
      if ((i >= 2)); then
          break
      fi
      echo "---"
      sleep 10
done 2>/dev/null | shyaml get-value -L ingests.0.id & pid=$! ; sleep 2; kill $pid
tag-1

使用 -y 是强制输出可解析为流的YAML，这可以帮助你链式调用 shyaml

$ i=0; while true; do
      ((i++))
      echo "ingests:"
      echo " - data: xxx"
      echo "   id: tag-$i"
      if ((i >= 3)); then
          break
      fi
      echo "---"
      sleep 0.2
done | shyaml get-value ingests.0 -L -y | shyaml get-value id | tr '\0' '\n'
tag-1
tag-2
tag-3

空字符串仍然被视为空YAML文档

$ echo | shyaml get-value "toto"
Error: invalid path 'toto', can't query subvalue 'toto' of a leaf (leaf value is None).

包含‘.’的键

使用 \\ 来访问包含 \ 的键，使用 \. 来访问包含字面 . 的键。只需注意shell转义（示例使用单引号）

$ cat test.yaml | shyaml get-value 'subvalue\.how-much'
1.2
$ cat test.yaml | shyaml get-value 'subvalue\.how-much\\more'
1.3
$ cat test.yaml | shyaml get-value 'subvalue\.how-much\\.more' default
default

最后一个例子没有正确转义最后的 .，这是正确的版本

$ cat test.yaml | shyaml get-value 'subvalue\.how-much\\\.more' default
1.4

空字符串键

是的，shyaml 支持空字符串键。你可能永远不会用到它，但它包含在YAML规范中。因此，shyaml 支持它

$ cat <<EOF > test.yaml
empty-sub-key:
    "":
       a: foo
       "": bar
"": wiz
EOF

$ cat test.yaml | shyaml get-value empty-sub-key..
bar
$ cat test.yaml | shyaml get-value ''
wiz

请注意，一个空字符串与没有任何字符串是不同的

$ cat <<EOF > test.yaml
"":
   a: foo
   b: bar
"x": wiz
EOF
$ cat test.yaml | shyaml keys

x
$ cat test.yaml | shyaml keys ''
a
b

第一个询问根YAML的键，第二个询问位于根YAML中空字符串命名元素的内容的键

处理缺失路径

shyaml命令行上的第三个参数是DEFAULT参数。如果给定的KEY在YAML结构中未找到，则shyaml会返回你提供的默认值。

截至版本 < 0.3，此参数默认为空字符串。对于所有版本0.3（包括）以上，如果未提供，则将打印错误消息

$ echo "a: 3" | shyaml get-value a mydefault
3

$ echo "a: 3" | shyaml get-value b mydefault
mydefault

$ echo "a: 3" | shyaml get-value b
Error: invalid path 'b', missing key 'b' in struct.

您可以通过指定空字符串作为第三个参数来模拟v0.3之前的行为

$ echo "a: 3" | shyaml get-value b ''

从版本0.6开始，您还可以使用 -q 或 --quiet 在YAML结构中未找到KEY时静默失败

$ echo "a: 3" | shyaml -q get-value b; echo "errlvl: $?"
errlvl: 1
$ echo "a: 3" | shyaml -q get-value a; echo "errlvl: $?"
3errlvl: 0

有序映射

目前，在shell脚本中使用shyaml涉及愉快地接受YAML输入并输出YAML输出，这些输出将被进一步处理。

这非常有效。

在版本 0.4.0 之前，shyaml会大胆地重新排序（按字母顺序排序）映射中的键。如果这应该根据规范认为是无害的（映射确实是未排序的，这意味着顺序不重要），在实践中，YAML用户可能会因为shyaml将他们的YAML弄乱并想要赋予基本YAML映射意义而感到不满。

我是谁，要禁止这种YAML映射的使用？因此，从版本 0.4.0 开始，shyaml将愉快地保留你的映射顺序

$ cat <<EOF > test.yaml
mapping:
  a: 1
  c: 2
  b: 3
EOF

对于 shyaml 版本 0.4.0 之前

# shyaml get-value mapping < test.yaml
a: 1
b: 3
c: 2

对于包括和高于 0.4.0 的 shyaml 版本

$ shyaml get-value mapping < test.yaml
a: 1
c: 2
b: 3

严格YAML以供进一步处理

可以通过使用 shyaml 的输出递归和广泛地处理 yaml，并将输出重定向到 shyaml。大部分输出都是 YAML 格式。大部分？嗯，为了方便使用，字面量键（字符串、数字）会直接输出，而不使用 YAML 引号，这通常很方便。

但这会带来不一致行为的结果。因此，当处理 shyaml 输出的 YAML 时，你可能需要考虑使用 --yaml（或 -y）选项来仅输出严格的 YAML。

但是，当你想要输出字符串时，你需要再次调用 shyaml get-value 来显式地取消引号。

对象标签

YAML 规范允许对象标签，这允许你将本地数据映射到应用程序中的对象。

在使用 shyaml 时，我们不想与这些标签纠缠，但仍允许解析它们的内部结构。

get-type 会正确地给出对象的类型

$ cat <<EOF > test.yaml
%TAG !e! tag:example.com,2000:app/
---
- !e!foo "bar"
EOF

$ shyaml get-type 0 < test.yaml
tag:example.com,2000:app/foo

get-value 与 -y（见严格 YAML 部分）将给出完整的带标签的 YAML 值

$ shyaml get-value -y 0 < test.yaml  ## docshtest: ignore-if LIBYAML
!<tag:example.com,2000:app/foo> 'bar'

另一个例子

$ cat <<EOF > test.yaml
%TAG ! tag:clarkevans.com,2002:
--- !shape
  # Use the ! handle for presenting
  # tag:clarkevans.com,2002:circle
- !circle
  center: &ORIGIN {x: 73, y: 129}
  radius: 7
- !line
  start: *ORIGIN
  finish: { x: 89, y: 102 }
- !label
  start: *ORIGIN
  color: 0xFFEEBB
  text: Pretty vector drawing.
EOF
$ shyaml get-type 2 < test.yaml
tag:clarkevans.com,2002:label

你仍然可以遍历内部值

$ shyaml get-value -y 2.start < test.yaml
x: 73
y: 129

注意，所有全局标签都将被解析和简化（如 !!map、!!str、!!seq），但不会解析未知的本地标签

$ cat <<EOF > test.yaml
%YAML 1.1
---
!!map {
  ? !!str "sequence"
  : !!seq [ !!str "one", !!str "two" ],
  ? !!str "mapping"
  : !!map {
    ? !!str "sky" : !myobj "blue",
    ? !!str "sea" : !!str "green",
  },
}
EOF

$ shyaml get-value < test.yaml  ## docshtest: ignore-if LIBYAML
sequence:
- one
- two
mapping:
  sky: !myobj 'blue'
  sea: green

空文档

当提供空文档时，shyaml 会将该文档视为包含一个 null 值

$ echo | shyaml get-value -y  ## docshtest: ignore-if LIBYAML
null
...

使用字符串

在调用 shyaml 而不带任何参数时，将打印出可用的快速提示信息。

$ shyaml
Error: Bad number of arguments.
Usage:

    shyaml {-h|--help}
    shyaml {-V|--version}
    shyaml [-y|--yaml] [-q|--quiet] ACTION KEY [DEFAULT]
<BLANKLINE>

完整的帮助信息可以通过使用标准 -h 或 -help 获取。

$ shyaml --help

Parses and output chosen subpart or values from YAML input.
It reads YAML in stdin and will output on stdout it's return value.

Usage:

    shyaml {-h|--help}
    shyaml {-V|--version}
    shyaml [-y|--yaml] [-q|--quiet] ACTION KEY [DEFAULT]


Options:

    -y, --yaml
              Output only YAML safe value, more precisely, even
              literal values will be YAML quoted. This behavior
              is required if you want to output YAML subparts and
              further process it. If you know you have are dealing
              with safe literal value, then you don't need this.
              (Default: no safe YAML output)

    -q, --quiet
              In case KEY value queried is an invalid path, quiet
              mode will prevent the writing of an error message on
              standard error.
              (Default: no quiet mode)

    -L, --line-buffer
              Force parsing stdin line by line allowing to process
              streamed YAML as it is fed instead of buffering
              input and treating several YAML streamed document
              at once. This is likely to have some small performance
              hit if you have a huge stream of YAML document, but
              then you probably don't really care about the
              line-buffering.
              (Default: no line buffering)

    ACTION    Depending on the type of data you've targetted
              thanks to the KEY, ACTION can be:

              These ACTIONs applies to any YAML type:

                get-type          ## returns a short string
                get-value         ## returns YAML

              These ACTIONs applies to 'sequence' and 'struct' YAML type:

                get-values{,-0}   ## returns list of YAML
                get-length        ## returns an integer

              These ACTION applies to 'struct' YAML type:

                keys{,-0}         ## returns list of YAML
                values{,-0}       ## returns list of YAML
                key-values,{,-0}  ## returns list of YAML

              Note that any value returned is returned on stdout, and
              when returning ``list of YAML``, it'll be separated by
              a newline or ``NUL`` char depending of you've used the
              ``-0`` suffixed ACTION.

    KEY       Identifier to browse and target subvalues into YAML
              structure. Use ``.`` to parse a subvalue. If you need
              to use a literal ``.`` or ``\``, use ``\`` to quote it.

              Use struct keyword to browse ``struct`` YAML data and use
              integers to browse ``sequence`` YAML data.

    DEFAULT   if not provided and given KEY do not match any value in
              the provided YAML, then DEFAULT will be returned. If no
              default is provided and the KEY do not match any value
              in the provided YAML, shyaml will fail with an error
              message.

Examples:

     ## get last grocery
     cat recipe.yaml       | shyaml get-value groceries.-1

     ## get all words of my french dictionary
     cat dictionaries.yaml | shyaml keys-0 french.dictionary

     ## get YAML config part of 'myhost'
     cat hosts_config.yaml | shyaml get-value cfgs.myhost

<BLANKLINE>

使用无效的关键字将引发错误和用法信息。

$ shyaml get-foo
Error: 'get-foo' is not a valid action.
Usage:

    shyaml {-h|--help}
    shyaml {-V|--version}
    shyaml [-y|--yaml] [-q|--quiet] ACTION KEY [DEFAULT]
<BLANKLINE>

版本信息

通过使用 shyaml --version（或 -V），你可以获取有用的信息（如果出现错误）或者如果你想检查 shyaml 是否使用 libyaml 的 C 绑定。

# shyaml -V      ## Example of possible output
version: unreleased
PyYAML: 3.13
libyaml available: 0.1.6
libyaml used: True
Python: 2.7.8 (default, Oct 20 2014, 15:05:19)  [GCC 4.9.1]

请注意，即使 libyaml 可用，你也可以通过使用 FORCE_PYTHON_YAML_IMPLEMENTATION 来强制使用 Python 实现。

$ FORCE_PYTHON_YAML_IMPLEMENTATION=1 shyaml --version | grep "^libyaml used:"
libyaml used: False

推送请求指南

你可以发送任何代码。我会查看它，并自己将其集成到代码库中，并保留你作为作者。这个过程可能需要一些时间，如果你遵循以下指南，它将更快：

• 使用 PEP8 或 pylint 检查你的代码。尽量保持 80 列宽。

• 按最小关注点分开你的提交。

• 每个提交都应该通过测试（以便于二分查找）

• 每个功能/错误修复提交应包含代码、测试和文档。

• 带有排版或代码美观更改的次要提交非常受欢迎。这些应该在提交摘要中标记为 !minor。

• 提交信息应遵循 gitchangelog 规则（检查 git 日志以获取示例）

• 如果提交修复了问题或完成了特性的实现，请在摘要中提及。

如果您在这里没有找到答案的指南问题，请检查当前的 git log，您可能找到以前的提交，这将向您展示如何处理您的问题。

0.6.2 (2020-12-15)

修复

• UTF-8 值会导致跟踪回溯（修复 #51）[Valentin Lab]

0.6.1 (2018-12-14)

0.6.0 (2018-12-13)

0.5.2 (2018-04-25)

修复

• 缺少关于 get-length 的文档，并纠正了帮助消息中的错误。[Valentin Lab]

• 在查询缺少的键时移除了 Python 3.0 异常。（修复 #34）[Valentin Lab]

0.5.1 (2018-03-06)

0.5.0 (2017-03-23)

新增

• 引入 -y 选项以强制完整 yaml 输出。[Valentin Lab]

  默认情况下，直接打印的文本字符串未加引号且可直接使用。如果这非常有用，但在许多情况下，这可能不一致且模糊，尤其是在该字符串本身是 YAML 表示的情况下。

  这实际上可能导致在重新使用 shyaml 输出进行进一步解析时出现微妙的错误。

  因此，如果您想对未加引号的文本类型进行进一步处理，请使用 -y。如果您期望一个字符串并希望它为纯原始字符串，请避免使用 -y。

0.4.2 (2017-02-08)

修复

• <<: YAML 合并功能支持。[Valentin Lab]

0.4.1 (2016-08-29)

修复

• 在 python2 中，Unicode 字符串将被显示为字面值（修复 #26）[Valentin Lab]

  str 不是匹配 python 2 中所有字符串类型的正确类型。因此，Unicode 字符串（通常由带重音的字符产生）将被打印为引号（Python 的表示形式）。

0.4.0 (2016-01-11)

新增

• 避免在输出中对映射键进行排序。[Valentin Lab]

  shyaml 的几个命令将输出 YAML。但在处理过程中，整个内容都被解析和重新写入。这可能导致与原始输入的差异。在某些用例中，键的顺序可能会引起麻烦，尽管映射本身不应该有序，但这些是通过文件顺序性排序的，使用 'omap' 通常很繁琐。shyaml 现在保留键遇到的原始顺序。

0.3.4 (2015-03-06)

0.2.2 (2014-03-19)

修复

• 没有任何参数时，被视为一个空字符串参数。感谢Yassa Bb。（修复了#6）[Valentin Lab]

0.2.1 (2013-11-23)

0.2.0 (2013-05-03)

0.1.3 (2013-03-29)

修复

• 移除了shyaml输出末尾的冗余换行符。[Valentin Lab]

• 支持查询“无”内容。现在返回整个输入YAML。[Valentin Lab]

  在此修复之前，您不能单独请求shyaml get-value，即使这样做有意义，但它完全无用，因为它返回整个YAML输入。

0.1.2 (2013-03-23)

新增

• 支持列表索引（参见README.rst）。[Valentin Lab]

• 在解析结构时捕获异常，并输出一个干净的错误信息。[Valentin Lab]

0.1.1 (2013-02-27)

更改

• 一些小的改进，并添加了“安装”部分。[Valentin Lab]

0.1.0 (2013-02-27)

• 首次导入。[Valentin Lab]