JSON::JQ - jq ( library binding


  use JSON::JQ;
  my $jq = JSON::JQ->new({ script => '.' });
  # 1. process perl data
  my $results = $jq->process({ data => { foo => 'bar' }});
  # 2. process json string
  my $results = $jq->process({ json => '{ "foo": "bar" }'});
  # 3. process json file
  my $results = $jq->process({ json_file => 'foo.json' });
  # check items in @$results


This is a jq library binding, making it possible to process data using jq script/filter/module. Check the jq homepage for a detailed explanation and documentation.


new({ parameter => value, ... })

Construct a jq engine instance and return it, jq script must be provided by either script or script_file parameter.

  • script

    A string of jq script. The simplest one is '.', which does data 'echo'.

  • script_file

    A path to the file which contains the jq script. Shell-bang on first line will be ignored safely.

  • variable

    A hash reference with pre-defined variables and their values, they can be used by the jq script later. Complex data structures like nested arrays and/or hashes are acceptable.

    Check the jq official documentation on how to reference variables inside script.

  • library_paths

    An array reference with one or more directory paths inside. They will be used to search jq library/module when needed.

    The default search paths are '~/.jq' '$ORIGIN/../lib/jq' '$ORIGIN/lib', which confirm with jq executable.

    Check the jq official documentation on how to use this functionality in script.

process({ parameter => value, ... })

Process given input and return results as array reference. The input data must be provided via one of the parameters below.

  • data

    A Perl variable representing JSON formed data. The straight way to understand its equivalent is the return of JSON::from_json call.

    Any other type of data which the jq engine will accept can do. Such as undef, which says Null input. It is useful when the output data is created solely by a script itself.

    Bear in mind that the jq engine cannot understand (blessed) perl objects, with one exception - objects returned via JSON::true() or JSON::false(). They will be handled by underlying XS code properly before passing them to the jq engine.

    Check SPECIAL DATA MAPPING section below.

  • json

    A json encoded string. It will be decoded using JSON::from_json before handling to jq engine. Which also means, it must fully conform with the JSON specification.

  • json_file

    Similar to json parameter above, instead read the JSON string from given file.


The following JSON values are mapped to corresponding Perl values:

  • true: JSON::true

  • false: JSON::false

  • null: undef


The following jq engine callbacks are implemented:

error callback

Any error message raised by jq engine during its initialization and execution will be pushed into perl instance's private _error attribute. It is transparent to user, each method will croak on critical errors and show them.

debug callback

This is a builtin debug feature of the engine. It prints out debug messages when triggered. Check the jq official documentation for more details.


Limited debug functionality is implemented via the following module variables:

$JSON::JQ::DUMP_DISASM [default: off]

When on, print out the jq script disassembly code using jq_dump_disassembly.

$JSON::JQ::DEBUG [default: off]

Internal use only. When on, print out debug messages from XS code.


Please report bugs to


    Dongxu Ma
    dongxu _dot_ ma _at_


This program is free software licensed under the...

        The MIT License

The full text of the license can be found in the LICENSE file included with this module.


jq official wiki