yaml paths

1. Introduction
2. Self-Help Documentation

Introduction

The yaml-paths command-line tool scans YAML/JSON/Compatible data for any components matching one or more search expressions. User options permitting, this includes keys, values, Array elements, as well as Anchor and their Alias names. Given the appropriate decryption key, EYAML values can be scanned. Results can be filtered or expanded. Multiple sources can be scanned by a single command, including files and STDIN as well as multi-document files to either or both.

This page explores the various command-line arguments understood by yaml-paths. For real-world examples of using it, please check yaml-paths Examples.

Self-Help Documentation

When the --help (-h) flag is passed into yaml-paths, it produces this output:

usage: yaml-paths [-h] [-V] -s EXPRESSION [-c EXPRESSION] [-m] [-L] [-F] [-X]
                  [-P] [-n] [-t ['.', '/', 'auto', 'dot', 'fslash']]
                  [-i | -k | -K] [-a] [-A | -Y | -y | -l] [-e] [-x EYAML]
                  [-r PRIVATEKEY] [-u PUBLICKEY] [-S] [-d | -v | -q]
                  [YAML_FILE [YAML_FILE ...]]

Returns zero or more YAML Paths indicating where in given YAML/JSON/Compatible
data one or more search expressions match. Values, keys, and/or anchors can be
searched. EYAML can be employed to search encrypted values.

positional arguments:
  YAML_FILE             one or more YAML files to search; omit or use - to
                        read from STDIN

optional arguments:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  -c EXPRESSION, --except EXPRESSION
                        except results matching this search expression; can be
                        set more than once
  -m, --expand          expand matching parent nodes to list all permissible
                        child leaf nodes (see "reference handling options" for
                        restrictions)
  -t ['.', '/', 'auto', 'dot', 'fslash'], --pathsep ['.', '/', 'auto', 'dot', 'fslash']
                        indicate which YAML Path seperator to use when
                        rendering results; default=dot
  -a, --refnames        also search the names of &anchor and *alias references
  -S, --nostdin         Do not implicitly read from STDIN, even when there are
                        no - pseudo-files in YAML_FILEs with a non-TTY session
  -d, --debug           output debugging details
  -v, --verbose         increase output verbosity
  -q, --quiet           suppress all non-result output except errors

required settings:
  -s EXPRESSION, --search EXPRESSION
                        the search expression; can be set more than once

result printing options:
  -L, --values          print the values or elements along with each YAML Path
                        (complex results are emitted as JSON; use --expand to
                        emit only simple values)
  -F, --nofile          omit source file path and name decorators from the
                        output (applies only when searching multiple files)
  -X, --noexpression    omit search expression decorators from the output
  -P, --noyamlpath      omit YAML Paths from the output (useful with --values
                        or to indicate whether a file has any matches without
                        printing them all, perhaps especially with
                        --noexpression)
  -n, --noescape        omit escape characters from special characters in
                        printed YAML Paths; this is unsafe for feeding the
                        resulting YAML Paths into other YAML Path commands
                        because the symbols that would be escaped have special
                        meaning to YAML Path processors

key name searching options:
  -i, --ignorekeynames  (default) do not search key names
  -k, --keynames        search key names in addition to values and array
                        elements
  -K, --onlykeynames    only search key names (ignore all values and array
                        elements)

reference handling options:
  Indicate how to treat anchor and alias references. An anchor is an
  original, reusable key or value. All aliases become replaced by the
  anchors they reference when YAML data is read. These options specify how
  to handle this duplication of keys and values. Note that the default
  behavior includes all aliased keys but not aliased values.

  -A, --anchorsonly     include only original matching key and value anchors
                        in results, discarding all aliased keys and values
                        (including child nodes)
  -Y, --allowkeyaliases
                        (default) include matching key aliases, permitting
                        search traversal into their child nodes
  -y, --allowvaluealiases
                        include matching value aliases (does not permit search
                        traversal into aliased keys)
  -l, --allowaliases    include all matching key and value aliases

EYAML options:
  Left unset, the EYAML keys will default to your system or user defaults.
  Both keys must be set either here or in your system or user EYAML
  configuration file when using EYAML.

  -e, --decrypt         decrypt EYAML values in order to search them
                        (otherwise, search the encrypted blob)
  -x EYAML, --eyaml EYAML
                        the eyaml binary to use when it isn't on the PATH
  -r PRIVATEKEY, --privatekey PRIVATEKEY
                        EYAML private key
  -u PUBLICKEY, --publickey PUBLICKEY
                        EYAML public key

A search or exception EXPRESSION takes the form of a YAML Path search operator
-- %, $, =, ^, >, <, >=, <=, =~, or ! -- followed by the search term, omitting
the left-hand operand. For more information about YAML Paths, please visit
https://github.com/wwkimball/yamlpath/wiki. To report issues with this tool or
to request enhancements, please visit
https://github.com/wwkimball/yamlpath/issues.

For a deeper dive into these options:

• Search Filters

  • --search (-s) is one or more Search Expressions -- omitting the square-brackets ([]) and operand, like OPERATOR TERM instead of [OPERAND OPERATOR TERM] -- which include results from the scan. Set another --search (-s) for each expression.
  • --except (-c) is one or more Search Expressions -- omitting the square-brackets ([]) and operand, like OPERATOR TERM instead of [OPERAND OPERATOR TERM] -- which exclude results from the scan. Set another --except (-c) for each expression.
  • --refnames (-a) allows the scan to evaluate the names of Anchors and Aliases.
  • --ignorekeynames (-i) disallows searching Hash key names. This is the default mode for key name searches. In this mode, only Array elements and the value of Hash key-value pairs are searched.
  • --keynames (-k) allow searching Hash key names in addition to values and Array elements.
  • --onlykeynames (-K) restricts searching to only Hash key names, ignoring all values and Array elements; this is the opposite of the default mode.
  • --anchorsonly (-A) restricts matching to only the original Anchor, disregarding all Aliases. This mode blocks traversal into Aliased Hash keys.
  • --allowkeyaliases (-Y) permits matching Aliased Hash keys, allowing traversal into their children nodes. This does not permit matching Aliased values. This is the default Anchor and Alias matching mode, eliminating all duplicate Aliased values.
  • --allowvaluealiases (-y) permits matching Aliased values (Array elements and the value portion of Hash key-value pairs) but not Aliased Hash keys. This mode blocks traversal into Aliased Hash keys.
  • --allowaliases (-l) permits matching both Aliased Hash keys and Aliased values. This mode is the "most noisy" in that it will match all duplicates caused by Aliased keys and values. Since changing the Anchor for Aliases is all that is required to affect a "one version of the truth" change to a YAML data file, this is usually more noise than necessary. However, use this mode when you specifically need to find every instance of an Anchor's use.

• Search Result Display

  • --expand (-m) vertically expands complex results, listing each Array element and Hash Key-Value pair on a separate line instead of displaying single-line JSON results.
  • --values (-L) display the value of each match rather that just the YAML Path to the value.
  • --nofile (-F) omit the file-name and sub-document index from the display results.
  • --noexpression (-X) omit display of the matching Search Expression. This decorator is normally displayed only when using more than one.
  • --noyamlpath (-P) omit display of the matching YAML Path. This is typically the result most users are after but when you are interested only in the --values (-L), this -- along with --nofile (-L), --noexpression (-X), and --values (-L) -- can reduce the output to just the values.
  • --noescape (-n) omit escape symbols (\) from printed YAML Paths, if displayed. While this option generates user-friendly output, any YAML Paths printed with special -- unescaped -- characters cannot be used as input to other YAML Path parsers and processors lest they generate errors or other unexpected outcomes.

• EYAML (Encrypted YAML) Data Handling

  • --decrypt (-e) Permit decrypting encrypted values to enable matching them. When scanning encrypted data without setting this option, the encrypted blob is itself searched for matches.
  • --eyaml (-x) specifies the fully-qualified path to the external eyaml command. This is useful whenever you need to employ a custom version of eyaml or the command is not on the system PATH.
  • --privatekey (-r) specifies the EYAML private key to use with the external eyaml command when querying encrypted data. This value is necessary only when your user or system EYAML configuration does not already supply this key or you need to override it.
  • --publickey (-u) specifies the EYAML public key to use with the external eyaml command. This value is necessary only when your user or system EYAML configuration does not already supply this key or you need to override it and your version of the eyaml command requires it to decrypt data.

• Data Input

  • --nostdin (-S) is useful only when using this command-line tool in a context where data is available on STDIN but you do not wish this command to consume it or you need to block access to STDIN against any unintended attempts to read from it.
  • --pathsep (-t) is (rarely) used to override automatic detection of the separator used in the YAML Paths for --search (-s) and --except (-c); this is useful for "weird" YAML Paths where it would not typically be obvious which separator is in use.

• Processing Output Control

  • --debug (-d) generates a vast amount of detailed information as the document is parsed and the value changed. It is particularly helpful when tracing YAML Path behavior or troubleshooting other options.
  • --verbose (-v) generates slightly more status messages as the value is changed.
  • --quiet (-q) suppresses normal status and processing messages.