NAME

       JSON::MaybeXS - use Cpanel::JSON::XS with a fallback to 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 tries to load Cpanel::JSON::XS, and if that fails instead tries to load
       JSON::PP. If neither is available, an exception will be thrown.

       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 stucture 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 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) <mst@shadowcat.co.uk>

CONTRIBUTORS

       None yet. Well volunteered? :)

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.