NAME

JSON::JQ - jq (https://stedolan.github.io/jq/) library binding

SYNOPSIS

  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

DESCRIPTION

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.

METHODS

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.

SPECIAL DATA MAPPING

The following JSON values are mapped to corresponding Perl values:

• true: JSON::true

• false: JSON::false

• null: undef

CALLBACKS

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.

DEBUG

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.

BUGS

Please report bugs to https://github.com/dxma/perl5-json-jq/issues.

AUTHOR

    Dongxu Ma
    CPAN ID: DONGXU
    dongxu _dot_ ma _at_ gmail.com
    https://github.com/dxma

COPYRIGHT

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.

SEE ALSO

jq official wiki

cpanm JSON::JQ

perl -MCPAN -e shell
install JSON::JQ