/ 
JQ-Lite-0.29
River stage zero No dependents
/ JQ::Lite

NAME

JQ::Lite - A lightweight jq-like JSON query engine in Perl

VERSION

Version 0.29

SYNOPSIS

use JQ::Lite;

my $jq = JQ::Lite->new;
my @results = $jq->run_query($json_text, '.users[].name');

for my $r (@results) {
    print encode_json($r), "\n";
}

DESCRIPTION

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, with no external binaries or XS modules.

FEATURES

  • Pure Perl (no XS, no external binaries)

  • Dot notation (e.g. .users[].name)

  • Optional key access with '?' (e.g. .nickname?)

  • Array indexing and flattening (e.g. .users[0], .users[])

  • select(...) filters with ==, !=, <, >, and, or

  • Pipe-style query support (e.g. .[] | select(.age > 25) | .name)

  • Built-in functions: length, keys, first, last, reverse, sort, unique, has

  • count function to return the number of results (v0.29+)

  • count function to count number of elements in an array

  • group_by(...) to group array items by a key

  • Command-line interface: jq-lite

  • Interactive mode for line-by-line query exploration

  • Decoder selection via --use (JSON::PP, JSON::XS, etc)

  • Debug output via --debug

CONSTRUCTOR

new

my $jq = JQ::Lite->new;

Creates a new instance. Options may be added in future versions.

METHODS

run_query

my @results = $jq->run_query($json_text, $query);

Runs a jq-like query against the given JSON string.

The return value is a list of matched results. Each result is a Perl scalar (string, number, arrayref, hashref, etc.) depending on the query.

SUPPORTED SYNTAX

  • .key.subkey

  • .array[0]

  • .array[] (flattening)

  • .key? (optional access)

  • select(.key > 1 and .key2 == "foo")

  • group_by(.field)

  • .key | count

  • .[] | select(...) | count

  • .array | count

  • Functions: length, keys, first, last, reverse, sort, unique, has

  • .[] as alias for flattening top-level arrays

COMMAND LINE USAGE

jq-lite is a CLI wrapper for this module.

cat data.json | jq-lite '.users[].name'
jq-lite '.users[] | select(.age > 25)' data.json
jq-lite -r '.users[].name' data.json
jq-lite '.[] | select(.active == true) | .name' data.json
jq-lite '.users[] | select(.age > 25) | count' data.json

Interactive Mode

Omit the query to enter interactive mode:

jq-lite data.json

You can then type queries line-by-line against the same JSON input.

Decoder Selection and Debug

jq-lite --use JSON::PP --debug '.users[0].name' data.json

REQUIREMENTS

Uses only core modules:

  • JSON::PP

Optional: JSON::XS, Cpanel::JSON::XS, JSON::MaybeXS

SEE ALSO

JSON::PP, jq

AUTHOR

Kawamura Shingo <pannakoota1@gmail.com>

LICENSE

Same as Perl itself.