Author image Dongxu Ma
and 1 contributors


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 jq library binding, making it possible to process data using jq script/filter/module. Check jq homepage for detail 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 simplist one is '.', which does data 'echo'.

  • script_file

    A path to file which contains 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 jq script later. Complex data structure like nested array and/or hash is acceptable.

    Check 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 jq officiall 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 prameters below.

  • data

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

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

    Bare in mind that jq engine cannot understand (blessed) perl objects, with one exception - object returned via JSON::true() or JSON::false(). They will be handled by underlying XS code properly before passing them to 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 confirm with JSON speculation.

  • json_file

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


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 jq official docucmentation for more detail.


Limited debug functionality is implemented via 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 bug 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.


   * L<jq official wiki|>