Overview

In the last

episode we looked at how JSON data is structured and saw how

jq could be used to format and print this type of data.

In this episode we'll visit a few of the options to the

jq command and then start on the filters written in the

jq language.

Options used by jq

In general the jq command is invoked thus:

jq [options...] filter [files...]

It can be given data in files or sent to it via the STDIN (standard

in) channel. We saw data being sent this way in the last episode, having

been downloaded by curl.

There are many options to the command, and these are listed in the

manual page and in the online manual. We will

look at a few of them here:

--help or -h

Output the jq help and exit with zero.

-f filename or

--from-file filename

Read filter from the file rather than from a command line, like awk´s

-f option. You can also use ´#´ to make comments in the file.

--compact-output or -c

By default, jq pretty-prints JSON output. Using this

option will result in more compact output by instead putting each JSON

object on a single line.

--color-output or -C and

--monochrome-output or -M

By default, jq outputs colored JSON if writing to a

terminal. You can force it to produce color even if writing to a pipe or

a file using -C, and disable color with

-M.

--tab

Use a tab for each indentation level instead of two spaces.

--indent n

Use the given number of spaces (no more than 7) for indentation.

Notes

The -C option is useful when printing output to the

less command with the colours that jq normally

generates. Use this:

jq -C '.' file.json | less -R

The -R option to less allows colour escape sequences to

pass through.

Do not do what I did recently. Accidentally leaving the

-C option on the command caused formatted.json

to contain all the escape codes used to colour the output:

$ jq -C '.' file.json > formatted.json

This is why jq normally only generates coloured output

when writing to the terminal.

Filters in jq

As we saw in the last episode JSON can contain arrays and objects.

Arrays are enclosed in square brackets and their elements can be any of

the data types we saw last time. So, arrays of arrays, arrays of

objects, and arrays of both of these are all possible.

Objects contain collections of keyed items where the keys are strings

of various types and the values they are associated with can be any of

the data types.

JSON Examples

Simple arrays:

[1,2,3]

[1,2,3,[4,5,6]]

["Hacker","Public","Radio"]

["Sunday","Monday","Tuesday","Wednesday","Thursday","Friday","Saturday"]

Simple object:

{ "name": "Hacker Public Radio", "type": "podcast"}

This more complex object was generated by the Random User Generator

API.