Difference between revisions of "Yq"

From NovaOrdis Knowledge Base
Jump to: navigation, search
(Operations)
(Write/Update a YAML Document)
(6 intermediate revisions by the same user not shown)
Line 37: Line 37:
 
=Operations=
 
=Operations=
 
==Read==
 
==Read==
 +
{{External|https://mikefarah.github.io/yq/read/}}
 +
 +
yq r <''file.yaml''> <''path''>
 +
cat <''file.yaml''> | yq r - <''path''>
 +
 +
If the path does not exist - either the final element, or intermediary elements - , yq returns literally "null", but the return code is 0.
 +
 +
If the path exists, but the content is empty, yq returns "null".
 +
 +
===Checking yq-validity===
 +
 +
An empty file or a file that only contains commands is invalid for for yq. This can be checked as follows:
 +
 +
  if ! yq r file.yaml 1>/dev/null 2>/dev/null; then
 +
    echo "file.yaml invalid"
 +
  fi
 +
 +
==Create a New YAML Document==
 +
{{External|https://mikefarah.github.io/yq/create/}}
 +
 +
yq n <path> <value>
 +
 +
The content is sent to stdout.
 +
 +
Example:
 +
 +
yq n test.color blue > test.yaml
 +
 +
Result:
 +
<syntaxhighlight lang='yaml'>
 +
test:
 +
  color: blue
 +
</syntaxhighlight>
 +
 +
==Write/Update a YAML Document==
 +
{{External|https://mikefarah.github.io/yq/write/}}
 +
 +
The command takes the file specified as a base and writes/updates the specified paths. It then sends the entire resulted YAML file at stdout.
 +
 +
If the base is empty, or only contains comments, yq w fails with:
 +
Error: asked to process document index 0 but there are only 0 document(s)
 +
"yq-validity" can be checked with [[#Checking_yq-validity|yq r]] command.
 +
 +
Starting from test.yaml:
 +
<syntaxhighlight lang='yaml'>
 +
item:
 +
  color: blue
 +
</syntaxhighlight>
 +
 +
yq w test.yaml item.color red
 +
 +
produces:
 +
<syntaxhighlight lang='yaml'>
 +
item:
 +
  color: red
 +
</syntaxhighlight>
 +
 +
The command can add a new path, creating all required path elements:
 +
 +
yq w test.yaml item.size large
 +
 +
produces:
 +
<syntaxhighlight lang='yaml'>
 +
item:
 +
  color: blue
 +
  size: large
 +
</syntaxhighlight>
 +
 +
The command may update the file '''in-place''' by specifying the "-i" option:
 +
 +
yq w -i test.yaml ...
 +
 +
'''write Idiosyncrasies''':
 +
* write strips off the comments from the base file

Revision as of 22:02, 15 January 2020

External

Internal

DEPLETE

YqTODELETE

Overview

yq is a lightweight and portable command-line YAML processor. It is written in Go and it consists in a single portable binary. It can be used to query a YAML file using a YAML path, to update a YAML file for a YAML path or using a script file, to create a YAML file or merge YAML files. The update operation creates any missing path elements. yq can also be used to convert YAML files to JSON and JSON files to YAML.

The default output is YAML, unless -j option is used.

Version

yq --version
yq version 2.4.1

Installation

Mac

brew install yq

Linux

yq_version=2.4.1
cd /tmp
wget https://github.com/mikefarah/yq/releases/download/${yq_version}/yq_linux_amd64
mv /tmp/yq_linux_amd64 yq /bin/yq
chmod a+x /bin/yq

Concepts

Command Line Options

-v

Provides additional details on parsing.

-j

Output formatted as JSON.

Operations

Read

https://mikefarah.github.io/yq/read/
yq r <file.yaml> <path>
cat <file.yaml> | yq r - <path>

If the path does not exist - either the final element, or intermediary elements - , yq returns literally "null", but the return code is 0.

If the path exists, but the content is empty, yq returns "null".

Checking yq-validity

An empty file or a file that only contains commands is invalid for for yq. This can be checked as follows:

 if ! yq r file.yaml 1>/dev/null 2>/dev/null; then
   echo "file.yaml invalid"
 fi

Create a New YAML Document

https://mikefarah.github.io/yq/create/
yq n <path> <value>

The content is sent to stdout.

Example:

yq n test.color blue > test.yaml

Result:

test:
  color: blue

Write/Update a YAML Document

https://mikefarah.github.io/yq/write/

The command takes the file specified as a base and writes/updates the specified paths. It then sends the entire resulted YAML file at stdout.

If the base is empty, or only contains comments, yq w fails with:

Error: asked to process document index 0 but there are only 0 document(s)

"yq-validity" can be checked with yq r command.

Starting from test.yaml:

item:
  color: blue
yq w test.yaml item.color red

produces:

item:
  color: red

The command can add a new path, creating all required path elements:

yq w test.yaml item.size large

produces:

item:
  color: blue
  size: large

The command may update the file in-place by specifying the "-i" option:

yq w -i test.yaml ...

write Idiosyncrasies:

  • write strips off the comments from the base file