yq
v4.x
v4.x
  • yq
  • How It Works
  • Recipes
  • Upgrading from V3
  • Commands
    • Evaluate
    • Evaluate All
    • Shell Completion
  • Operators
    • Add
    • Alternative (Default value)
    • Anchor and Alias Operators
    • Array to Map
    • Assign (Update)
    • Boolean Operators
    • Collect into Array
    • Column
    • Comment Operators
    • Compare Operators
    • Contains
    • Create, Collect into Object
    • Date Time
    • Delete
    • Divide
    • Document Index
    • Encode / Decode
    • Entries
    • Env Variable Operators
    • Equals
    • Eval
    • File Operators
    • Filter Operator
    • Flatten
    • Group By
    • Has
    • Keys
    • Kind
    • Length
    • Line
    • Load
    • Min
    • Map
    • Max
    • Modulo
    • Multiply (Merge)
    • Omit
    • Parent
    • Path
    • Pick
    • Pipe
    • Pivot
    • Recursive Descent (Glob)
    • Reduce
    • Reverse
    • Select
    • Shuffle
    • Slice Array
    • Sort
    • Sort Keys
    • Split into Documents
    • String Operators
    • Style
    • Subtract
    • Tag
    • To Number
    • Traverse (Read)
    • Union
    • Unique
    • Variable Operators
    • With
  • Usage
    • Output format
    • Working with CSV, TSV
    • Working with JSON
    • Working with Properties
    • Working with XML
    • Working with LUA
    • Working with TOML
    • Working with Shell Output
    • Front Matter
    • Split into multiple files
    • GitHub Action
    • Tips, Tricks, Troubleshooting
  • Github Page
Powered by GitBook
On this page
  • Encode value as json string
  • Encode value as json string, on one line
  • Encode value as json string, on one line shorthand
  • Decode a json encoded string
  • Encode value as props string
  • Decode props encoded string
  • Decode csv encoded string
  • Decode tsv encoded string
  • Encode value as yaml string
  • Encode value as yaml string, with custom indentation
  • Decode a yaml encoded string
  • Update a multiline encoded yaml string
  • Update a single line encoded yaml string
  • Encode array of scalars as csv string
  • Encode array of arrays as csv string
  • Encode array of arrays as tsv string
  • Encode value as xml string
  • Encode value as xml string on a single line
  • Encode value as xml string with custom indentation
  • Decode a xml encoded string
  • Encode a string to base64
  • Encode a yaml document to base64
  • Encode a string to uri
  • Decode a URI to a string
  • Encode a string to sh
  • Decode a base64 encoded string
  • Decode a base64 encoded yaml document

Was this helpful?

  1. Operators

Encode / Decode

PreviousDocument IndexNextEntries

Last updated 2 years ago

Was this helpful?

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 for accepted formats.

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

Base64 assumes encoding. Encoding and decoding both assume that the content is a utf-8 string and not binary content.

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 arrays 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
documentation
rfc4648