NAME
JSON::Tiny - Minimalistic JSON. No dependencies.
SYNOPSIS
my
$bytes
= encode_json {
foo
=> [1, 2],
bar
=>
'hello!'
,
baz
=> \1};
my
$hash
= decode_json
$bytes
;
DESCRIPTION
JSON::Tiny is a minimalistic standalone adaptation of Mojo::JSON, from the Mojolicious framework. It is a single-source-file module with under 300 lines of code and core-only dependencies.
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 among the fastest pure-Perl implementations 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. The string value has a higher precedence unless both representations are equivalent.
[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
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, and the character /
to prevent XSS attacks.
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.
false
my
$false
= false;
False value, used because Perl has no equivalent.
from_json
my
$value
= from_json
$chars
;
Decode JSON text that is not UTF-8
encoded to Perl value and die if decoding fails.
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. An undef
return value indicates a bare null
. Dies if decoding fails.
to_json
my
$chars
= to_json {
i
=>
'♥ Perl'
};
Encode Perl value to JSON text without UTF-8
encoding it.
true
my
$true
= true;
True value, used because Perl has no native equivalent.
More on Booleans
A reference to a scalar (even if blessed) is 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 overloaded stringification.
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. This must be set prior to calling a JSON decoding function. Use local
to limit scope.
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 300 lines of code; an embeddable single-file module. Distribution: 18KB.
JSON::PP has 42 functions and methods. JSON::Tiny has seven.
Performance:
Rate JSON_PP JSON_Tiny
JSON_PP 304/s -- -52%
JSON_Tiny 636/s 109% --
JSON uses JSON::XS if it's available, in which case JSON wins. See
examples/json_bench.pl
for benchmark code.JSON::Tiny's lightweight design reduces its startup time compared to the JSON module. This may benefit 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.pl
andexamples/json_tiny.pl
.valgrind Devel::MemoryTrace::Light
JSON::PP 5.1MB 3.7MB
JSON::Tiny 4.5MB 2.6MB
CONFIGURATION AND ENVIRONMENT
No configuration.
DEPENDENCIES
Perl 5.8.4 or newer. Perl 5.10+ is recommended due to bugs in Perl 5.8's regular expression engine.
INCOMPATIBILITIES
Incompatible with Exporter versions older than 5.59 (ie, predating Perl 5.8.4).
AUTHOR
David Oswald, <davido at cpan.org>
Code and tests adapted from Mojo::JSON.
SUPPORT
Direct 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:
Github: Development is hosted on Github at:
RT: CPAN's request tracker (bug reports)
AnnoCPAN: Annotated CPAN documentation
CPAN Ratings
Search CPAN
ACKNOWLEDGEMENTS
Mojolicious team for its lightweight JSON implementation. This module was adapted from Mojo::JSON 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 formed the basis for Mojo::JSON, and subsequently JSON::Tiny.
Randal Schwartz showed his pure-regexp JSON parser (PerlMonks) to Los Angeles Perl Mongers (09/2012). He wasn't involved in JSON::Tiny, but exploring alternatives to his solution led to this project.
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.