Description

I'm frequently passed long shell one-liners that require some visual inspection before running. These days, there's about as much jq in that one-liner as there is bash. I wrote jqfmt to help add line breaks in sensible locations while reading (or writing!) jq.

At time of initial development, I naturally turned to https://github.com/itchyny/gojq expecting to be able to generate and walk a syntax tree—but gojq didn't seem to provide an AST that could be "walked," and it doesn't export its parsing logic to be used in library form. So, I yanked the relevant code out of https://github.com/itchyny/gojq/blob/main/query.go and started from there.

Side note: Ever tried Googling for "jq formatter"? Reading search results is a nightmare since jq itself is, among other things, a formatter.

Getting started

Install

With Homebrew via the jqfmt package:

brew install jqfmt

With Go:

go install -v github.com/noperator/jqfmt/cmd/jqfmt@latest

Usage

𝄢 jqfmt -h
Usage of jqfmt:
  -ar
    	break array literals, one element per line
  -f string
    	read jq from this file instead of stdin
  -fn string
    	comma-separated function names to break the line before
  -if
    	break if/elif/else/end onto their own lines
  -o	collapse to a single canonical line
  -ob
    	break object literals, one key per line
  -op string
    	comma-separated operators to break on (pipe,comma,add,...)

Let's take this line of jq…

𝄢 echo '{one: .two, three: [.four, .five, [.fivetwo, .fivethree]], six: map(select((.seven | .eight | .nine)))}' |
    jqfmt
{ one: .two, three: [.four, .five, [.fivetwo, .fivethree]], six: map(select((.seven | .eight | .nine))) }

…and format objects.

𝄢 echo '{one: .two, three: [.four, .five, [.fivetwo, .fivethree]], six: map(select((.seven | .eight | .nine)))}' |
    jqfmt -ob
{
    one: .two,
    three: [.four, .five, [.fivetwo, .fivethree]],
    six: map(select((.seven | .eight | .nine)))
}

Nice! Let's also do arrays.

𝄢 echo '{one: .two, three: [.four, .five, [.fivetwo, .fivethree]], six: map(select((.seven | .eight | .nine)))}' |
    jqfmt -ob -ar
{
    one: .two,
    three: [
        .four,
        .five,
        [
            .fivetwo,
            .fivethree
        ]
    ],
    six: map(select((.seven | .eight | .nine)))
}

It'll read easier if we also break on pipes.

𝄢 echo '{one: .two, three: [.four, .five, [.fivetwo, .fivethree]], six: map(select((.seven | .eight | .nine)))}' |
    jqfmt -ob -ar -op pipe
{
    one: .two,
    three: [
        .four,
        .five,
        [
            .fivetwo,
            .fivethree
        ]
    ],
    six: map(select((.seven |
        .eight |
        .nine)))
}

Word operators (and/or) break before the operator, the way you'd write a boolean chain by hand — while pipes and commas still trail.

𝄢 echo '{name: .n, ok: select(.active and .verified and .paid)}' |
    jqfmt -ob -op pipe,and
{
    name: .n,
    ok: select(.active
        and .verified
        and .paid)
}

Full list of valid operators

pipe
comma
add
sub
mul
div
mod
eq
ne
gt
lt
ge
le
and
or
alt
assign
modify
updateAdd
updateSub
updateMul
updateDiv
updateMod
updateAlt

Back matter

Acknowledgements

• @zjzeit for helping me believe that formatting jq is a reasonable thing to do.
• @colindean for helping me believe that jqfmt was a reasonable thing to build.
• @tracertea for writing jq lines long enough to warrant a formatter.
• @addyosmani for "First do it, then do it right, then do it better." I wrote this on a plane (as the best tools are) over a year ago, but always had more features I wanted to add before releasing it. Doing it "right" might mean a refactor or clean-up; "better" would probably mean incorporating an AST.

See also

• https://news.ycombinator.com/item?id=9448128
• jqlang/jq#2366 (comment)
• itchyny/gojq#62
• wader/jqjq#8

To-do

• handle func definitions
• quickly format jq by appending fmt to jq on the CLI

License

This project is licensed under the MIT License.