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 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 UTF8 support subtly wrong.  See the
       documentation for JSON for further details.

   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);

   to_json, from_json
       See JSON for details.  These are included to support legacy code only.

   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;

CAVEATS

       The "new()" method in this module is technically a factory, not a constructor, because the
       objects it returns will NOT be blessed into the "JSON::MaybeXS" class.

       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 /]));

AUTHOR

       mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>

CONTRIBUTORS

       •   Clinton Gormley <drtech@cpan.org>

       •   Karen Etheridge <ether@cpan.org>

       •   Kieren Diment <diment@gmail.com>

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.