Writing jq With Less Stress

Wait… What?!

Yes, I know: a clickbait title. Even so, I aim to present an opinionated guide for getting started writing code in jq that goes beyond the manual with suggestions about how to write jq code that costs less to understand, to change, and therefore causes you less stress.

The Plan

I intend this guide to help you to progress from writing simple jq code to having a system for where to put code. Don’t worry: you don’t need to put everything in the right place from the first moment---on the contrary, this guide focuses on how to let code flow to ever-more-helpful parts of your project. Start simple, then let complications force themselves into existence. I’ve chosen these refactoring moves to help you decide what to do when the layout of your jq code starts to feel vaguely annoying.

These are the steps I tend to follow:

1. Write jq expressions directly on the command line.
2. Move expressions into functions.
3. Move functions into library files.
4. Split library files into modules… and don’t forget to make the load path explicit!
5. Move modules into their own projects.

You might recognize these steps as “just how to organize source code”. Yes, perhaps this all seems like “common sense”, but I’ve noticed something particular about how programmers behave, including me:

Danger

If we don’t understand our options, we tend to do nothing, even when we know that things will gradually crumble around us.

This guide aims to show you your options, so that you choose to do something, rather than let your code congeal into a Big Ball of Mud.

I propose we start very simply: merely writing expressions directly on the command line. And if you’re new to jq, then you’ll probably want to do this, anyway.

Note

This guide will not provide a thorough introduction to jq, but instead only introduce you to enough to get started. If you want to write something in jq and you don’t know how, then refer to the manual.