Crates.io | jql-parser |
lib.rs | jql-parser |
version | 7.1.13 |
source | src |
created_at | 2023-04-21 21:41:00.248679 |
updated_at | 2024-07-10 13:13:35.774632 |
description | Parser for jql - the JSON Query Language tool. |
homepage | |
repository | https://github.com/yamafaktory/jql |
max_upload_size | |
id | 845664 |
size | 47,709 |
jql
is a JSON Query Language tool built with Rust 🦀.
Pronounce it as jackal 🐺.
The package is maintained by @jirutka.
apk add jql
The AUR package is maintained by @barklan.
yay -S jql
cargo install jql
cargo binstall jql
dnf install jql
pkg install jql
brew install jql
nix-env -i jql
zypper install jql
Compiled binary versions are automatically uploaded to GitHub when a new release is made. You can install jql
manually by downloading a release.
To make a selection from a JSON input, jql
expects a query as a sequence of tokens.
To be fully compliant with the JSON format, jql
always expect key selectors to be double-quoted, see The JavaScript Object Notation (JSON) Data Interchange Format.
{
".valid": 1337,
"": "yeah!",
"\"": "yup, valid too!"
}
Consequently, to be shell compliant, a query must be either enclosed by single quotation marks or every inner double quotation mark must be escaped.
Group separators build up an array from sub-queries.
JSON input
{ "a": 1, "b": 2, "c": 3 }
Query
'"a","b","c"'
JSON output
[1, 2, 3]
Indexes can be used in arbitrary order.
JSON input
[1, 2, 3]
Query
'[2,1]'
JSON output
[3, 2]
Range can be in natural order [0:2]
, reversed [2:0]
, without lower [:2]
or upper bound [0:]
.
JSON input
[1, 2, 3]
Query
'[2:1]'
JSON output
[3, 2]
Lens can be a combination of one or more selectors with or an optional value, a value being any of boolean | null | number | string.
JSON input
[
{ "a": 1, "b": { "d": 2 } },
{ "a": 2, "b": "some" },
{ "a": 2, "b": { "d": null } },
{ "a": 2, "b": true },
{ "c": 3, "b": 4 }
]
Query
'|={"b""d"=2, "c"}'
JSON output
[
{ "a": 1, "b": { "d": 2 } },
{ "c": 3, "b": 4 }
]
Any valid JSON key can be used.
JSON input
{ "a": 1, "b": 2, "c": 3 }
Query
'"c"'
JSON output
3
Keys can be used in arbitrary order.
JSON input
{ "a": 1, "b": 2, "c": 3 }
Query
'{"c","a"}'
JSON output
{ "c": 3, "a": 1 }
Indexes can be used in arbitrary order.
JSON input
{ "a": 1, "b": 2, "c": 3 }
Query
'{2,0}'
JSON output
{ "c": 3, "a": 1 }
Range can be in natural order {0:2}
, reversed {2:0}
, without lower {:2}
or upper bound {0:}
.
JSON input
{ "a": 1, "b": 2, "c": 3 }
Query
'{2:1}'
JSON output
{ "c": 3, "b": 2 }
Flattens arrays and objects.
JSON input
[[[[[[[[[[[[[[{ "a": 1 }]]]]]]]]]]]]], [[[[[{ "b": 2 }]]]], { "c": 3 }], null]
Query
'..'
JSON output
[{ "a": 1 }, { "b": 2 }, { "c": 3 }, null]
JSON input
{ "a": { "c": false }, "b": { "d": { "e": { "f": 1, "g": { "h": 2 } } } } }
Query
'..'
JSON output
{
"a.c": false,
"b.d.e.f": 1,
"b.d.e.g.h": 2
}
Applies the next tokens in parallel on each element of an array.
JSON input
{ "a": [{ "b": { "c": 1 } }, { "b": { "c": 2 } }] }
Query
'"a"|>"b""c"'
JSON output
[1, 2]
Stops the parallelization initiated by the pipe in operator.
JSON input
{ "a": [{ "b": { "c": 1 } }, { "b": { "c": 2 } }] }
Query
'"a"|>"b""c"<|[1]'
JSON output
2
Maps the output into simple JSON primitives boolean | null | number | string | [] | {}.
JSON input
{ "a": [1, 2, 3] }
Query
'"a"!'
JSON output
[]
jql '"a"' input.json > output.json
cat test.json | jql '"a"'
By default, the output is pretty printed in a more human-readable way, this can be disabled.
-i, --inline
The command will read the provided query from a file instead of the stdin.
-q, --query <FILE>
This can be useful to drop the double-quotes surrounding a string primitive.
-r, --raw-string
This flag is only about reading processing any 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).
-s, --stream
The command will return a matching exit code based on the validity of the JSON content or file provided.
-v, --validate
-h, --help
-V, --version
jql -h
jql --help
This project is composed of following crates:
Some commands are available as a justfile
at the root of the workspace (testing / fuzzing).
just --list
There's no plan to align jql
with jq
or any other similar tool.
Some benchmarks comparing a set of similar functionalities provided by this tool and jq are available here.