/ 
JSON-Tiny-0.43
River stage two • 22 direct dependents • 29 total dependents
/ 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;
if(defined(my $hash = $json->decode($bytes))) { say $hash->{message} }
else { say 'Error: ', $json->error }

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 RFC4627 JSON implementations.

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.

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

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, which can be imported individually.

decode_json

my $array = decode_json($bytes);
my $hash  = decode_json($bytes);

Decode JSON to Perl data structure and die if decoding fails.

encode_json

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

Encode Perl data structure to JSON.

j (DEPRECATED)

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 die if decoding fails.

This function has been deprecated. RFC7159 specifies that scalars are now legitimate encode/decode entities, which makes j()'s ability to decide whether to encode or decode an intractable question. This function will be removed in an upcoming release without further warning.

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

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 in six modules and five files, and a dist tarball of 85KB. JSON::Tiny has under 350 lines of code; a single module in a single file -- good for embedding. The tarball is 19KB.

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

  • Performance (Benchmarks):

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

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

    JSON::Tiny's lightweight design 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. However, Perl 5.10 or newer is recommended due to bugs in the Perl 5.8.x regular expression engine.

INCOMPATIBILITIES

Incompatible with Exporter versions that predate Perl 5.8.4. Upgrade Exporter to version 5.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 a lightweight JSON implementation. 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 demonstrated his 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 regexp 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

JSON, JSON::PP, Mojo::JSON.