/ 
JSON-Tiny-0.38
River stage two • 22 direct dependents • 29 total dependents
/ 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 standalone adaptation of Mojo::JSON, from the Mojolicious framework. It is a single-source-file module of under 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.

Mojo::JSON 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.

Much of this POD is inherited directly from Mojo::JSON.

JSON::Tiny is a minimalistic and (Along with Mojo::JSON) possibly the fastest pure-Perl implementation of RFC 4627.

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. 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 to some other value, including blessed references prior to calling the decode method will have the desired effect. Using local to prevent the change from causing errors at a distance is probably a very good idea.

It's Tiny

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

  • JSON::PP is configurable, and comparatively complex. JSON::Tiny offers sane defaults, and nothing to configure.

  • Installation: cpanm JSON::PP vs cpanm JSON::Tiny: 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 facilitating embedding within existing code. The tarball is 18KB.

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

  • Fast Performance (Benchmarks):

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

    The benchmark script is included in this distribution's examples/ folder. JSON will automatically use JSON::XS if it's available. In that case, JSON::XS does win.

    Because JSON::Tiny doesn't pull in many external modules, and splits the POD into a separate file to minimize the source-code file size, startup time for JSON::Tiny is slightly faster than for the JSON module. This may be beneficial in applications such as CGI, where processes may are started frequently.

  • Light Memory Needs: From the distribution's examples/ folder, json_pp_alone.pl and json_tiny_alone.pl were tested, first with Devel::MemoryTrace::Light, and then with http://valgrind.org/valgrind. Here are the results:

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

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

    These utilities measuer memory in different ways, but both show JSON::Tiny is 600-700KB lighter 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.

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.