JQL
A JSON Query Language CLI tool built with Rust 🦀
📜 Core philosophy
- 📦 Stay lightweight
- 🎮 Keep its features as simple as possible
- 🧠 Avoid redundancy
- 💡 Provide meaningful error messages
- ↔️ Eat JSON as input, process, output JSON back
🚀 Installation
Cargo
Archlinux
The AUR package is maintained by @frol.
🛠️ Usage
If you find some of the following examples confusing, please have a look at The JavaScript Object Notation (JSON) Data Interchange Format.
Root selection
"This is a valid JSON text with one value"
"This is a valid JSON text with one value"
Child selection
"yay!"
Index selection
7
Please note that the following is also valid:
7
You can also select a set of indexes:
Range selection
Please note that you can reverse it:
Bonus, you can do it again to get it back:
Please note that you can still access the children:
"Misty"
You can also use the start or the end position as a range selector:
Array selection
Please note that this is basically an alias for a full range selection:
Property selection
Property selection can also be used with indexes and ranges. Please note that in this case a remapping/transformation is applied to the JSON data:
This is pretty unusual but it might help in some scenarios when e.g. one wants to extract some properties out of a complex JSON structure based on their order:
Multi-selection
Filter
You can also combine a filter with a child selection, a multi-selection and ranges at the same time:
Please note that you can combine filters to achieve the same result:
Flatten arrays
Truncate
The truncate selector !
can be used to stop walking the children's values and to explore an unknown JSON file / structure.
Each children is then transformed into a JSON primitive for convenience, e.g.:
primitive | value | result |
---|---|---|
object | { "a": 1, "b": 2, "c": 3 } |
{} |
array | [1, 2, 3] |
[] |
string | "foo" |
"foo" |
number | 666 |
666 |
null | null |
null |
Special characters
1337
"yeah!"
"yup, valid too!"
💻 Shell integration
How to save the output
How to read from stdin
|
Available flags 🤖
Help
Check
The command will return a matching exit code based on the validity of the JSON content or file provided. No selector is needed in this case!
Please note that this flag is exclusive.
Version
Inlining the JSON output
Raw output
Use the raw-output
flag on a string selection to directly return the raw string without JSON double-quotes:
|
|
Streaming
Use the stream
flag to read a stream of JSON lines:
while ; do ; ; done |
while ; do ; ; done |
Please note that this option is only about reading valid JSON output streamed line by line (e.g. Docker logs with the --follow
flag). This is not an option to read an incomplete streamed content (e.g. a very large input)!
🍿 Library
This crate is both a binary (the CLI tool) and a library that can be directly used https://docs.rs/crate/jql/.
⚡ Performance
Some benchmarks comparing a set of similar functionalities provided by this tool and jq are available here.