#CLI #JSON #tool

bin+lib jql

A JSON query language CLI tool

27 releases (15 stable)

✓ Uses Rust 2018 edition

2.4.2 Mar 1, 2019
2.4.1 Feb 28, 2019
2.3.4 Jan 11, 2019
2.2.0 Dec 26, 2018
0.1.7 Oct 31, 2018

#28 in Command line utilities

Download history 22/week @ 2018-11-17 49/week @ 2018-11-24 61/week @ 2018-12-01 86/week @ 2018-12-08 19/week @ 2018-12-15 50/week @ 2018-12-22 28/week @ 2018-12-29 76/week @ 2019-01-05 43/week @ 2019-01-12 33/week @ 2019-01-19 18/week @ 2019-01-26 14/week @ 2019-02-02 9/week @ 2019-02-09 6/week @ 2019-02-16 45/week @ 2019-02-23

169 downloads per month

MIT license

57KB
1.5K SLoC

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 install jql

🛠️ 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"
jql '.' example.json
"This is a valid JSON text with one value"

Child selection

{
  "some": {
    "property": "yay!"
  }
}
jql '"some"."property"' example.json
"yay!"

Index selection

{
  "primes": [7, 11, 13]
}
jql '"primes".[0]' example.json
7

Please note that the following is also valid:

jql '"primes"[0]"' example.json
7

You can also select a set of indexes:

jql '"primes".[2,0]' example.json
[
  13,
  7
]

Range selection

{
  "cats": [{ "first": "Pixie" }, { "second": "Kitkat" }, { "third": "Misty" }]
}
jql '"cats".[1:2]' example.json
[
  {
    "second": "Kitkat"
  },
  {
    "third": "Misty"
  }
]

Please note that you can reverse it:

jql '"cats".[2:1]' example.json
[
  {
    "third": "Misty"
  },
  {
    "second": "Kitkat"
  }
]

Bonus, you can do it again to get it back:

jql '"cats".[2:1].[1:0]' example.json
[
  {
    "second": "Kitkat"
  },
  {
    "third": "Misty"
  }
]

Please note that you can still access the children:

jql '"cats".[2:1].[0]."third"' example.json
"Misty"

You can also use the start or the end position as a range selector:

jql '"cats".[1:]' example.json
[
  {
    "second": "Kitkat"
  },
  {
    "third": "Misty"
  }
]
jql '"cats".[:1]' example.json
[
  {
    "first": "Pixie"
  },
  {
    "second": "Kitkat"
  }
]

Array selection

{
  "primes": [7, 11, 13]
}
jql '"primes".[]' example.json
[
  7,
  11,
  13
]

Please note that this is basically an alias for a full range selection:

jql '"primes".[0:2]' example.json

Property selection

{
  "object": { "a": 1, "b": 2, "c": 3 }
}
jql '"object".{"a","c"}' example.json
{
  "a": 1,
  "c": 3
}

Multi-selection

{
  "one": [1, 2, 3],
  "two": 2,
  "three": 3
}
jql '"one".[2:0],"two","three"' example.json
[
  [
    3,
    2,
    1
  ],
  2,
  3
]

Filter

{
  "laptops": [
    {
      "laptop": {
        "brand": "Apple",
        "options": ["a", "b", "c"]
      }
    },
    {
      "laptop": {
        "brand": "Asus",
        "options": ["d", "e", "f"]
      }
    }
  ]
}
jql '"laptops"|"laptop"' example.json
[
  {
    "brand": "Apple",
    "options": ["a", "b", "c"]
  },
  {
    "brand": "Asus",
    "options": ["d", "e", "f"]
  }
]

You can also combine a filter with a child selection, a multi-selection and ranges at the same time:

jql '"laptops"|"laptop"."brand"' example.json
[
  "Apple",
  "Asus"
]
jql '"laptops".[1:0]|"laptop"."brand","laptops"|"laptop"."brand"' example.json
[
  [
    "Asus",
    "Apple"
  ],
  [
    "Apple",
    "Asus"
  ]
]

Please note that you can combine filters to achieve the same result:

jql '"laptops".[1:0]|"laptop"|"brand","laptops"|"laptop"|"brand"' example.json
[
  "Apple",
  "Asus"
]

Flattening arrays

{
  "dna": [[[[["c", "a", "c"]]]], "g", "t", [[["a", ["t"]]]]]
}
jql '.."dna"' example.json
[
  "c",
  "a",
  "c",
  "g",
  "t",
  "a",
  "t"
]

Special characters

{
  ".valid": 1337,
  "": "yeah!",
  "\"": "yup, valid too!"
}
jql '".valid"' example.json
1337
jql '""' example.json
"yeah!"
jql '"\""' example.json
"yup, valid too!"

💻 Shell integration

How to save the output

jql '"foo"."bar"' input.json > output.json

How to read from stdin

cat example.json | jql '"foo"."bar"'

Available flags 🤖

Help

jql -h
jql --help

Version

jql -V
jql --version

Inlining the JSON output

jql -i '"some"."selector"' example.json
jql --inline '"some"."selector"' example.json

🍿 Library

This crate is both a binary (the CLI tool) and a library that can be directly used https://docs.rs/crate/jql/.

Dependencies

~5.5MB
~94K SLoC