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 }
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.
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 sensible symbols ("encode_json", "decode_json", and "is_bool"), use ":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 UTF-8 support subtly wrong. See the documentation for JSON for further details.
my $json_text = encode_json($data_structure);
my $data_structure = decode_json($json_text);
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.
The use of parentheses here is optional, and only used as a hint to the reader that this use of "JSON" is a subroutine call, not a class name.
$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.
Available since version 1.002004.
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).
The resulting object is blessed into the underlying backend, which offers (at least) the methods "encode" and "decode".
use JSON::MaybeXS; my $true = JSON()->true; my $false = JSON()->false;
The booleans are also available as subs or methods on JSON::MaybeXS.
use JSON::MaybeXS (); my $true = JSON::MaybeXS::true; my $true = JSON::MaybeXS->true; my $false = JSON::MaybeXS::false; my $false = JSON::MaybeXS->false;
Change code from:
use JSON::Any; my $json = JSON::Any->new->objToJson($data); # or to_json($data), or Dump($data)
to:
use JSON::MaybeXS; my $json = encode_json($data);
Change code from:
use JSON::Any; my $data = JSON::Any->new->jsonToObj($json); # or from_json($json), or Load($json)
to:
use JSON::MaybeXS; my $json = decode_json($data);
If you are using an object returned by this module as a Moo(se) attribute, this type constraint code:
is 'json' => ( isa => 'JSON::MaybeXS' );
will NOT do what you expect. Instead, either rely on the "JSON" class constant described above, as so:
is 'json' => ( isa => JSON::MaybeXS::JSON() );
Alternatively, you can use duck typing:
use Moose::Util::TypeConstraints 'duck_type'; is 'json' => ( isa => Object , duck_type([qw/ encode decode /]));
Because running XS code is not mandatory and JSON::PP (which is in perl core) is used as a fallback backend, this module is safe to be used in a suite of code that is fatpacked or installed into a restricted-resource environment.
You can also prevent any XS dependencies from being installed by setting "PUREPERL_ONLY=1" in Makefile.PL options (or in the "PERL_MM_OPT" environment variable), or using the "--pp" or "--pureperl" flags with the cpanminus client.