🧩 JQ::Lite — Lightweight jq in Pure Perl

🌐 Project homepage

JQ::Lite is a pure-Perl JSON query engine inspired by jq. It allows you to query and transform JSON using jq-like syntax — without external binaries.

✨ Highlights

• 🪶 Pure Perl — no XS or C dependencies
• 🔍 jq-style filters: .users[].name, .nickname?, select(...), map(...)
• 🔢 Supports arithmetic & conditionals: if ... then ... else ... end
• 🔧 CLI tool: jq-lite with --null-input, --slurp, --from-file, --yaml, --arg
• 📊 Built-in 100+ jq functions (see FUNCTIONS.md)
• 💻 Interactive mode for exploring JSON
• 🧰 Works with JSON or YAML input
• 🌐 Compatible with almost any Linux (even legacy or air-gapped) (see VISION.md)

💡 Why Pure Perl?

Unlike the original jq written in C, JQ::Lite is implemented entirely in Perl.
This design choice brings several practical advantages:

🧩 Portability

No compilation, no shared libraries — it runs anywhere Perl runs.
Perfect for restricted, legacy, or air-gapped environments.

🧰 Extensibility

Add or customize jq-like functions directly in Perl.
Leverage CPAN modules (LWP, DBI, etc.) to integrate with APIs, databases, or filesystems.

🧱 Integration

Use it seamlessly inside Perl scripts:

use JQ::Lite;
my $jq = JQ::Lite->new;
say for $jq->run_query($json, '.users[].name');

No need to call external binaries or parse command output.

⚙️ Lightweight Installation

No XS/C libraries or make install required — just cpanm JQ::Lite or the portable installer. Ideal for CI/CD pipelines or user-level installations.

🔍 Maintainability

Perl’s expressive syntax allows faster development and debugging. Community patches and feature extensions are easier than C-level contributions.

⚙️ Installation

🛠 From CPAN

cpanm JQ::Lite

🍺 Homebrew (macOS)

brew tap kawamurashingo/jq-lite
brew install --HEAD jq-lite

🐧 Portable Installer (Online → Offline)

For air-gapped or offline systems

1. Download on a connected machine

   ./download.sh [-v <version>] [-o /path/to/usb]
   

   → Produces JQ-Lite-<version>.tar.gz.

2. Transfer the tarball to the target (offline) machine.

3. Install (Linux/macOS)

   ./install.sh [-p <prefix>] [--skip-tests] /path/to/JQ-Lite-<version>.tar.gz
   

   Default install path: $HOME/.local

   export PATH="$HOME/.local/bin:$PATH"
   export PERL5LIB="$HOME/.local/lib/perl5/site_perl:$PERL5LIB"
   

🪟 Windows (PowerShell)

1. Open PowerShell and run:

   .\install-jq-lite.ps1 [-Prefix <path>] [--SkipTests] C:\path\to\JQ-Lite-<version>.tar.gz
   

2. Add to your PowerShell profile (optional):

   $env:PATH = "$env:USERPROFILE\.local\bin;" + $env:PATH
   $env:PERL5LIB = "$env:USERPROFILE\.local\lib\perl5\site_perl;" + $env:PERL5LIB
   

3. Verify:

   jq-lite -v
   

🚀 Usage

As a Perl module

use JQ::Lite;
my $jq = JQ::Lite->new;
my @names = $jq->run_query('{"users":[{"name":"Alice"}]}', '.users[].name');
print join("\n", @names);

As a CLI tool

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

💡 Try interactive mode:

jq-lite users.json

🧱 Environment Support

| Environment | jq | jq-lite | | -------------------- | -- | ------- | | Legacy CentOS / RHEL | ❌ | ✅ | | Alpine Linux | ⚠️ | ✅ | | Air-gapped / Proxy | ❌ | ✅ | | No root privilege | ⚠️ | ✅ |

✅ Runs on Perl ≥ 5.14, even on CentOS 6 or Debian 7 with perlbrew or local install.

🔍 Example Queries

jq-lite '.users[] | select(.profile.active) | .name' users.json
jq-lite '.users | sort_by(.age) | map(.name) | join(", ")' users.json
jq-lite '.users[].nickname? // .name' users.json

🧠 More Functions

See the complete list in 👉 FUNCTIONS.md or on MetaCPAN

👤 Author

Shingo Kawamura 📧 perl.jq.lite@gmail.com

📜 License

Same terms as Perl itself.