NAME

Mojo::JSON::MaybeXS - use JSON::MaybeXS as the JSON encoder for Mojolicious

SYNOPSIS

 use Mojo::JSON::MaybeXS;
 use Mojo::JSON qw/encode_json decode_json true false/;
 
 package My::Mojo::App;
 use Mojo::JSON::MaybeXS;
 use Mojo::Base 'Mojolicious';

DESCRIPTION

Mojo::JSON::MaybeXS is a monkey-patch module for using JSON::MaybeXS in place of Mojo::JSON in a Mojolicious application. It must be loaded before Mojo::JSON so the new functions will be properly exported.

CAVEATS

JSON::MaybeXS may load different modules depending on what is available, and these modules have slightly different behavior from Mojo::JSON and occasionally from each other. As of this writing, the author has found the following incompatibilities:

Boolean Stringification

If Cpanel::JSON::XS is loaded by JSON::MaybeXS (the default if available), the "true" in Mojo::JSON and "false" in Mojo::JSON booleans will stringify to "true" and "false". However, when using JSON::XS, or JSON::PP, they will stringify to "1" or "0", like in Mojo::JSON.

 print Mojo::JSON::false;
 # JSON::XS, JSON::PP, or Mojo::JSON: 0
 # Cpanel::JSON::XS: false

Object Conversion

Both JSON::MaybeXS and Mojo::JSON will attempt to call the TO_JSON method of a blessed reference to produce a JSON-friendly structure. If that method does not exist, JSON::MaybeXS will encode the object to null, while Mojo::JSON will stringify the object.

 print encode_json([DateTime->now]);
 # Mojo::JSON: ["2014-11-30T04:31:13"]
 # JSON::MaybeXS: [null]

Unblessed References

JSON::MaybeXS does not allow unblessed references other than hash and array references or references to the integers 0 and 1, and will throw an exception if attempting to encode one. Mojo::JSON will treat all scalar references the same as references to 0 or 1 and will encode them to true or false depending on their boolean value.

 print encode_json([\'asdf']);
 # Mojo::JSON: [true]
 # JSON::MaybeXS: dies

Escapes

Mojo::JSON currently escapes the slash character / for security reasons, as well as the unicode characters u2028 and u2029, while JSON::MaybeXS does not. This does not affect decoding of the resulting JSON.

 print encode_json(["/\x{2028}/\x{2029"]);
 # Mojo::JSON: ["\/\u2028\/\u2029"]
 # JSON::MaybeXS: ["/ / "]
 # Both decode to arrayref containing: "/\x{2028}/\x{2029}"

inf and nan

Mojo::JSON encodes inf and nan to strings, whereas JSON::MaybeXS will encode them as numbers (barewords) producing invalid JSON.

 print encode_json([9**9**9, -sin 9**9**9]);
 # Mojo::JSON: ["inf","nan"]
 # JSON::MaybeXS: [inf,nan]

Upgraded Numbers

JSON::MaybeXS will attempt to guess if a value to be encoded is numeric or string based on its last usage. Therefore, using a variable containing 13 in a string will cause it to be encoded as "13" even if the variable itself was not changed. Mojo::JSON will encode 13 as 13 regardless of whether it has been used as a string.

 my ($num1, $num2) = (13, 14);
 my $str = "$num1";
 print encode_json([$num1, $num2, $str]);
 # Mojo::JSON: [13,14,"13"]
 # JSON::MaybeXS: ["13",14,"13"]

BUGS

This is a monkey-patch of one of a few possible modules into another, and they have incompatibilities, so there will probably be bugs. Report any issues on the public bugtracker.

AUTHOR

Dan Book, dbook@cpan.org

CREDITS

Sebastian Riedel, author of Mojolicious, for basic implementation.

COPYRIGHT AND LICENSE

Copyright 2014, Dan Book.

This library is free software; you may redistribute it and/or modify it under the terms of the Artistic License version 2.0.

SEE ALSO

Mojo::JSON, JSON::MaybeXS, Cpanel::JSON::XS, JSON::XS, JSON::PP

cpanm Mojo::JSON::MaybeXS

perl -MCPAN -e shell
install Mojo::JSON::MaybeXS