/ 
JSON-JQ-0.02
River stage zero No dependents
/ JSON::JQ

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 jq library binding, making it possible to process data using jq script/filter/module. Check jq homepage for detail 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 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 straight 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.

    Bear 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 conform with JSON speculation.

  • 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

* L<jq official wiki|https://github.com/stedolan/jq/wiki>