yq/pkg/yqlib/doc/operators/encode-decode.md

351 lines
5.2 KiB
Markdown
Raw Normal View History

2021-11-03 02:54:09 +00:00
# Encoder / Decoder
2021-10-22 01:37:47 +00:00
Encode operators will take the piped in object structure and encode it as a string in the desired format. The decode operators do the opposite, they take a formatted string and decode it into the relevant object structure.
2021-10-26 04:07:50 +00:00
Note that you can optionally pass an indent value to the encode functions (see below).
These operators are useful to process yaml documents that have stringified embeded yaml/json/props in them.
2021-11-03 02:54:09 +00:00
2021-10-24 00:35:40 +00:00
2021-12-02 01:11:15 +00:00
| Format | Decode (from string) | Encode (to string) |
| --- | -- | --|
| Yaml | from_yaml | to_yaml(i)/@yaml |
| JSON | from_json | to_json(i)/@json |
| Properties | | to_props/@props |
| CSV | | to_csv/@csv |
| TSV | | to_tsv/@tsv |
2021-12-21 05:52:54 +00:00
| XML | from_xml | to_xml(i)/@xml |
2021-12-02 01:11:15 +00:00
CSV and TSV format both accept either a single array or scalars (representing a single row), or an array of array of scalars (representing multiple rows).
2021-12-21 05:52:54 +00:00
XML uses the `--xml-attribute-prefix` and `xml-content-name` flags to identify attributes and content fields.
2021-12-02 01:11:15 +00:00
## Encode value as json string
2021-10-22 01:37:47 +00:00
Given a sample.yml file of:
```yaml
a:
2021-12-02 01:11:15 +00:00
cool: thing
2021-10-22 01:37:47 +00:00
```
then
```bash
2021-12-02 01:11:15 +00:00
yq eval '.b = (.a | to_json)' sample.yml
2021-10-22 01:37:47 +00:00
```
will output
```yaml
a:
2021-12-02 01:11:15 +00:00
cool: thing
2021-10-22 01:37:47 +00:00
b: |
2021-12-02 01:11:15 +00:00
{
"cool": "thing"
}
2021-10-24 00:35:40 +00:00
```
2021-12-02 01:11:15 +00:00
## Encode value as json string, on one line
Pass in a 0 indent to print json on a single line.
2021-10-24 00:35:40 +00:00
Given a sample.yml file of:
```yaml
a:
2021-12-02 01:11:15 +00:00
cool: thing
2021-10-24 00:35:40 +00:00
```
then
```bash
2021-12-02 01:11:15 +00:00
yq eval '.b = (.a | to_json(0))' sample.yml
2021-10-24 00:35:40 +00:00
```
will output
```yaml
a:
2021-12-02 01:11:15 +00:00
cool: thing
b: '{"cool":"thing"}'
2021-10-22 01:37:47 +00:00
```
2021-12-02 01:11:15 +00:00
## Encode value as json string, on one line shorthand
Pass in a 0 indent to print json on a single line.
2021-10-22 01:37:47 +00:00
Given a sample.yml file of:
```yaml
a:
cool: thing
```
then
```bash
2021-12-02 01:11:15 +00:00
yq eval '.b = (.a | @json)' sample.yml
2021-10-22 01:37:47 +00:00
```
will output
```yaml
a:
cool: thing
2021-12-02 01:11:15 +00:00
b: '{"cool":"thing"}'
2021-10-22 01:37:47 +00:00
```
2021-12-02 01:11:15 +00:00
## Decode a json encoded string
Keep in mind JSON is a subset of YAML. If you want idiomatic yaml, pipe through the style operator to clear out the JSON styling.
Given a sample.yml file of:
```yaml
a: '{"cool":"thing"}'
```
then
```bash
yq eval '.a | from_json | ... style=""' sample.yml
```
will output
```yaml
cool: thing
```
## Encode value as props string
2021-10-22 01:37:47 +00:00
Given a sample.yml file of:
```yaml
a:
cool: thing
```
then
```bash
2021-12-02 01:11:15 +00:00
yq eval '.b = (.a | @props)' sample.yml
2021-10-22 01:37:47 +00:00
```
will output
```yaml
a:
cool: thing
b: |
2021-12-02 01:11:15 +00:00
cool = thing
2021-10-22 01:37:47 +00:00
```
2021-12-02 01:11:15 +00:00
## Encode value as yaml string
Indent defaults to 2
2021-10-24 00:35:40 +00:00
Given a sample.yml file of:
```yaml
a:
2021-12-02 01:11:15 +00:00
cool:
bob: dylan
2021-10-24 00:35:40 +00:00
```
then
```bash
2021-12-02 01:11:15 +00:00
yq eval '.b = (.a | to_yaml)' sample.yml
2021-10-24 00:35:40 +00:00
```
will output
```yaml
a:
2021-12-02 01:11:15 +00:00
cool:
bob: dylan
b: |
cool:
bob: dylan
2021-10-24 00:35:40 +00:00
```
2021-12-02 01:11:15 +00:00
## Encode value as yaml string, with custom indentation
You can specify the indentation level as the first parameter.
Given a sample.yml file of:
```yaml
a:
cool:
bob: dylan
```
then
```bash
yq eval '.b = (.a | to_yaml(8))' sample.yml
```
will output
```yaml
a:
cool:
bob: dylan
b: |
cool:
bob: dylan
```
2021-10-22 01:37:47 +00:00
## Decode a yaml encoded string
Given a sample.yml file of:
```yaml
a: 'foo: bar'
```
then
```bash
yq eval '.b = (.a | from_yaml)' sample.yml
```
will output
```yaml
a: 'foo: bar'
b:
foo: bar
```
## Update a multiline encoded yaml string
2021-10-22 01:37:47 +00:00
Given a sample.yml file of:
```yaml
a: |
foo: bar
baz: dog
2021-10-22 01:37:47 +00:00
```
then
```bash
yq eval '.a |= (from_yaml | .foo = "cat" | to_yaml)' sample.yml
```
will output
```yaml
a: |
foo: cat
baz: dog
```
## Update a single line encoded yaml string
Given a sample.yml file of:
```yaml
a: 'foo: bar'
```
then
```bash
yq eval '.a |= (from_yaml | .foo = "cat" | to_yaml)' sample.yml
```
will output
```yaml
a: 'foo: cat'
2021-10-22 01:37:47 +00:00
```
2021-12-02 01:11:15 +00:00
## Encode array of scalars as csv string
Scalars are strings, numbers and booleans.
Given a sample.yml file of:
```yaml
- cat
- thing1,thing2
- true
- 3.40
```
then
```bash
yq eval '@csv' sample.yml
```
will output
```yaml
cat,"thing1,thing2",true,3.40
```
## Encode array of arrays as csv string
Given a sample.yml file of:
```yaml
- - cat
- thing1,thing2
- true
- 3.40
- - dog
- thing3
- false
- 12
```
then
```bash
yq eval '@csv' sample.yml
```
will output
```yaml
cat,"thing1,thing2",true,3.40
dog,thing3,false,12
```
## Encode array of array scalars as tsv string
Scalars are strings, numbers and booleans.
Given a sample.yml file of:
```yaml
- - cat
- thing1,thing2
- true
- 3.40
- - dog
- thing3
- false
- 12
```
then
```bash
yq eval '@tsv' sample.yml
```
will output
```yaml
cat thing1,thing2 true 3.40
dog thing3 false 12
```
2021-12-21 05:52:54 +00:00
## Encode value as xml string
Given a sample.yml file of:
```yaml
a:
cool:
foo: bar
+id: hi
```
then
```bash
yq eval '.a | to_xml' sample.yml
```
will output
```yaml
<cool id="hi">
<foo>bar</foo>
</cool>
2021-12-21 05:59:09 +00:00
2021-12-21 05:52:54 +00:00
```
## Encode value as xml string on a single line
Given a sample.yml file of:
```yaml
a:
cool:
foo: bar
+id: hi
```
then
```bash
yq eval '.a | @xml' sample.yml
```
will output
```yaml
<cool id="hi"><foo>bar</foo></cool>
2021-12-21 05:59:09 +00:00
2021-12-21 05:52:54 +00:00
```
## Encode value as xml string with custom indentation
Given a sample.yml file of:
```yaml
a:
cool:
foo: bar
+id: hi
```
then
```bash
2021-12-21 05:59:09 +00:00
yq eval '{"cat": .a | to_xml(1)}' sample.yml
2021-12-21 05:52:54 +00:00
```
will output
```yaml
2021-12-21 05:59:09 +00:00
cat: |
<cool id="hi">
<foo>bar</foo>
</cool>
2021-12-21 05:52:54 +00:00
```
2021-12-21 04:02:07 +00:00
## Decode a xml encoded string
Given a sample.yml file of:
```yaml
a: <foo>bar</foo>
```
then
```bash
yq eval '.b = (.a | from_xml)' sample.yml
```
will output
```yaml
a: <foo>bar</foo>
b:
foo: bar
```