JQ::Lite

JQ::Lite is a lightweight, pure-Perl JSON query engine inspired by the jq command-line tool.
It allows you to extract, traverse, and filter JSON data using a simplified jq-like syntax — entirely within Perl.

🔧 Features

• ✅ Pure Perl (no XS, no external binaries)
• ✅ Dot notation (.users[].name)
• ✅ Optional key access (.nickname?)
• ✅ Array indexing and expansion (.users[0], .users[])
• ✅ select(...) filters with ==, !=, <, >, and, or
• ✅ Built-in functions: length, keys, first, last, reverse, sort, unique, has
• ✅ Command-line interface: jq-lite
• ✅ Reads from STDIN or file
• ✅ Interactive mode for exploring JSON line-by-line
• ✅ v0.19+: --use option to select decoder (JSON::PP, JSON::XS, etc.)
• ✅ v0.19+: --debug option to show active JSON module

🤔 Why JQ::Lite (vs jq or JSON::PP)?

| Use Case | Tool | |-----------------------|-----------------| | Simple JSON decode | ✅ JSON::PP | | Shell processing | ✅ jq | | jq-style queries in Perl | ✅ JQ::Lite | | Lightweight & portable | ✅ JQ::Lite |

📦 Installation

perl Makefile.PL
make
make test
make install

🚀 Usage

As a Perl module

use JQ::Lite;

my $json = '{"users":[{"name":"Alice"},{"name":"Bob"}]}';
my $jq = JQ::Lite->new;
my @names = $jq->run_query($json, '.users[].name');

print join("\n", @names), "\n";

As a command-line tool

cat users.json | jq-lite '.users[].name'
jq-lite '.users[] | select(.age > 25)' users.json
jq-lite -r '.users[].name' users.json

for windows

type user.json | jq-lite ".users[].name"
jq-lite -r ".users[].name" users.json

⚠️ jq-lite is named to avoid conflict with the real jq.

🔄 Interactive Mode

If you omit the query, jq-lite enters interactive mode, allowing you to type queries line-by-line against a fixed JSON input.

jq-lite users.json

jq-lite interactive mode. Enter query (empty line to quit):
> .users[0].name
"Alice"
> .users[] | select(.age > 25)
{
  "name" : "Alice",
  "age" : 30,
  ...
}

• Results will be re-rendered each time, clearing the previous output (like a terminal UI).
• Works with --raw-output (-r) as well.

🔍 v0.19+: Decoder selection and debug output

You can now explicitly select which JSON module to use (JSON::PP, JSON::XS, or Cpanel::JSON::XS) and see what is used with --debug.

$ jq-lite --debug .users[0].age users.json
[DEBUG] Using Cpanel::JSON::XS
30

$ jq-lite --use JSON::PP .users[0].age users.json
30

$ jq-lite --use JSON::PP --debug .users[0].age users.json
[DEBUG] Using JSON::PP
30

📘 Example Input

{
  "users": [
    {
      "name": "Alice",
      "age": 30,
      "profile": {
        "active": true,
        "country": "US"
      }
    },
    {
      "name": "Bob",
      "age": 25,
      "profile": {
        "active": false,
        "country": "JP"
      }
    }
  ]
}

Example Queries

jq-lite '.users[].name' users.json
jq-lite '.users | length' users.json
jq-lite '.users[0] | keys' users.json
jq-lite '.users[].nickname?' users.json
jq-lite '.users[] | select(.age > 25)' users.json
jq-lite '.users[] | select(.profile.active == true) | .name' users.json
jq-lite '.users | sort | reverse | first' users.json

🧪 Testing

prove -l t/

📦 CPAN

👉 JQ::Lite on MetaCPAN

📝 License

This module is released under the same terms as Perl itself.

👤 Author

Kawamura Shingo
📧 pannakoota1@gmail.com
🔗 GitHub @kawamurashingo