View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
Matt S Trout > JSON-MaybeXS > JSON::MaybeXS



Annotate this POD


Open  0
View/Report Bugs
Module Version: 1.001000   Source   Latest Release: JSON-MaybeXS-1.004000


JSON::MaybeXS - use Cpanel::JSON::XS with a fallback to JSON::PP


  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 }


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 usage, you might want to pass options as constructor args rather than calling mutators, so we provide our own new method that supports that.


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


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


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


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.



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


mst - Matt S. Trout (cpan:MSTROUT) <>


None yet. Well volunteered? :)


Copyright (c) 2013 the JSON::MaybeXS "AUTHOR" and "CONTRIBUTORS" as listed above.


This library is free software and may be distributed under the same terms as perl itself.

syntax highlighting: