The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Mojo-JSON_XS-1.022
River stage zero No dependents
++
/ Mojo::JSON_XS

NAME

Mojo::JSON_XS - Faster JSON processing for Mojolicious

SYNOPSIS

  use Mojo::JSON_XS;  # Must be earlier than Mojo::JSON
  use Mojo::JSON qw(to_json from_json ...);

DESCRIPTION

Using Mojo::JSON_XS overrides Mojo::JSON, so your JSON processing will be done by compiled C code rather than pure perl. Cpanel::JSON::XS is a hard dependency, so is required both at installation time and run time.

DEPRECATED

This code was merged into Mojolicious v7.87, so it only makes sense to continue using this module if you are constrained to a Mojolicious earlier than that.

USAGE

You absolutely must use Mojo::JSON_XS before anything uses Mojo::JSON.

I suggest that in your top-level file (myapp.pl for a lite app and script/my_app for a full app) you use this module very early in the file (even if you do not mention any other JSON in that file).

CAVEATS

The underlying module Cpanel::JSON::XS generates slightly different results (since it is maintaining compatibility with JSON::XS) from the results you would get from Mojo::JSON. Be sure to check each of the differences noted below and consider the impact on your application. Clearly it is no use generating the wrong output quickly when you could have the correct output (less quickly).

The examples below show to_json because it is slightly shorter, but usually it is encode_json that you will want. Remember too that j is available ("FUNCTIONS" in Mojo::JSON) particularly for commandline testing.

Slashes

Mojo::JSON escapes slashes when encoding (to mitigate script-injection attacks).

  perl -MMojo::JSON=to_json -E'say to_json(q{/})'
  # produces "\/"

  perl -MMojo::JSON_XS -MMojo::JSON=to_json -E'say to_json(q{/})'
  # produces "/"

and similar for encode_json.

Unicode

Mojo::JSON uses uppercase for hex values when encoding

  perl -MMojo::JSON=to_json -E'say to_json(qq{\x1f})'
  # produces "\u001F"

  perl -MMojo::JSON_XS -MMojo::JSON=to_json -E'say to_json(qq{\x1f})'
  # produces "\u001f"

and similar for encode_json. Cf http://tools.ietf.org/html/rfc7159.

Mojo::JSON makes special cases for security, so u2028 and u2029 are rendered in their codepoint form.

  perl -MMojo::JSON=to_json -E'say to_json(qq{\x{2028}})'
  # produces "\u2028"

  perl -MMojo::JSON_XS -MMojo::JSON=to_json -E'say to_json(qq{\x{2028}})'
  # produces the unicode character

References

Mojo::JSON can encode references (as Boolean).

  perl -MMojo::JSON=to_json -E'$a = q{string}; say to_json(\$a)'
  # produces "true"

  perl -MMojo::JSON_XS -MMojo::JSON=to_json -E'$a = q{string}; say to_json(\$a)'
  # produces error
  # "cannot encode reference to scalar unless the scalar is 0 or 1"

Numbers

Mojo::JSON detects numbers much better.

  perl -MMojo::JSON=to_json -E'$a = 2; say to_json(["$a", $a])'
  # produces "["2",2]"

  perl -MMojo::JSON_XS -MMojo::JSON=to_json -E'$a = 2; say to_json(["$a", $a])'
  # produces "["2","2"]"

Mojo::JSON encodes inf and nan as strings.

  perl -MMojo::JSON=to_json -E'say to_json(9**9**9)'
  # produces "inf"

  perl -MMojo::JSON_XS -MMojo::JSON=to_json -E'say to_json(9**9**9)'
  # produces inf

Error Messages

The handling and format of error messages is different between the two modules, as you would expect.

SUPPORT

Although the code is gifted by Sebastian Riedel, this is not part of the Mojolicious distribution. Saying that, it is likely you can find someone on the IRC channel happy to discuss this module. Any bugs or issues should be logged in the specific Github account.

IRC

#mojo on irc.perl.org

Github Issue Tracker

https://github.com/niczero/mojo-jsonxs/issues

COPYRIGHT AND LICENCE

Copyright (C) 2014--17, Sebastian Riedel, Nic Sandfield.

This program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.

SEE ALSO

Mojo::JSON, Cpanel::JSON::XS.