/ 
JSON-Tiny-0.01
River stage two • 23 direct dependents • 30 total dependents
/ JSON::Tiny

NAME

JSON::Tiny - Minimalistic JSON. No dependencies.

SYNOPSIS

use JSON::Tiny;

my $json  = JSON::Tiny->new;
my $bytes = $json->encode({foo => [1, 2], bar => 'hello!'});
my $hash  = $json->decode($bytes);

DESCRIPTION

JSON::Tiny is a standalone adaptation of Mojo::JSON, from the fabulous Mojolicious "web in a box" framework (version 3.43). It has been adapted as a single-source-file module of about 345 lines of code with core-only dependencies.

Mojo::JSON was chosen as a starting point because it is so light-weight to begin with, robust, relaxed, and well tested. Furthermore, Mojo::JSON's tests were able to be adapted as easily as the module itself to a no non-core dependency configuration.

Most of the remainder of this document is adapted directly from Mojo::JSON. The names have been changed to protect the innocent.

JSON::Tiny is a minimalistic and relaxed implementation of RFC 4627. While it is possibly the fastest pure-Perl JSON parser available, you should not use it for validation.

It supports normal Perl data types like Scalar, Array reference, Hash reference and will try to call the TO_JSON method on blessed references, or stringify them if it doesn't exist.

[1, -2, 3]     -> [1, -2, 3]
{"foo": "bar"} -> {foo => 'bar'}

Literal names will be translated to and from JSON::Tiny constants or a similar native Perl value.

true  -> JSON::Tiny->true
false -> JSON::Tiny->false
null  -> undef

Decoding UTF-16 (LE/BE) and UTF-32 (LE/BE) will be handled transparently, encoding will only generate UTF-8. The two Unicode whitespace characters u2028 and u2029 will always be escaped to make JSONP easier.

ATTRIBUTES

JSON::Tiny implements the following attributes.

error

my $err = $json->error;
$json   = $json->error('Parser error');

Parser errors.

METHODS

JSON::Tiny implements the following methods.

new

my $json = JSON::Tiny->new;

Instantiate a JSON::Tiny object.

decode

my $array = $json->decode($bytes);
my $hash  = $json->decode($bytes);

Decode JSON.

encode

my $bytes = $json->encode({foo => 'bar'});

Encode Perl data structure.

false

my $false = JSON::Tiny->false;
my $false = $json->false;

False value, used because Perl has no native equivalent.

true

my $true = JSON::Tiny->true;
my $true = $json->true;

True value, used because Perl has no native equivalent.

It's Tiny

Comparing JSON::Tiny to JSON::PP (from the JSON distribution):

  • JSON is highly configurable (and comparatively complex). JSON::Tiny provides sane defaults, and a simple zero-configuration API.

  • Installation: cpanm JSON vs cpanm JSON::Tiny: JSON: 5.9 seconds. JSON::Tiny 1.8 seconds.

  • Minimal Dependencies: Both JSON and JSON::Tiny use only core dependencies. JSON::Tiny is backward compatible to Perl 5.10, while JSONJSON is backward compatible to 5.6.

  • Simple Design: JSON has 2254 lines of code spread across six modules and five files with a distribution tarball size of 84KB. JSON::Tiny has 345 lines of code in a single module, from a single file. It can even be easily embedded within existing code. The tarball size is 17KB.

  • Simple Interface: JSON::PP has around 42 functions and methods (many are setters/getters for behavioral attributes). JSON::Tiny has six.

  • Fast Performance (Benchmarks):

               Rate   JSON_PP JSON_Tiny
JSON_PP   288/s        --      -62%
JSON_Tiny 767/s      166%        --

    The script used to generate this benchmark is included in the JSON::Tiny distribution's examples/ folder. Note: JSON will automatically use JSON::XS if it's available, and in that case, JSON::XS blows all the pure-Perl modules away.

  • Light Memory Demands: From the distribution's examples/ folder, json_pp_alone.pl and json_tiny_alone.pl were tested, first using Devel::MemoryTrace::Light, and then using http://valgrind.org/valgrind. The results were as follows:

    • JSON (JSON::PP): About 1.7MB detected with Devel::MemoryTrace::Lite, and 6.1MB detected with valgrind.

    • JSON::Tiny: About 1.1MB detected with Devel::MemoryTrace::Lite, and 5.4MB detected with valgrind.

    Obviously the two utilities have very different methods of measuring memory use, but both show JSON::Tiny to be 600-700KB lighter weight than JSON::PP.

CONFIGURATION AND ENVIRONMENT

This module should run under any Perl from 5.10.0 onward.

DEPENDENCIES

This module uses only core dependencies.

INCOMPATIBILITIES

This module uses Perl constructs that are incompatible with pre v5.10.0 Perl.

AUTHOR

David Oswald, <davido at cpan.org>

The code and tests were adapted with minimal changes from Mojo::JSON.

SUPPORT

Support requests for this module should be directed to the author. Bug reports should be directed to CPAN's Request Tracker (RT), listed below.

You can find documentation for this module with the perldoc command.

perldoc JSON::Tiny

This module is maintained in a public repo at Github. You may look for information at:

ACKNOWLEDGEMENTS

Thank-you to the Mojolicious development team for producing an excellent product that implements light-weight versions of many useful tools. This module wouldn't exist (or wouldn't be as well tested and designed) if it had to be written from scratch.

Also to Randal Schwartz for mentioning that he had a need for an embeddable light-weight JSON parser, posting his pure-Regex solution on PerlMonks (http://www.perlmonks.org/?node_id=995856), and explaining it at Los Angeles PerlMongers (September 2012). Though he wasn't involved in JSON::Tiny, it was the exploration of alternatives to his solution that provided inspiration for this module.

LICENSE AND COPYRIGHT

Copyright 2012 David Oswald.

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

See http://www.perlfoundation.org/artistic_license_2_0 for more information.

SEE ALSO

JSON, JSON::PP, JSON::XS, Mojo::JSON, Mojolicious.