/ 
JQ-Lite-0.39
/ JQ::Lite

NAME

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

VERSION

Version 0.39

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 required)

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

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

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

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

  • Pipe-style query chaining using | operator

  • Built-in functions: length, keys, values, first, last, reverse, sort, sort_by, unique, has, group_by, join, count, empty, type, nth, del, compact

  • Supports map(...) and limit(n) style transformations

  • Interactive mode for exploring queries line-by-line

  • Command-line interface: jq-lite (compatible with stdin or file)

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

  • Debug output via --debug

  • List all functions with --help-functions

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. Returns 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] (index access)

  • .array[] (flattening arrays)

  • .key? (optional key access)

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

  • group_by(.field) (group array items by key)

  • sort_by(.key) (sort array of objects by key)

  • .key | count (count items or fields)

  • .[] | select(...) | count (combine flattening + filter + count)

  • .array | map(.field) | join(", ")

    Concatenates array elements with a custom separator string. Example:

    .users | map(.name) | join(", ")

    Results in:

    "Alice, Bob, Carol"

  • values()

    Returns all values of a hash as an array. Example:

    .profile | values

  • empty()

    Discards all output. Compatible with jq. Useful when only side effects or filtering is needed without output.

    Example:

    .users[] | select(.age > 25) | empty

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

  • type()

    Returns the type of the value as a string: "string", "number", "boolean", "array", "object", or "null".

    Example:

    .name | type     # => "string"
.tags | type     # => "array"
.profile | type  # => "object"

  • nth(n)

    Returns the nth element (zero-based) from an array.

    Example:

    .users | nth(0)   # first user
.users | nth(2)   # third user

  • del(key)

    Deletes a specified key from a hash object and returns a new hash without that key.

    Example:

    .profile | del("password")

    If the key does not exist, returns the original hash unchanged.

    If applied to a non-hash object, returns the object unchanged.

  • compact()

    Removes undef and null values from an array.

    Example:

    .data | compact()

    Before: [1, null, 2, null, 3]

    After: [1, 2, 3]

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
jq-lite '.users | map(.name) | join(", ")'
jq-lite '.users[] | select(.age > 25) | empty'
jq-lite '.profile | values'

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

Show Supported Functions

jq-lite --help-functions

Displays all built-in functions and their descriptions.

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.