taigrr/yq
1
0
Fork 0
mirror of https://github.com/taigrr/yq synced 2025-01-18 04:53:17 -08:00
Code Issues Projects Releases Wiki Activity

GitBook: [v3.x] 17 pages modified

Browse Source
This commit is contained in:
Mike Farah
2020-06-16 01:19:04 +00:00
committed by gitbook-bot
parent 086f0ec6b9
commit 85bb1aec16
17 changed files with 2347 additions and 84 deletions
Download Patch File Download Diff File Expand all files Collapse all files

94
usage/convert.md Normal file
View File

@@ -0,0 +1,94 @@
# Working with JSON
## Yaml to Json
To convert output to json, use the `--tojson` \(or `-j`\) flag. This is supported by all commands. You can change the json output format by using the [pretty print](output-format.md#pretty-print) or [indent](output-format.md#indent) flags. _Note that due to the implementation of the JSON marshaller in GO, object keys will be sorted on output \(_[_https://golang.org/pkg/encoding/json/\#Marshal_](https://golang.org/pkg/encoding/json/#Marshal)_\)._
Given a sample.yaml file of:
```yaml
b:
c: 2
```
then
```bash
yq r -j sample.yaml
```
will output
```javascript
{"b":{"c":2}}
```
To format the json:
```yaml
yq r --prettyPrint -j sample.yaml
```
will yield
```yaml
{
"b": {
"c": 2
}
}
```
### Multiple matches
Each matching yaml node will be converted to json and printed out on a separate line. The [prettyPrint](output-format.md#pretty-print) and [indent](output-format.md#indent) flags will still work too. ****
Given a sample.yaml file of:
```yaml
bob:
c: 2
bab:
c: 5
```
then
```bash
yq r -j sample.yaml b*
```
will output
```javascript
{"c":2}
{"c":5}
```
## Json to Yaml
To read in json, just pass in a json file instead of yaml, it will just work - as json is a subset of yaml. However, you will probably want to [pretty print the output](output-format.md#pretty-print) to look more like an idiomatic yaml document.
e.g given a json file
```javascript
{"a":"Easy! as one two three","b":{"c":2,"d":[3,4]}}
```
then
```bash
yq r --prettyPrint sample.json
```
will output
```yaml
a: Easy! as one two three
b:
c: 2
d:
- 3
- 4
```

161
usage/output-format.md Normal file
View File

@@ -0,0 +1,161 @@
---
description: Flags to control yaml and json output format
---
# Output format
These flags are available for all `yq` commands.
## Colorize Output
Use the `--colors/-C`flag to print out yaml with colors. This does not work when outputing in JSON format.
## Pretty Print
Use the `--prettyPrint/-P` flag to enforce a formatting style for yaml documents. This is particularly useful when reading a json file \(which is a subset of yaml\) and wanting to format it in a more conventional yaml format.
Given:
```text
{
"apples": [
{
"are": "great"
}
]
}
```
Then:
```text
yq r --prettyPrint sample.json
```
Will print out:
```text
apples:
- are: great
```
This works in the same manner for yaml files:
```text
"apples": [are: great]
```
will format to:
```text
apples:
- are: great
```
## Indent
Use the indent flag `--indent/-I` to control the number of spaces used for indentation. This also works for JSON output. The default value is 2.
Note that lists are indented at the same level as the map key at indent level 2, but are more deeply indented at indent level 4 and greater. This is \(currently\) a quirk of the underlying [yaml parser](https://github.com/go-yaml/yaml/tree/v3).
Given:
```text
apples:
collection:
- name: Green
- name: Blue
favourite: Pink Lady
```
Then:
```text
yq r -I4 sample.yaml
```
Will print out:
```text
apples:
collection:
- name: Green
- name: Blue
favourite: Pink Lady
```
With json, you must also specify the `--prettyPrint/-P` flag
```text
yq r -j -P -I4 sample.yaml
```
yields
```text
{
"apples": {
"collection": [
{
"name": "Green"
},
{
"name": "Blue"
}
],
"favourite": "Pink Lady"
}
}
```
## Unwrap scalars
By default scalar values are 'unwrapped', that is only their value is printed \(except when outputting as JSON\). To print out the node as-is, with the original formatting an any comments pass in `--unwrapScalar=false`
Given data.yml:
```yaml
a: "Things" # cool stuff
```
Then:
`yq r --unwrapScalar=false data.yml a`
Will yield:
```yaml
"Things" # cool stuff
```
where as without setting the flag to false you would get:
```yaml
Things
```
## Strip comments
Use the `--stripComments` flag to print out the yaml file without any of the original comments.
Given data.yml of:
```yaml
a:
b: # there is where the good stuff is
c: hi
```
Then
```yaml
yq r data.yml a --stripComments
```
Will yield:
```yaml
b:
c: hi
```

251
usage/path-expressions.md Normal file
View File

@@ -0,0 +1,251 @@
---
description: Path expressions are used to deeply navigate and match particular yaml nodes.
---
# Path Expressions
_As a general rule, you should wrap paths in quotes to prevent your CLI from processing `*`, `[]` and other special characters._
## Simple expressions
### Maps
`'a.b.c'`
```yaml
a:
b:
c: thing # MATCHES
```
### Arrays
`'a.b[1].c'`
```yaml
a:
b:
- c: thing0
- c: thing1 # MATCHES
- c: thing2
```
#### Appending to arrays
\(e.g. when using the write command\)
`'a.b[+].c'`
```yaml
a:
b:
- c: thing0
```
Will add a new entry:
```yaml
a:
b:
- c: thing0
- c: thing1 # NEW entry from [+] on B array.
```
#### Negative Array indexes
Negative array indexes can be used to traverse the array in reverse
`'a.b[-1].c'`
Will access the last element in the `b` array and yield:
```yaml
thing2
```
## Splat
### Maps
`'a.*.c'`
```yaml
a:
b1:
c: thing # MATCHES
d: whatever
b2:
c: thing # MATCHES
f: something irrelevant
```
#### Prefix splat
`'bob.item*.cats'`
```yaml
bob:
item:
cats: bananas # MATCHES
something:
cats: lemons
itemThing:
cats: more bananas # MATCHES
item2:
cats: apples # MATCHES
thing:
cats: oranges
```
### Arrays
`'a.b[*].c'`
```yaml
a:
b:
- c: thing0 # MATCHES
d: what..ever
- c: thing1 # MATCHES
d: blarh
- c: thing2 # MATCHES
f: thingamabob
```
## Deep Splat
`**` will match arbitrary nodes for both maps and arrays:
`'a.**.c'`
```yaml
a:
b1:
c: thing1 # MATCHES
d: cat cat
b2:
c: thing2 # MATCHES
d: dog dog
b3:
d:
- f:
c: thing3 # MATCHES
d: beep
- f:
g:
c: thing4 # MATCHES
d: boop
- d: mooo
```
## Search by children nodes
You can search children by nodes - note that this will return the _parent_ of the matching expression, in the example below the parent\(s\) will be the matching indices of the 'a' array. We can then navigate down to get 'b.c' of each matching indice.
`'a.(b.d==cat).b.c'`
```yaml
a:
- b:
c: thing0
d: leopard
ba: fast
- b:
c: thing1 # MATCHES
d: cat
ba: meowy
- b:
c: thing2
d: caterpillar
ba: icky
- b:
c: thing3 # MATCHES
d: cat
ba: also meowy
```
### With prefixes
`'a.(b.d==cat*).c'`
```yaml
a:
- b:
c: thing0
d: leopard
ba: fast
- b:
c: thing1 # MATCHES
d: cat
ba: meowy
- b:
c: thing2 # MATCHES
d: caterpillar
ba: icky
- b:
c: thing3 # MATCHES
d: cat
ba: also meowy
```
### Matching children values
`'animals(.==cat)'`
```yaml
animals:
- dog
- cat # MATCHES
- rat
```
this also works in maps, and with prefixes
`'animals(.==c*)'`
```yaml
animals:
friendliest: cow # MATCHES
favourite: cat # MATCHES
smallest: rat
```
## Special Characters
When your yaml field has special characters that overlap with `yq` path expression characters, you will need to escape them in order for the command to work.
### Keys with dots
When specifying a key that has a dot use key lookup indicator.
```yaml
b:
foo.bar: 7
```
```bash
yaml r sample.yaml 'b."foo.bar"'
```
```bash
yaml w sample.yaml 'b."foo.bar"' 9
```
Any valid yaml key can be specified as part of a key lookup.
Note that the path is in single quotes to avoid the double quotes being interpreted by your shell.
### Keys \(and values\) with leading dashes
The flag terminator needs to be used to stop the app from attempting to parse the subsequent arguments as flags, if they start if a dash.
```bash
yq n -j -- --key --value
```
Will result in
```text
--key: --value
```

288
usage/value-parsing.md Normal file
View File

@@ -0,0 +1,288 @@
---
description: >-
How values are parsed from the CLI to commands that create/update yaml (e.g.
new/write).
---
# Value Parsing
`yq` attempts to parse values intelligently, e.g. when a number is passed it - it will assume it's a number as opposed to a string. `yq` will not alter the representation of what you give. So if you pass '03.0' in, it will assume it's a number and keep the value formatted as it was passed in, that is '03.0'.
The `--tag` flag can be used to override the tag type to force particular tags.
## Default behavior
### Integers
_Given_
```bash
yq new key 3
```
results in
```yaml
key: 3
```
_Given a formatted number_
```bash
yq new key 03
```
results in
```yaml
key: 03
```
`yq` keeps the number formatted as it was passed in.
### Float
_Given_
```bash
yq new key "3.1"
```
results in
```yaml
key: 3.1
```
Note that quoting the number does not make a difference.
_Given a formatted decimal number_
```bash
yq new key 03.0
```
results in
```yaml
key: 03.0
```
`yq` keeps the number formatted as it was passed in
### Booleans
```bash
yq new key true
```
results in
```yaml
key: true
```
### Nulls
```bash
yq new key null
```
results in
```yaml
key: null
```
```bash
yq new key '~'
```
results in
```yaml
key: ~
```
```bash
yq new key ''
```
results in
```yaml
key:
```
### Strings
```bash
yq new key whatever
```
results in
```yaml
key: whatever
```
```bash
yq new key ' whatever '
```
results in
```yaml
key: ' whatever '
```
## Using the tag flag to cast
Previous versions of yq required double quoting to force values to be strings, this no longer works - instead use the --tag flag.
### Casting booleans
```bash
yq new --tag '!!str' key true
```
results in
```yaml
key: "true"
```
### Casting nulls
```bash
yq new --tag '!!str' key null
```
results in
```yaml
key: "null"
```
### Custom types
```bash
yq new --tag '!!farah' key gold
```
results in
```yaml
key: !!farah gold
```
## The style flag
The `--style` flag can be used to specify the quote or block style of the node value. Valid values are
* single
* double
* folded
* flow
* literal
* tagged
For example, given:
```bash
MULTILINE=$(cat <<END
This is line one.
This is line two.
END
)
SINGLE="only one line"
```
### Single
```yaml
yq n --style single things "$MULTILINE"
```
```yaml
things: 'This is line one.
This is line two.'
```
### Double
```yaml
things: "This is line one.\nThis is line two."
```
### Folded:
```yaml
things: >-
This is line one.
This is line two.
```
#### Folded single line:
```yaml
things: >-
only one line
```
### Flow:
```yaml
things: |-
This is line one.
This is line two.
```
#### Flow single line:
```yaml
things: only one line
```
### Literal
```yaml
things: |-
This is line one.
This is line two.
```
#### Literal single line
```yaml
things: |-
only one line
```
### Tagged
Always show the tag, note - you must also pass in `--tag='!!str'`
```yaml
things: !!str |-
This is line one.
This is line two.
```
#### Tagged single line
```yaml
things: !!str only one line
```