JSON::MaybeXS - Use Cpanel::JSON::XS with a fallback to JSON::XS and JSON::PP
use JSON::MaybeXS; my $data_structure = decode_json($json_input); my $json_output = encode_json($data_structure); my $json = JSON->new; my $json_with_args = JSON::MaybeXS->new(utf8 => 1); # or { utf8 => 1 }
This module first checks to see if either Cpanel::JSON::XS or JSON::XS is already loaded, in which case it uses that module. Otherwise it tries to load Cpanel::JSON::XS, then JSON::XS, then JSON::PP in order, and either uses the first module it finds or throws an error.
It then exports the encode_json and decode_json functions from the loaded module, along with a JSON constant that returns the class name for calling new on.
encode_json
decode_json
JSON
new
If you're writing fresh code rather than replacing JSON.pm usage, you might want to pass options as constructor args rather than calling mutators, so we provide our own new method that supports that.
encode_json, decode_json and JSON are exported by default; is_bool is exported on request.
is_bool
To import only some symbols, specify them on the use line:
use
use JSON::MaybeXS qw(encode_json decode_json is_bool); # functions only use JSON::MaybeXS qw(JSON); # JSON constant only
To import all available sensible symbols (encode_json, decode_json, and is_bool), use :all:
:all
use JSON::MaybeXS ':all';
To import all symbols including those needed by legacy apps that use JSON::PP:
use JSON::MaybeXS ':legacy';
This imports the to_json and from_json symbols as well as everything in :all. NOTE: This is to support legacy code that makes extensive use of to_json and from_json which you are not yet in a position to refactor. DO NOT use this import tag in new code, in order to avoid the crawling horrors of getting UTF8 support subtly wrong. See the documentation for JSON for further details.
to_json
from_json
This is the encode_json function provided by the selected implementation module, and takes a perl data structure which is serialised to JSON text.
my $json_text = encode_json($data_structure);
This is the decode_json function provided by the selected implementation module, and takes a string of JSON text to deserialise to a perl data structure.
my $data_structure = decode_json($json_text);
See JSON for details. These are included to support legacy code only.
The JSON constant returns the selected implementation module's name for use as a class name - so:
my $json_obj = JSON->new; # returns a Cpanel::JSON::XS or JSON::PP object
and that object can then be used normally:
my $data_structure = $json_obj->decode($json_text); # etc.
$is_boolean = is_bool($scalar)
Returns true if the passed scalar represents either true or false, two constants that act like 1 and 0, respectively and are used to represent JSON true and false values in Perl.
true
false
1
0
Since this is a bare sub in the various backend classes, it cannot be called as a class method like the other interfaces; it must be called as a function, with no invocant. It supports the representation used in all JSON backends.
With JSON::PP, JSON::XS and Cpanel::JSON::XS you are required to call mutators to set options, such as:
my $json = $class->new->utf8(1)->pretty(1);
Since this is a trifle irritating and noticeably un-perlish, we also offer:
my $json = JSON::MaybeXS->new(utf8 => 1, pretty => 1);
which works equivalently to the above (and in the usual tradition will accept a hashref instead of a hash, should you so desire).
To include JSON-aware booleans (true, false) in your data, just do:
use JSON::MaybeXS; my $true = JSON->true; my $false = JSON->false;
mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
Clinton Gormley <drtech@cpan.org>
Karen Etheridge <ether@cpan.org>
Kieren Diment <diment@gmail.com>
Copyright (c) 2013 the JSON::MaybeXS "AUTHOR" and "CONTRIBUTORS" as listed above.
JSON::MaybeXS
This library is free software and may be distributed under the same terms as perl itself.
To install JSON::MaybeXS, copy and paste the appropriate command in to your terminal.
cpanm
cpanm JSON::MaybeXS
CPAN shell
perl -MCPAN -e shell install JSON::MaybeXS
For more information on module installation, please visit the detailed CPAN module installation guide.