Today I read through the jq manual cover-to-cover. For those unaware, jq is a popular CLI tool to query and manipulate JSON. It’s also a Turing-complete mini-language with nice functional semantics that fits well into the ethos of composable CLI tools.

It was an exemplar of well-written technical documentation. Concise, well-written, littered with examples, and linking to an interactive playground to test-and-learn.

Some learnings:

1. It’s surprisingly functional! You can implement recursive functions and use higher-order functions! For example, here’s factorial in jq:

$ jq '[.,1]|until(.[0] < 1; [.[0] - 1, .[1] * .[0]])|.[1]'

2. It supports string interpolation - this is really nice if you’re piping stuff from JSON into a string. Coupled with format strings this becomes frictionless:

$ echo '{"search":"hello; world"}' | jq -r '@uri "https://www.google.com/search?q=\(.search)"'
# https://www.google.com/search?q=hello%3B%20world

3. You can define functions that accept functions¹, and control structures that allow labelling.

$ echo '[[1,2],[10,20]]' | jq -r 'def addvalue(f): . + [f]; map(addvalue(.[0]))'
#[[1,2,1], [10,20,10]]

4. You can traverse complex data structures with first-class pathing support. And you can easily modify nested structures to extend objects.
5. For the category theorists/polyglots, there’s a denotational semantics paper written about jq.
6. Bonus: You can build a Brainfuck interpreter in jq; and you can build a jq interpreter in jq - how’s that for bootstrapping!

Side note: This is one of my goals for 2025 - read through documentation end-to-end to develop mastery over tools. I’m trying to prioritise selectively depth over breadth.