2 releases
0.1.1 | Jul 12, 2020 |
---|---|
0.1.0 | Jul 12, 2020 |
#147 in #yaml
22 downloads per month
81KB
2K
SLoC
ry
ry searches yaml for matching paths/values. It's written in rust and inspired by yq
Usage
ry <yaml_file_name> <path_expression>
Returns the nodes in yaml_file_name
matching path_expression
. See Basic for path_expression
examples.
Basic
For a file test_map.yml
containing:
a:
b: 1
then:
ry test_map.yml 'a.b'
will return 1
.
And for a file test_array.yml
containing:
letters:
- a
- b
then:
ry test_array.yml 'letters[1]'
will return b
.
From STDIN
For the test_map.yml
file above, the following:
cat test.yml | target/release/ry - 'a.b'
will return 1
. Note that the -
character represents STDIN
.
Wildcard matching
The '*'
character acts as a wildcard in path expressions. For a file test_wild.yml
containing:
a:
item_b:
f: 1
thing_c:
f: 2
item_d:
f: 3
then:
ry test_wild.yml 'a.*.f'
will return:
1
2
3
You can also use wildcards with a prefix, for example:
ry test_wild.yml 'a.item*.f'
will return:
1
3
Finally, wildcards can be used to match array elements as well. For the file test_wild_array.yml
containing:
letters:
- a
- b
- c
then:
ry test_wild_array.yml 'letters[*]'
will return:
a
b
c
Deep splat matching
The deep splat pattern '**'
is used to recursively match nodes in a file. For the file test_splat.yml
containing:
a:
b1:
c: # MATCH
c: crabs_1 # MATCH
d: bears
b2:
c: crabs_2
d: bears
b3:
e:
- f:
c: crabs_3 # MATCH
g: bears
- f:
g:
c: crabs_4 # MATCH
h: bears
- f: bears
then:
ry test_splat.yml 'a.**.c'
will return:
crabs_1
c: crabs_1
crabs_2
crabs_3
crabs_4
Printing matching paths
The --printMode
feature flag allows you to print the paths leading to matching nodes. For a file test_wild.yml
containing:
a:
item_b:
f: 1
thing_c:
f: 2
item_d:
f: 3
then:
ry test_wild.yml 'a.*.f' --printMode p
will return:
a.item_b.f
a.thing_c.f
a.item_d.f
while:
ry test_wild.yml 'a.*.f' --printMode pv
will return both matching paths and values:
a.item_b.f: 1
a.thing_c.f: 2
a.item_d.f: 3
Note that:
ry test_wild.yml a.*.f --printMode v
is equivalent to the default:
ry test_wild.yml 'a.*.f'
which will just return matching values:
1
2
3
Multi-doc support
If you have multiple documents in a single yaml file, the -d
feature flag allows you to apply your search to a specific document. By default all documents are searched.
For the file test_multi_doc.yml
containing:
a:
b: 1
crabs: here
---
a:
b: 2
then:
ry test_multi_doc.yml 'a.b' -d1
will return 2
, while:
ry test_multi_doc.yml 'a.b' -d0
will return 1
. Finally:
ry test_multi_doc.yml 'a.b' -d'*'
will return:
1
2
Collecting results into an array
The feature flag --collect
will collect the output elements into an array. For the file test_collect.yml
containing:
letters:
a:
crab: 1
b:
crab: 2
c:
crab: 3
then:
ry test_collect.yml 'letters.*.crab'
will return:
1
2
3
while:
ry test_collect.yml 'letters.*.crab' --collect
will return:
- 1
- 2
- 3
Printing the length of results
The --length
feature flag prints the length of results.
For arrays, length means the number of items. For the file test_array_length.yml
containing:
looking:
- here
- there
- elsewhere
then:
ry test_array_length.yml 'looking' --length
will return 3
.
For maps, length means the number of entries. For the file test_map_length.yml
containing:
looking:
here: yes
there: yes
elsewhere: no
then:
ry test_map_length.yml 'looking' --length
will return 3
.
Finally for scalars, length means the length of the scalar. For the file test_string_length.yml
containing:
looking: string
then:
ry test_string_length.yml 'looking' --length
will return 6
. For the file test_int_length.yml
containing:
looking: 100
then:
ry test_int_length.yml 'looking' --length
will return 3
.
Anchors and Aliases
Anchors and aliases will be substituted automatically. This means that for a file anchor_and_alias.yml
containing:
first: &crab
a: b
second: *crab
then:
ry anchor_and_alias.yml 'second.a'
will return b
.
Advanced
Filtering by children nodes
You can filter parent nodes based on their children. For the file test_filter.yml
containing:
a:
- b:
c: magic
d: crab
- b:
c: magically
d: bear
- b:
c: magic
d: more crab
- b:
careful: magic
d: most crab
then
ry test_filter.yml 'a.(b.c==magic).d' --printMode pv
will return:
a[0].d: crab
a[2].d: more crab
Note that
(b.c==magic)
filters based on the children of each array member undera
, but it returns the parents of those children for further searching (i.e. the filter(b.c==magic)
returns array members undera
).
Filtering also supports wildcards, for example:
ry test_filter.yml 'a.(b.c*==magic*).d' --printMode pv
will return:
a[0].d: crab
a[1].d: bear
a[2].d: more crab
a[3].d: most crab
Matching on children values
Similar filtering by children nodes, it's also possible to filter based on children values.
For arrays, this just means matching the value in the array. For the file matching_array.yml
containing:
crabs:
- abby
- carl
- alexandra
then:
ry matching_array.yml 'crabs(.==a*)' --printMode pv
will return:
crabs[0]: abby
crabs[2]: alexandra
For maps, this just means matching the map entry's value. For the file matching_map.yml
containing:
crabs:
name_1: abby
name_2: carl
name_3: alexandra
then:
ry matching_map.yml 'crabs(.==a*)' --printMode pv
will return:
crabs.name_1: abby
crabs.name_3: alexandra
Notice that this ignores the keys of the map entries.
Length of filtered results
The length of filtered results get printed individually. For the file test_filtered_length.yml
containing:
crabs:
- abby
- carl
- alexandra
then:
ry test_filtered_length.yml 'crabs(.==a*)' --printMode pv --length
will return:
crabs[0]: 4
crabs[2]: 9
However, if you want to know the total number of filtered results, you can use the --collect
and --length
feature flags together. Then:
ry test_filtered_length.yml 'crabs(.==a*)' --length --collect
will return 2
.
Dependencies
~2MB
~31K SLoC