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 All of "encode_json", "decode_json" and "JSON" are exported by default. To import only some symbols, specify them on the "use" line: use JSON::MaybeXS qw(encode_json decode_json); # functions only use JSON::MaybeXS qw(JSON); # JSON constant only 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. CONSTRUCTOR new With JSON::PP, JSON::XS and Cpanel::JSON::XS you are required to call mutators to set options, i.e. 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). AUTHOR mst - Matt S. Trout (cpan:MSTROUT) CONTRIBUTORS * Clinton Gormley * Karen Etheridge 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.