yq/operators/encode-decode.md

Encoder / Decoder

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.

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 embedded yaml/json/props in them.

Format	Decode (from string)	Encode (to string)
Yaml	from_yaml/@yamld	to_yaml(i)/@yaml
JSON	from_json/@jsond	to_json(i)/@json
Properties	from_props/@propsd	to_props/@props
CSV	from_csv/@csvd	to_csv/@csv
TSV	from_tsv/@tsvd	to_tsv/@tsv
XML	from_xml/@xmld	to_xml(i)/@xml
Base64	@base64d	@base64
URI	@urid	@uri
Shell		@sh

See CSV and TSV documentation for accepted formats.

XML uses the --xml-attribute-prefix and xml-content-name flags to identify attributes and content fields.

Base64 assumes rfc4648 encoding. Encoding and decoding both assume that the content is a string.

Encode value as json string

Given a sample.yml file of:

a:
  cool: thing

then

yq '.b = (.a | to_json)' sample.yml

will output

a:
  cool: thing
b: |
  {
    "cool": "thing"
  }  

Encode value as json string, on one line

Pass in a 0 indent to print json on a single line.

Given a sample.yml file of:

a:
  cool: thing

then

yq '.b = (.a | to_json(0))' sample.yml

will output

a:
  cool: thing
b: '{"cool":"thing"}'

Encode value as json string, on one line shorthand

Pass in a 0 indent to print json on a single line.

Given a sample.yml file of:

a:
  cool: thing

then

yq '.b = (.a | @json)' sample.yml

will output

a:
  cool: thing
b: '{"cool":"thing"}'

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:

a: '{"cool":"thing"}'

then

yq '.a | from_json | ... style=""' sample.yml

will output

cool: thing

Encode value as props string

Given a sample.yml file of:

a:
  cool: thing

then

yq '.b = (.a | @props)' sample.yml

will output

a:
  cool: thing
b: |
  cool = thing  

Decode props encoded string

Given a sample.yml file of:

a: |-
  cats=great
  dogs=cool as well  

then

yq '.a |= @propsd' sample.yml

will output

a:
  cats: great
  dogs: cool as well

Decode csv encoded string

Given a sample.yml file of:

a: |-
  cats,dogs
  great,cool as well  

then

yq '.a |= @csvd' sample.yml

will output

a:
  - cats: great
    dogs: cool as well

Decode tsv encoded string

Given a sample.yml file of:

a: |-
  cats	dogs
  great	cool as well  

then

yq '.a |= @tsvd' sample.yml

will output

a:
  - cats: great
    dogs: cool as well

Encode value as yaml string

Indent defaults to 2

Given a sample.yml file of:

a:
  cool:
    bob: dylan

then

yq '.b = (.a | to_yaml)' sample.yml

will output

a:
  cool:
    bob: dylan
b: |
  cool:
    bob: dylan  

Encode value as yaml string, with custom indentation

You can specify the indentation level as the first parameter.

Given a sample.yml file of:

a:
  cool:
    bob: dylan

then

yq '.b = (.a | to_yaml(8))' sample.yml

will output

a:
  cool:
    bob: dylan
b: |
  cool:
          bob: dylan  

Decode a yaml encoded string

Given a sample.yml file of:

a: 'foo: bar'

then

yq '.b = (.a | from_yaml)' sample.yml

will output

a: 'foo: bar'
b:
  foo: bar

Update a multiline encoded yaml string

Given a sample.yml file of:

a: |
  foo: bar
  baz: dog  

then

yq '.a |= (from_yaml | .foo = "cat" | to_yaml)' sample.yml

will output

a: |
  foo: cat
  baz: dog  

Update a single line encoded yaml string

Given a sample.yml file of:

a: 'foo: bar'

then

yq '.a |= (from_yaml | .foo = "cat" | to_yaml)' sample.yml

will output

a: 'foo: cat'

Encode array of scalars as csv string

Scalars are strings, numbers and booleans.

Given a sample.yml file of:

- cat
- thing1,thing2
- true
- 3.40

then

yq '@csv' sample.yml

will output

cat,"thing1,thing2",true,3.40

Encode array of arrays as csv string

Given a sample.yml file of:

- - cat
  - thing1,thing2
  - true
  - 3.40
- - dog
  - thing3
  - false
  - 12

then

yq '@csv' sample.yml

will output

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:

- - cat
  - thing1,thing2
  - true
  - 3.40
- - dog
  - thing3
  - false
  - 12

then

yq '@tsv' sample.yml

will output

cat	thing1,thing2	true	3.40
dog	thing3	false	12

Encode value as xml string

Given a sample.yml file of:

a:
  cool:
    foo: bar
    +@id: hi

then

yq '.a | to_xml' sample.yml

will output

<cool id="hi">
  <foo>bar</foo>
</cool>

Encode value as xml string on a single line

Given a sample.yml file of:

a:
  cool:
    foo: bar
    +@id: hi

then

yq '.a | @xml' sample.yml

will output

<cool id="hi"><foo>bar</foo></cool>

Encode value as xml string with custom indentation

Given a sample.yml file of:

a:
  cool:
    foo: bar
    +@id: hi

then

yq '{"cat": .a | to_xml(1)}' sample.yml

will output

cat: |
  <cool id="hi">
   <foo>bar</foo>
  </cool>  

Decode a xml encoded string

Given a sample.yml file of:

a: <foo>bar</foo>

then

yq '.b = (.a | from_xml)' sample.yml

will output

a: <foo>bar</foo>
b:
  foo: bar

Encode a string to base64

Given a sample.yml file of:

coolData: a special string

then

yq '.coolData | @base64' sample.yml

will output

YSBzcGVjaWFsIHN0cmluZw==

Encode a yaml document to base64

Pipe through @yaml first to convert to a string, then use @base64 to encode it.

Given a sample.yml file of:

a: apple

then

yq '@yaml | @base64' sample.yml

will output

YTogYXBwbGUK

Encode a string to uri

Given a sample.yml file of:

coolData: this has & special () characters *

then

yq '.coolData | @uri' sample.yml

will output

this+has+%26+special+%28%29+characters+%2A

Decode a URI to a string

Given a sample.yml file of:

this+has+%26+special+%28%29+characters+%2A

then

yq '@urid' sample.yml

will output

this has & special () characters *

Encode a string to sh

Sh/Bash friendly string

Given a sample.yml file of:

coolData: strings with spaces and a 'quote'

then

yq '.coolData | @sh' sample.yml

will output

strings' with spaces and a '\'quote\'

Decode a base64 encoded string

Decoded data is assumed to be a string.

Given a sample.yml file of:

coolData: V29ya3Mgd2l0aCBVVEYtMTYg8J+Yig==

then

yq '.coolData | @base64d' sample.yml

will output

Works with UTF-16 😊

Decode a base64 encoded yaml document

Pipe through from_yaml to parse the decoded base64 string as a yaml document.

Given a sample.yml file of:

coolData: YTogYXBwbGUK

then

yq '.coolData |= (@base64d | from_yaml)' sample.yml

will output

coolData:
  a: apple