Project overview

On this page

Overview Design Goals Stable CLI Contract Stable Library API Contract Requirements and installation Containers Perl Integration Explore the documentation License

このページの目次

利用する場面設計上の目標 CLIの互換性仕様 Library APIの互換性仕様必要な環境導入方法コンテナ Perlへの組み込み詳しく読むライセンス

jq-liteは、Pure Perlで実装された軽量な、jqに似たJSONプロセッサーです。CLIの長期安定性と少ない依存を重視し、制約のある環境や長期運用するシステムのJSON処理に適しています。

外部バイナリ不要。
ネイティブライブラリ不要。
コンパイル不要。
テストで保護された安定したCLI仕様。
文書化されたLibrary APIの互換性仕様。

利用する場面

jqに似た構文でJSONを抽出・変換し、Perlが利用できるシステム間で移植しやすくします。

最小構成のLinux。
コンテナとCI。
古いシステムや制限された環境。
オフライン・隔離環境。
jqを導入できない環境。

Alpine Linuxの公式パッケージとしても提供されています。

apk add jq-lite

設計上の目標

安定したCLI

終了コード、標準エラーの接頭辞、エラー時の動作を長期の互換性の約束として扱います。

安定したLibrary API

文書化した公開Perl APIは、同じメジャーバージョン内で互換性を保ちます。

少ない依存

XS、C拡張、外部ライブラリを使わないPure Perl実装です。

予測可能な動作

シェルスクリプト、CI、インフラ自動化、下流のPerlモジュールを想定しています。機能を増やすことより信頼性を優先します。

CLIの互換性仕様

終了コードと意味、エラー分類、標準出力の成功・失敗時の動作、-e/--exit-statusの真偽判定、パイプ切断時の振る舞いを定義しています。保証を破る変更にはメジャーバージョン更新が必要です。

CLI仕様を読む

Library APIの互換性仕様

公開メソッド、引数、返り値、バージョン管理の方針を定義しています。2.xの安定した入口は以下です。

my $jq = JQ::Lite->new(%options);
my @results = $jq->run_query($json_text, $query);

意図的な破壊的変更にはメジャーバージョン更新が必要です。

Library API仕様を読む

必要な環境

Perl 5.14以上で動作します。古いホスト、オフライン環境、管理者権限のない環境では、Perlと依存モジュールを準備して利用できます。実際の導入可否は各環境の条件を確認してください。

導入方法

CPAN、Alpine Linux、配布アーカイブから導入できます。

インストールガイドを読む

コンテナ

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

ネイティブ依存を追加せずに、コンテナのJSON処理の道具として利用できます。

Perlへの組み込み

use JQ::Lite;
my $jq = JQ::Lite->new;
my @results = $jq->run_query($json, '.users[].name');
print "$_\n" for @results;

組み込みガイドに依存宣言、結果、エラー処理を掲載しています。内部モジュールではなく文書化した公開APIへ依存してください。

詳しく読む

CLI仕様 — 終了コード・エラー・パイプラインの振る舞い。
Library API仕様 — 公開メソッド・返り値・互換性の保証。
Perl組み込みガイド — 依存宣言・結果の扱い・エラー処理。
対応関数 — 目的別の対応関数リファレンス。
jqとの互換性 — jq 1.7とJQ::Lite 2.xの意味論の差分。
3.0ロードマップ — 変更計画・移行の指針・リリース条件。
設計方針 — 移植性・安定性・内部構造。

ライセンス

Perl本体と同じ条件で提供します。

jq-lite is a lightweight, jq-compatible alternative JSON processor written in pure Perl.

It is designed for long-term CLI stability and minimal dependencies, making it suitable as an OS-level JSON utility in constrained or long-lived environments.

No external binaries
No native libraries
No compilation step
Stable, test-backed CLI contract
Documented Library API compatibility contract

Overview

jq-lite allows querying and transforming JSON using jq-like syntax, while remaining fully portable across systems where Perl is available.

It is particularly suited for:

minimal Linux distributions
containers and CI environments
legacy or restricted systems
offline / air-gapped deployments
environments where jq cannot be installed

jq-lite is available as an official Alpine Linux package:

apk add jq-lite

Design Goals

Stable CLI contract Exit codes, stderr prefixes, and error behavior are treated as long-term compatibility promises.
Stable Library API contract Documented public Perl APIs are treated as compatibility promises within a major release series.
Minimal dependency footprint Implemented in pure Perl without XS, C extensions, or external libraries.
Predictable behavior Intended for use in shell scripts, CI pipelines, infrastructure automation, and downstream Perl modules.

jq-lite intentionally prioritizes reliability over feature growth.

Stable CLI Contract

jq-lite defines a fully implemented, test-backed CLI contract that serves as a strict backward-compatibility guarantee.

The contract specifies:

Exit codes and their meanings
Error categories and stderr prefixes
stdout behavior on success and failure
jq-compatible truthiness semantics (-e/--exit-status)
Broken pipe (SIGPIPE/EPIPE) behavior suitable for pipelines and CI

Contract specification: docs/cli-contract.md

Any change that would violate this contract requires a major version bump and is intentionally avoided.

Stable Library API Contract

JQ::Lite can be used as a dependency by applications and other CPAN distributions. The documented public Library API has its own compatibility contract covering public methods, documented arguments, return-value semantics, and versioning expectations.

The stable 2.x entry points currently include:

my $jq = JQ::Lite->new(%options);
my @results = $jq->run_query($json_text, $query);

Contract specification: docs/library-contract.md

Intentional breaking changes to this documented Library API require a major version bump.

Requirements and installation

Requires Perl 5.14 or later. Install through CPAN or Alpine Linux, or use a release archive.

View installation instructions

Containers

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

jq-lite can be used as a container-standard JSON processing tool without introducing native dependencies.

Perl Integration

jq-lite can also be used directly from Perl code:

use JQ::Lite;

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

For dependency declarations, result handling, and error-handling guidance, see docs/library-integration.md.

Downstream users should rely on documented public entry points rather than implementation submodules. See the Library API contract for compatibility guarantees.

Explore the documentation

CLI contract — Exit codes, errors and pipeline behavior.
Library API contract — Public methods, result types and compatibility guarantees.
Perl integration guide — Dependency declarations, results and error handling.
Function reference — Supported functions, grouped by purpose.
Compatibility with jq — Semantic differences between jq 1.7 and JQ::Lite 2.x.
3.0 roadmap — Planned changes, migration guidance and release criteria.
Design principles — Portability, stability and internal architecture.

License

Same terms as Perl itself.

All documentation Home