jq as a template engine

jq is one of those softwares that i normally dont use, but im glad its there when i need it. Thats the reason why i can never remember its syntax. This post is that, a kind of cheatsheet or reference to myself for the tasks that i normally use it for.

Extract a single property

If i want to extract a single property, in this case name, i only need to select it.

curl "https://jsonplaceholder.typicode.com/users/1" | jq '.name'

The . filter is the identity. Whether its the toplevel object, or an item of an iterator. Usually used to access the current item.

Filtering data

I can also “pipe” some property to a function or filter. For example to convert to uppercase

curl "https://jsonplaceholder.typicode.com/users/1" | jq '.name | ascii_upcase'

It could also be used to create new json objects

curl "https://jsonplaceholder.typicode.com/users/1" | jq '. | {name:.name, id:.id}'

Iterating data

If i want to apply a filter to every object in an array, i could use the .property[] iterator.

curl "https://jsonplaceholder.typicode.com/users" | jq '.[] | .username'

If i only need one property of the array, i could use a more compact syntax

curl "https://jsonplaceholder.typicode.com/users" | jq '.[].username'

If i want to collect everything in an array, i need to wrap all in []

curl "https://jsonplaceholder.typicode.com/users" | jq '[.[] | .username]'

String interpolation

If i need to interpolate some value to its string value, i could use the following syntaxis. \(.foo)

curl "https://jsonplaceholder.typicode.com/users" | jq '.[] | "\(.username) its called \(.name)"'

Its important to wrap the string in quotes ("). This is one of the main things i always forget

As a template example

With this, i could run the following command to get a list of users

curl "https://jsonplaceholder.typicode.com/users" | jq -r '.[] | "<li class=\"list-item\">\(.username) its called \(.name)</li>"'

What the -r flag does is output the content as a raw string, instead of trying to parse everything as a json value

edit 2023/12/31: Reading Scraping Goodreads i found out about jqterm: jq as a service