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

NAME

JSON::Tiny - Minimalistic JSON. No dependencies.

SYNOPSIS

    use JSON::Tiny qw(decode_json encode_json);

    # Encode and decode JSON (die on errors)
    my $bytes = encode_json({foo => [1, 2], bar => 'hello!', baz => \1});
    my $hash  = decode_json($bytes);

    # Handle errors
    my $json = JSON::Tiny->new;
    my $hash = $json->decode($bytes);
    my $err  = $json->error;
    say $err ? "Error: $err" : $hash->{message};

DESCRIPTION

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

Key features include transparent Unicode support, speed, small memory footprint, and a minimal code base ideal for bundling or inlining. Along with Mojo:JSON, it is possibly the fastest pure-Perl implementation of RFC 7159.

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. Differentiating between strings and numbers in Perl is hard; depending on how it has been used, a Scalar can be both at the same time. Since numeric comparisons on strings are very unlikely to happen unintentionally, the numeric value always gets priority, so any Scalar that has been used in numeric context is considered a number.

    [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

In addition Scalar references will be used to generate Booleans, based on if their values are true or false.

  \1 => true
  \0 => false

The two Unicode whitespace characters u2028 and u2029 will always be escaped to make JSONP easier.

FUNCTIONS

JSON::Tiny implements the following functions, which can be imported individually.

decode_json

  my $value = decode_json($bytes);

Decode JSON to Perl value and die if decoding fails.

encode_json

  my $bytes = encode_json({foo => 'bar'});

Encode Perl value to JSON.

j

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

Encode Perl data structure (which may only be an Array reference or Hash reference) or decode JSON. Dies if decoding fails.

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 $value  = $json->decode($bytes);

Decode JSON to Perl value and set "error" if decoding failed.

encode

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

Encode Perl value 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, users requiring a plain old literal 0 or 1, may set $JSON::Tiny::FALSE = 0; and $JSON::Tiny::TRUE = 1;. Any value, including blessed references will work. The setting must be made prioror to calling a JSON decoding method or function. Use local to constrain the scope of the change.

Tiny

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

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

  • Download and install with cpanm: JSON::PP, 5.2 seconds. JSON::Tiny, 1.9 seconds.

  • 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, six modules and five files. Distribution: 85KB.

    JSON::Tiny has under 320 lines of code; a single-file module -- good for embedding. Distribution: 19KB.

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

  • Performance (Benchmarks):

                   Rate   JSON_PP JSON_Tiny
    JSON_PP   306/s        --      -51%
    JSON_Tiny 624/s      104%        --

    JSON uses JSON::XS if it's available, in which case JSON wins. See examples/json_benchmark.pl for benchmark code.

    JSON::Tiny's lightweight design reduces its startup time as compared to the JSON module. This is beneficial to frequently run applications like CGI.

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

                     valgrind    Devel::MemoryTrace::Light
    JSON::PP      8.0MB        5.9MB
    JSON::Tiny    7.6MB        5.0MB

CONFIGURATION AND ENVIRONMENT

No configuration.

DEPENDENCIES

Perl 5.8.1 or newer. However, Perl 5.10 is the recommended minimum due to bugs in Perl 5.8's regular expression engine.

INCOMPATIBILITIES

Incompatible with Exporter versions that predate Perl 5.8.4. For older Perl versions upgrade Exporter to version 5.59 or newer.

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 their excellent product that offers a lightweight JSON implementation. This module was adapted directly from Mojo::JSON, 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 demonstrated a pure-regexp JSON parser (PerlMonks) to Los Angeles Perl Mongers (Sept 2012). He wasn't involved in JSON::Tiny, but my exploration of alternatives to his solution led to this fork of Mojo::JSON.

LICENSE AND COPYRIGHT

Copyright 2012-2014 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

Mojo::JSON, JSON, RFC 7159.