Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/grinnz/mojo-json-maybexs

Module to use JSON::MaybeXS as the JSON renderer for Mojolicious.
https://github.com/grinnz/mojo-json-maybexs

Last synced: 5 days ago
JSON representation

Module to use JSON::MaybeXS as the JSON renderer for Mojolicious.

Awesome Lists containing this project

README 

        
=pod



=head1 NAME



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



=head1 SYNOPSIS



 use Mojo::JSON::MaybeXS;

 use Mojo::JSON qw/encode_json decode_json true false/;

 

 # Preload for scripts using Mojo::JSON

 $ perl -MMojo::JSON::MaybeXS -S morbo myapp.pl

 

 # Must be set in environment for hypnotoad

 $ PERL5OPT=-MMojo::JSON::MaybeXS hypnotoad myapp.pl



=head1 DESCRIPTION



L is a monkey-patch module for using L as

the JSON encoder for a L application, or anything else using

L. It must be loaded before L so the new functions will

be properly exported.



Since L version 7.87, L has delegated to

L by default if installed and recent enough. Installing

L version 7.87+ and L version 4.09+ resolves the

below listed caveats between these modules, and is sufficient to improve the

performance of L without the use of this module.



=head1 CAVEATS



L may load different modules behind the scenes depending on what

is available, and these modules have slightly different behavior from

L and occasionally from each other. References to the behavior of

L below are actually describing the behavior shared among the

modules it loads.



L is used with the options C, C,

C, C, and C. C

enables sorting of hash keys when encoding to JSON objects as L

does. C allows encoding and decoding of bare values outside of

hash/array references, since L does not prevent this, in accordance

with L. The other options prevent

the encoder from blowing up when encountering values that cannot be represented

in JSON to better match the behavior of L. See below for more

specifics.



To better match the behavior of L, certain options may be enabled

depending on the backend that is used. If L version 3.0112 or

greater is loaded, it will be used with the option C. If

either L of at least version 3.0206 or L is loaded,

it will be used with the option C. If L version

4.09 or greater is loaded, it will be used with the option C.



As of this writing, the author has found the following incompatibilities:



=head2 Object Conversion



Both L and L will attempt to call the TO_JSON method

of a blessed reference to produce a JSON-friendly structure. If that method

does not exist, L or L version 3.0207 or greater

will stringify the object, while L or L will always encode

it to C.



 print encode_json([DateTime->now]);

 # Mojo::JSON or Cpanel::JSON::XS >= 3.0207: ["2014-11-30T04:31:13"]

 # JSON::XS or JSON::PP: [null]



=head2 Unblessed References



L does not allow unblessed references other than to hashes,

arrays, or the scalar values C<0> and C<1>, and will encode them to C.

Before L version 7.87, L will treat all scalar

references the same as references to C<0> or C<1> and will encode them to

C or C depending on their boolean value, and other references

(code, filehandle, etc) will be stringified.



Since L version 7.87, L's behavior with unblessed

references is the same as L.



 print encode_json([\'asdf', sub { 1 }]);

 # Mojo::JSON (Mojolicious >= 7.87): [null,null]

 # JSON::MaybeXS: [null,null]



=head2 Escapes



L currently escapes the slash character C> for security reasons.

Before L version 7.87, it also escaped the unicode characters

C and C. L version 3.0206 or greater and

L will have the option set to escape the slash character, and

L does not escape these characters. This does not affect decoding of

the resulting JSON.



 print encode_json(["/\x{2028}/\x{2029}"]);

 # Mojo::JSON (Mojolicious >= 7.87): ["\/ \/ "]

 # Cpanel::JSON::XS >= 3.0206 or JSON::PP: ["\/ \/ "]

 # JSON::XS: ["/ / "]

 # Both decode to arrayref containing: "/\x{2028}/\x{2029}"



=head2 inf and nan



L encodes C and C to strings. L version

3.0112 or greater will also stringify C and C. However, L

or L will encode them as numbers (barewords) producing invalid JSON.



 print encode_json([9**9**9, -sin 9**9**9]);

 # Mojo::JSON or Cpanel::JSON::XS >= 3.0112: ["inf","nan"] (on Linux)

 # JSON::XS or JSON::PP: [inf,nan]



=head2 Upgraded Numbers



L, if using L, will attempt to guess if a value to be

encoded is numeric or string based on whether Perl has ever populated a string

value for it internally. Therefore, using a variable containing C<13> in a

string context will cause it to be encoded as C<"13"> even if the variable

itself was not changed. L, L version 2.92 or greater, or

L version 3.0109 or greater will encode C<13> as C<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, JSON::PP >= 2.92, Cpanel::JSON::XS >= 3.0109: [13,14,"13"]

 # JSON::XS: ["13",14,"13"]



=head2 Duplicate Keys



L, L, and L will silently accept duplicate keys

in the same JSON object when decoding a JSON string. L

version 3.0235 or greater will throw an exception if duplicate keys are

encountered. L version 4.09 or greater will have the option

set to once again accept duplicate keys.



 print dumper decode_json('{"foo":1, "bar":2, "foo":3}');

 # Mojo::JSON, JSON::XS, or JSON::PP: { bar => 2, foo => 3 }

 # Cpanel::JSON::XS >= 3.0235 and < 4.09: "Duplicate keys not allowed" exception



=head1 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.



=head1 AUTHOR



Dan Book, C



=head1 CREDITS



Sebastian Riedel, author of L, for basic implementation.



=head1 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.



=head1 SEE ALSO



L, L, L, L, L



=cut