🧩 JQ::Lite — Lightweight jq in Pure Perl

🌐 Project homepage

✨ What is JQ::Lite?

JQ::Lite is a pure-Perl JSON query engine inspired by jq.

It lets you query and transform JSON using jq-like syntax — without external binaries, native libraries, or compilation.

✅ Official Alpine Linux package

apk add jq-lite

JQ::Lite is designed for minimal environments such as:

• Alpine Linux
• containers & CI pipelines
• legacy / restricted / air-gapped systems

where simplicity, readability, and low dependency footprint matter.

🚀 Why jq-lite (in one glance)

• 🪶 Pure Perl — no XS, no C, no shared libraries

• 🔍 jq-style filters: .users[].name, select(...), map(...)

• 🔢 Arithmetic & conditionals: if ... then ... else ... end

• 🔧 CLI tool: jq-lite

  • --null-input, --slurp, --from-file
  • --yaml, --arg, --argjson, --ascii-output

• 📊 100+ built-in jq functions → see FUNCTIONS.md

• 💻 Interactive mode for exploring JSON

• 🧰 JSON & YAML input

• 🌐 Runs almost anywhere Perl runs → even legacy or air-gapped systems → see VISION.md

⚡ Quick Start (CLI)

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

Interactive exploration:

jq-lite users.json

🧱 Environment Support

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

✅ Runs on Perl ≥ 5.14 (e.g. CentOS 6, Debian 7 via perlbrew or local install)

💡 Why Pure Perl?

🧩 Portability

No compilation, no shared libraries. If Perl runs, jq-lite runs.

Perfect for:

• minimal containers
• legacy servers
• restricted or offline environments

🧰 Extensibility

Extend jq-like behavior directly in Perl.

You can integrate CPAN modules such as:

• LWP (HTTP / APIs)
• DBI (databases)
• filesystem or OS tools

🧱 Seamless Perl Integration

use JQ::Lite;

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

No external command calls. No parsing of CLI output.

⚙️ Lightweight Installation

• No XS / C toolchain
• No system-wide install required
• Ideal for CI/CD or user-local installs

🔍 Maintainability

• Faster iteration than C-based jq
• Easier debugging
• Community contributions are simpler

⚙️ Installation

🛠 From CPAN

cpanm JQ::Lite

🐧 Alpine Linux (Official)

apk add jq-lite

🍺 Homebrew (macOS)

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

🐳 Containers (Recommended)

Alpine-based image

FROM alpine
RUN apk add --no-cache jq-lite

jq-lite is ideal as a container-standard JSON tool:

• tiny footprint
• predictable behavior
• no native dependencies

🐧 Portable Installer (Online → Offline)

For air-gapped or offline systems:

1. Download (on connected machine)

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

1. Transfer JQ-Lite-<version>.tar.gz

2. Install

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

Default:

$HOME/.local

Environment setup:

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

🪟 Windows (PowerShell)

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

Verify:

jq-lite -v

🔍 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

📚 Documentation

• 📘 Functions: FUNCTIONS.md
• 🧭 Vision & portability: VISION.md
• 📦 MetaCPAN: https://metacpan.org/pod/JQ::Lite

👤 Author

Shingo Kawamura (川村慎吾) 📧 pannakoota1@gmail.com

📜 License

Same terms as Perl itself.