/ 
JQ-XS-1.01
/ JQ::XS

NAME

JQ::XS - Perl wrapper for libjq

SYNOPSIS

use JQ::XS;

my $jq = JQ::XS->new('.foo[] | select(. > 2)');

# Perl data interface
my @results = $jq->process({ foo => [1, 3, 5] });
# Returns: (3, 5)

# JSON text interface
my @out = $jq->process_json('{"foo":[1,3,5]}');
# Returns: ('3', '5')

# Get the program source
my $prog = $jq->program;

DESCRIPTION

JQ::XS provides a clean object-oriented wrapper around libjq, the C library behind the jq command-line tool. It allows you to:

- Compile and execute jq filter programs - Process Perl data structures (hashes, arrays, numbers, strings) - Process JSON text - Handle errors gracefully with Perl exceptions (croak)

METHODS

new($program)

Creates a new JQ::XS object by compiling the given jq filter program.

my $jq = JQ::XS->new('.foo');

Croaks with an error message if the program fails to compile.

process($data)

Processes Perl data through the compiled jq filter. Takes a Perl scalar (which can be a reference to a hash or array) and returns a list of results. Each result is a Perl data structure.

my @results = $jq->process({ name => 'Alice' });

In scalar context, returns an arrayref of results.

my $results_ref = scalar($jq->process($data));

Croaks if the jq filter produces a runtime error or if the processing fails.

Boolean handling

JSON booleans returned by a filter become JSON::PP::Boolean objects, which behave as true/false in boolean context and stringify to 1 and 0. They compare equal to the JSON::PP::true and JSON::PP::false constants.

my ($is_big) = JQ::XS->new('. > 2')->process(5);   # JSON::PP::true

On input, the following are converted to JSON true/false:

  • JSON::PP::Boolean, Types::Serialiser::Boolean, or boolean objects (by their truth value)

  • unblessed references to a plain scalar, e.g. \1 and \0

  • Perl's native boolean values, i.e. the results of comparison and logical operators and of builtin::true/builtin::false

    $jq->process($x > $y);   # jq sees true or false, not 1 or ""

    On perls before 5.36 this only works for a boolean passed directly to process(); a copy (e.g. stored in a hash or array first) loses its boolean identity and is treated as an ordinary number/string. On perl 5.36 and later, copies keep their boolean flag and are recognized anywhere in the structure.

process_json($json_text)

Like process, but takes JSON text as input and returns a list of JSON strings (one for each output).

my @json_out = $jq->process_json('{"name":"Alice"}');

Croaks if the JSON input is invalid or if the jq filter produces a runtime error.

program()

Returns the source code of the compiled jq filter program.

my $src = $jq->program;

CONSTANTS

The following constants are available via @EXPORT_OK:

JQ_DEBUG_TRACE       - value 1
JQ_DEBUG_TRACE_DETAIL - value 2
JQ_DEBUG_TRACE_ALL    - value 3

AUTHOR

James Rouzier <rouzier@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2026 James Rouzier

This library is free software; you can redistribute it and/or modify it under the terms of the MIT license. See the LICENSE file included with this distribution.