4 ms·

JQ is often frustrating when you want to do something non-trivial but you can't figure out how and the documentation is of little help. I think JQ could really

JQ is often frustrating when you want to do something non-trivial but you can't figure out how and the documentation is of little help. I think JQ could really benefit from having a classic programming language style "book", like "The AWK Programming Language". JQ is fundamentally a functional programming language with semantics that are not obvious reading its current docs.

doytch 5y ago
I've also found the documentation tough to use when I need to jump back in and answer something like "how do I _____?" It feels like one of those sets of docs that's better approached by just reading the whole damn thing, working through some examples, etc. Studying the docs as opposed to referring to them.
- psanford 5y ago
  Right, I agree. But I think the way the docs are currently written are not really meant to be read through like that. Thats why I mentioned "The AWK Programming Language" book, which is excellently written, and easy to read from start to end. I don't mean to denigrate the current docs, writing documentation is hard!
matthewtovbin 5y ago
Try JSONata instead - http://docs.jsonata.org/overview.html http://docs.jsonata.org/overview.html
- loa_in_ 5y ago
  It doesn't seem to provide a command-line tool, which is the point of jq
  - matthewtovbin 5y ago
    Look no more - https://github.com/blgm/jfq https://github.com/blgm/jfq
psacawa 5y ago
This exists. At least, a detailed manual exists. It's the jq wiki on github [1]. Lots of detailed information/recipes. [1]: https://github.com/stedolan/jq/wiki https://github.com/stedolan/jq/wiki
- psanford 5y ago
  Whoa, I didn't know this existed. This does seem to address a lot of what I want. I wish that were more prominently linked to from https://stedolan.github.io/jq/ https://stedolan.github.io/jq/.
Niksko 5y ago
Agreed. It's usually just a bunch of trial and error for me, or trying to phrase my problem in a way that matches stack overflow questions. And the docs for yq (the jq for YAML) are 100 times worse. The documentation feels like it was written by aliens. Even incredibly simple things are impossible for me to find in the yq docs.

doytch 5y ago

I've also found the documentation tough to use when I need to jump back in and answer something like "how do I _____?" It feels like one of those sets of docs that's better approached by just reading the whole damn thing, working through some examples, etc. Studying the docs as opposed to referring to them.

psanford 5y ago
Right, I agree. But I think the way the docs are currently written are not really meant to be read through like that. Thats why I mentioned "The AWK Programming Language" book, which is excellently written, and easy to read from start to end. I don't mean to denigrate the current docs, writing documentation is hard!

matthewtovbin 5y ago

Try JSONata instead - http://docs.jsonata.org/overview.html http://docs.jsonata.org/overview.html

loa_in_ 5y ago
It doesn't seem to provide a command-line tool, which is the point of jq
- matthewtovbin 5y ago
  Look no more - https://github.com/blgm/jfq https://github.com/blgm/jfq

psacawa 5y ago

This exists. At least, a detailed manual exists. It's the jq wiki on github [1]. Lots of detailed information/recipes. [1]: https://github.com/stedolan/jq/wiki https://github.com/stedolan/jq/wiki

psanford 5y ago
Whoa, I didn't know this existed. This does seem to address a lot of what I want. I wish that were more prominently linked to from https://stedolan.github.io/jq/ https://stedolan.github.io/jq/.

Niksko 5y ago

Agreed. It's usually just a bunch of trial and error for me, or trying to phrase my problem in a way that matches stack overflow questions. And the docs for yq (the jq for YAML) are 100 times worse. The documentation feels like it was written by aliens. Even incredibly simple things are impossible for me to find in the yq docs.