The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
JSON-Tiny-0.40
River stage two • 16 direct dependents • 21 total dependents
13 ++
/ JSON::Tiny

NAME

JSON::Tiny - Minimalistic JSON. No dependencies.

SYNOPSIS

    use JSON::Tiny;

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

    # Check for errors
    my $json = JSON::Tiny->new;
    if(defined(my $hash = $json->decode($bytes))) { say $hash->{message} }
    else { say 'Error: ', $json->error }

    # Use the alternative interface
    use JSON::Tiny 'j';
    my $bytes = j({foo => [1, 2], bar => 'hello!', baz => \1});
    my $hash  = j($bytes);

DESCRIPTION

JSON::Tiny is a minimalistic standalone adaptation of Mojo::JSON, from the Mojolicious framework. It is a single-source-file module with 350 lines of code and core-only dependencies.

Key features include RFC 4627 JSON, transparent Unicode support, speed, small memory footprint, and a minimal code base ideal for bundling or inlining. JSON::Tiny and Mojo::JSON are possibly the fastest pure-Perl implementations of RFC 4627.

JSON::Tiny 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. In addition Scalar references will be used to generate booleans, based on if their values are true or false.

    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.

FUNCTIONS

JSON::Tiny implements the following functions.

j

    my $bytes = j([1, 2, 3]);
    my $bytes = j({foo => 'bar'});
    my $array = j($bytes);
    my $hash  = j($bytes);

Encode Perl data structure or decode JSON and return undef if decoding fails.

Dies with a JSON::Tiny::error message on decode failure.

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 to Perl data structure and return undef if decoding fails.

encode

    my $bytes = $json->encode([1, 2, 3]);
    my $bytes = $json->encode({foo => 'bar'});

Encode Perl data structure to JSON.

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.

More on Booleans

A reference to a scalar (even if blessed) will also be encoded as a Boolean value unless it has a TO_JSON method.

    my $json = $j->encode( { b => \1, a => \0 } ); # {"b":true,"a":false}

Boolean false and true values returned when JSON is decoded are JSON::Tiny::_Bool objects with stringification and numeric overloading. As an advanced option, if the user requires a plain old literal 0 or 1, setting $JSON::Tiny::FALSE = 0; and $JSON::Tiny::TRUE = 1;, or some other value, including blessed references prior to calling the decode method will have the desired effect. Use local to prevent the change from causing errors at a distance.

Tiny

Comparing JSON::Tiny with JSON::PP from the JSON distribution:

  • JSON::PP is configurable, but more complex. JSON::Tiny offers sane defaults, and zero configuration.

  • Installation with cpanm: JSON::PP, 5.2 seconds. JSON::Tiny, 1.9 seconds (including download).

  • Minimal Dependencies: Both JSON::PP and JSON::Tiny only use core dependencies. JSON::Tiny requires Perl 5.8.4, while JSON::PP requires 5.6.

  • Simple Design: JSON has 2254 lines of code in six modules and five files, and a dist tarball of 84KB. JSON::Tiny has 350 lines of code; a single module in a single file -- great for embedding. The tarball is 19KB.

  • JSON::PP has 42 functions and methods. JSON::Tiny has seven.

  • Performance (Benchmarks):

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

    The benchmark code is included in this distribution's examples/ folder. JSON will automatically use JSON::XS if it's available, in which case JSON::XS wins.

    JSON::Tiny's lightweight design also reduces its startup time as compared to the JSON module. This may be beneficial in applications such as CGI, where processes are started frequently.

  • Light Memory Needs: Memory usage was tested with http://valgrind.org/valgrind and Devel::MemoryTrace::Lite by running examples/json_pp_alone.pl and examples/json_tiny_alone.pl.

    • JSON (JSON::PP) -- Devel::MemoryTrace::Lite: 1.7MB. valgrind: 6.1MB.

    • JSON::Tiny -- Devel::MemoryTrace::Lite: 1.1MB. valgrind: 5.4MB.

    These utilities show that JSON::Tiny is 600-700KB smaller than JSON::PP.

CONFIGURATION AND ENVIRONMENT

No configuration.

DEPENDENCIES

Perl 5.8.4 or newer.

INCOMPATIBILITIES

Incompatible with Exporter versions that predate Perl 5.8.4. Perl 5.8.4 shipped with Exporter v5.58. Exporter became dual-life as of v5.59. Upgrade Exporter to v5.59 or newer for Perl versions older than 5.8.4.

AUTHOR

David Oswald, <davido at cpan.org>

Code and tests were adapted from Mojo::JSON.

SUPPORT

Directed support requests to the author. Direct bug reports to CPAN's Request Tracker (RT).

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

    perldoc JSON::Tiny

You may look for additional information at:

ACKNOWLEDGEMENTS

The Mojolicious team for producing an excellent product that offers light-weight implementations of many useful tools. This module was adapted directly from Mojo::JSON, which was chosen as a model because it is robust, minimal, and well tested. Mojo::JSON's tests were also adapted to a dependency-free design.

Christian Hansen, whos GitHub Gist provided the basis for Mojo::JSON, from which this module is derived.

Randal Schwartz for showing Los Angeles Perl Mongers (Sept 2012) his pure-regexp JSON parser (PerlMonks). He wasn't involved in JSON::Tiny, but it was exploring alternatives to his solution that led to this fork of Mojo::JSON.

LICENSE AND COPYRIGHT

Copyright 2012-2013 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.