noperator/jqfmt

like gofmt, but for jq

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

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

Usage

𝄢 jqfmt -h
Usage of jqfmt:
  -ar
    	arrays
  -f string
    	file
  -o	one line
  -ob
    	objects
  -op string
    	operators
  -v	verbose

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)))
}

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.

jqfmt's Issues

Not sure how to get this to work

I have a .jq file I'm trying to get this to work on, but struggling. It doesn't seem like it can read the contents of my file. I'm trying to cat the contents of a file into jqfmt and im just getting this error:

❯ cat artifact.jq | jqfmt
FATA[0000] could not format jq: could not read file: open /Users/myuser/.jq: no such file or directory

Any ideas? Is it possible to run it against a file and update the file?

Issue with jqfmt picking up jq

Hi, i noticed that when i installed jqfmt, it does not work with the example provided in the readme

echo '{one: .two, three: [.four, .five, [.fivetwo, .fivethree]], six: map(select((.seven | .eight | .nine)))}' |
    jqfmt
FATA[0000] could not format jq: could not read file: open /Users/e.savio/.jq: no such file or directory 

Do you know of a possible solution for this, if there is something that must have been wrong during the installation?

`conform.nvim` support

Trying to integrate conform.nvim with jqfmt:

      formatters = {
        jqfmt = {
          command = os.getenv("XDG_DATA_HOME") .. "/go/bin/jqfmt",
          args = { "-ob", "-ar", "-op", "pipe" },
        },
    }

This config will fail with:

21:14:51[ERROR] Formatter 'jqfmt' error: time="2024-07-06T21:14:51+03:00" level=fatal msg="could not read file: open /dev/stdin: no such device or address"

FR opened: stevearc/conform.nvim#396

conform.nvim will by default load the buffer into the formatter's stdin and read its stdout (formatters.jqfmt.stdin = true).

If stdin = false, it will create a temp file (will appear in "$FILENAME" args). The temp file is assumed to be modified in-place by the format command.

So, there are two options here. Figure out why and where /dev/stdin is gone and/or how to debug this or modify jqfmt to also have a -fix or -in-place option. I could give it a go, if you'd like. :)