JSON::Tiny(3pm)

1JSON::Tiny(3)         User Contributed Perl Documentation        JSON::Tiny(3)
2
3
4

NAME

6       JSON::Tiny - Minimalistic JSON. No dependencies.
7

SYNOPSIS

9         use JSON::Tiny qw(decode_json encode_json);
10
11         my $bytes = encode_json {foo => [1, 2], bar => 'hello!', baz => \1};
12         my $hash  = decode_json $bytes;
13

DESCRIPTION

15       JSON::Tiny is a minimalistic standalone adaptation of Mojo::JSON, from
16       the Mojolicious framework. It is a single-source-file module with under
17       300 lines of code and core-only dependencies.
18
19       Features include transparent Unicode support, speed, small memory
20       footprint, and a minimal code base ideal for bundling or inlining.
21       Along with Mojo::JSON, it is among the fastest pure-Perl
22       implementations of RFC 7159 <http://tools.ietf.org/html/rfc7159>.
23
24       JSON::Tiny supports normal Perl data types like scalar, array
25       reference, hash reference, and will try to call the TO_JSON method on
26       blessed references, or stringify them if it doesn't exist.
27
28       Differentiating between strings and numbers in Perl is hard; depending
29       on how it has been used, a scalar can be both at the same time. The
30       string value has a higher precedence unless both representations are
31       equivalent.
32
33         [1, -2, 3]     -> [1, -2, 3]
34         {"foo": "bar"} -> {foo => 'bar'}
35
36       Literal names will be translated to and from JSON::Tiny constants or a
37       similar native Perl value.
38
39         true  -> JSON::Tiny->true
40         false -> JSON::Tiny->false
41         null  -> undef
42
43       Scalar references will be used to generate Booleans, based on if their
44       values are true or false.
45
46         \1 => true
47         \0 => false
48
49       The two Unicode whitespace characters "u2028" and "u2029" will always
50       be escaped to make JSONP easier, and the character "/" to prevent XSS
51       attacks.
52

FUNCTIONS

54       JSON::Tiny implements the following functions, which can be imported
55       individually.
56
57   decode_json
58         my $value = decode_json $bytes;
59
60       Decode JSON to Perl value and die if decoding fails.
61
62   encode_json
63         my $bytes = encode_json {foo => 'bar'};
64
65       Encode Perl value to JSON.
66
67   false
68         my $false = false;
69
70       False value, used because Perl has no equivalent.
71
72   from_json
73         my $value = from_json $chars;
74
75       Decode JSON text that is not "UTF-8" encoded to Perl value and die if
76       decoding fails.
77
78   j
79         my $bytes = j [1, 2, 3];
80         my $bytes = j {foo => 'bar'};
81         my $value = j $bytes;
82
83       Encode Perl data structure (which may only be an array reference or
84       hash reference) or decode JSON. An "undef" return value indicates a
85       bare "null".  Dies if decoding fails.
86
87   to_json
88         my $chars = to_json {i => '♥ Perl'};
89
90       Encode Perl value to JSON text without "UTF-8" encoding it.
91
92   true
93         my $true = true;
94
95       True value, used because Perl has no native equivalent.
96
97       More on Booleans
98
99       A reference to a scalar (even if blessed) is encoded as a Boolean value
100       unless it has a TO_JSON method.
101
102         my $json = $j->encode( { b => \1, a => \0 } ); # {"b":true,"a":false}
103
104       Boolean false and true values returned when JSON is decoded are
105       JSON::Tiny::_Bool objects with overloaded stringification.
106
107       Advanced option: Users requiring a plain old literal 0 or 1, may set
108       "$JSON::Tiny::FALSE = 0;" and "$JSON::Tiny::TRUE = 1;". Any value,
109       including blessed references will work. This must be set prior to
110       calling a JSON decoding function. Use "local" to limit scope.
111

Tiny

113       JSON::Tiny compared with JSON::PP from the JSON distribution:
114
115       •   JSON::PP is configurable, but more complex. JSON::Tiny offers sane
116           defaults, and no configuration.
117
118       •   Download and install with "cpanm": JSON::PP, 5.2 seconds.
119           JSON::Tiny, 1.9 seconds.
120
121       •   Minimal Dependencies: Both JSON::PP and JSON::Tiny only use core
122           dependencies. JSON::Tiny requires Perl 5.8.4, while JSON::PP
123           requires 5.6.
124
125       •   Simple Design: JSON has 2254 lines of code, six modules and five
126           files. Distribution: 85KB.
127
128           JSON::Tiny has under 300 lines of code; an embeddable single-file
129           module.  Distribution: 18KB.
130
131       •   JSON::PP has 42 functions and methods. JSON::Tiny has seven.
132
133       •   Performance:
134
135                        Rate   JSON_PP JSON_Tiny
136             JSON_PP   304/s        --      -52%
137             JSON_Tiny 636/s      109%        --
138
139           JSON uses JSON::XS if it's available, in which case JSON wins.  See
140           "examples/json_bench.pl" for benchmark code.
141
142           JSON::Tiny's lightweight design reduces its startup time compared
143           to the JSON module. This may benefit frequently run applications
144           like CGI.
145
146       •   Light Memory Needs: Memory usage was tested with
147           <http://valgrind.org/valgrind> and Devel::MemoryTrace::Light by
148           running "examples/json_pp.pl" and "examples/json_tiny.pl".
149
150                        valgrind  Devel::MemoryTrace::Light
151             JSON::PP   5.1MB     3.7MB
152             JSON::Tiny 4.5MB     2.6MB
153

CONFIGURATION AND ENVIRONMENT

155       No configuration.
156

DEPENDENCIES

158       Perl 5.8.4 or newer. Perl 5.10+ is recommended due to bugs in Perl
159       5.8's regular expression engine.
160

INCOMPATIBILITIES

162       Incompatible with Exporter versions older than 5.59 (ie, predating Perl
163       5.8.4).
164

AUTHOR

166       David Oswald, "<davido at cpan.org>"
167
168       Code and tests adapted from Mojo::JSON.
169

SUPPORT

171       Direct support requests to the author. Direct bug reports to CPAN's
172       Request Tracker (RT).
173
174       You can find documentation for this module with the perldoc command.
175
176         perldoc JSON::Tiny
177
178       You may look for additional information at:
179
180       •   Github: Development is hosted on Github at:
181
182           <http://www.github.com/daoswald/JSON-Tiny>
183
184       •   RT: CPAN's request tracker (bug reports)
185
186           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=JSON-Tiny>
187
188       •   AnnoCPAN: Annotated CPAN documentation
189
190           <http://annocpan.org/dist/JSON-Tiny>
191
192       •   CPAN Ratings
193
194           <http://cpanratings.perl.org/d/JSON-Tiny>
195
196       •   Search CPAN
197
198           <http://search.cpan.org/dist/JSON-Tiny/>
199

ACKNOWLEDGEMENTS

201       Mojolicious team for its lightweight JSON implementation. This module
202       was adapted from Mojo::JSON because it is robust, minimal, and well
203       tested.  Mojo::JSON's tests were also adapted to a dependency-free
204       design.
205
206       Christian Hansen, whos GitHub Gist
207       <https://gist.github.com/chansen/810296> formed the basis for
208       Mojo::JSON, and subsequently JSON::Tiny.
209
210       Randal Schwartz showed his pure-regexp JSON parser (PerlMonks
211       <http://perlmonks.org/?node_id=995856>) to Los Angeles Perl Mongers
212       (09/2012). He wasn't involved in JSON::Tiny, but exploring alternatives
213       to his solution led to this project.
214

LICENSE AND COPYRIGHT

216       Copyright 2012-2014 David Oswald.
217
218       This program is free software, you can redistribute it and/or modify it
219       under the terms of the Artistic License version 2.0.
220
221       See <http://www.perlfoundation.org/artistic_license_2_0> for more
222       information.
223