1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117
|
NAME
JSON::MaybeXS - Use Cpanel::JSON::XS with a fallback to JSON::XS and
JSON::PP
SYNOPSIS
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 }
DESCRIPTION
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.
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.
EXPORTS
"encode_json", "decode_json" and "JSON" are exported by default;
"is_bool" is exported on request.
To import only some symbols, specify them on the "use" line:
use JSON::MaybeXS qw(encode_json decode_json is_bool); # functions only
use JSON::MaybeXS qw(JSON); # JSON constant only
To import all available symbols, use ":all":
use JSON::MaybeXS ':all';
encode_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);
decode_json
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);
JSON
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_bool
$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.
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.
CONSTRUCTOR
new
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).
BOOLEANS
To include JSON-aware booleans ("true", "false") in your data, just do:
use JSON::MaybeXS;
my $true = JSON->true;
my $false = JSON->false;
AUTHOR
mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
CONTRIBUTORS
* Clinton Gormley <drtech@cpan.org>
* Karen Etheridge <ether@cpan.org>
COPYRIGHT
Copyright (c) 2013 the "JSON::MaybeXS" "AUTHOR" and "CONTRIBUTORS" as
listed above.
LICENSE
This library is free software and may be distributed under the same
terms as perl itself.
|