JSON(3pm)

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

NAME

6       JSON - parse and convert to JSON (JavaScript Object Notation).
7

SYNOPSIS

9        use JSON;
10
11        $obj = {
12           id   => ["foo", "bar", { aa => 'bb'}],
13           hoge => 'boge'
14        };
15
16        $js  = objToJson($obj);
17        # this is {"id":["foo","bar",{"aa":"bb"}],"hoge":"boge"}.
18        $obj = jsonToObj($js);
19        # the data structure was restored.
20
21        # OOP
22
23        my $json = new JSON;
24
25        $obj = {id => 'foo', method => 'echo', params => ['a','b']};
26        $js  = $json->objToJson($obj);
27        $obj = $json->jsonToObj($js);
28
29        # pretty-printing
30        $js = $json->objToJson($obj, {pretty => 1, indent => 2});
31
32        $json = JSON->new(pretty => 1, delimiter => 0);
33        $json->objToJson($obj);
34

TRANSITION PLAN

36       In the next large update version, JSON and JSONRPC modules are split.
37
38         JSON::Parser and JSON::Converter are deleted from JSON dist.
39         JSON and JSON::PP in JSON dist.
40
41         JSON becomes wrapper to JSON::XS and/or JSON::PP.
42
43         JSONRPC* and Apache::JSONRPC are deleted from JSON dist.
44         JSONRPC::Client, JSONRPC::Server and JSONRPC::Procedure in JSON::RPC dist.
45
46         Modules in JSON::RPC dist supports JSONRPC protocol v1.1 and 1.0.
47

DESCRIPTION

49       This module converts between JSON (JavaScript Object Notation) and Perl
50       data structure into each other.  For JSON, See to http://www.crock‐
51       ford.com/JSON/.
52

METHODS

54       new()
55       new( %options )
56           returns a JSON object. The object delegates the converting and
57           parsing process to JSON::Converter and JSON::Parser.
58
59            my $json = new JSON;
60
61           "new" can take some options.
62
63            my $json = new JSON (autoconv => 0, pretty => 1);
64
65           Following options are supported:
66
67           autoconv
68               See "AUTOCONVERT" for more info.
69
70           skipinvalid
71               "objToJson()" does "die()" when it encounters any invalid data
72               (for instance, coderefs). If "skipinvalid" is set with true,
73               the function convets these invalid data into JSON format's
74               "null".
75
76           execcoderef
77               "objToJson()" does "die()" when it encounters any code refer‐
78               ence.  However, if "execcoderef" is set with true, executes the
79               coderef and uses returned value.
80
81           pretty
82               See "PRETTY PRINTING" for more info.
83
84           indent
85               See "PRETTY PRINTING" for more info.
86
87           delimiter
88               See "PRETTY PRINTING" for more info.
89
90           keysort
91               See "HASH KEY SORT ORDER" for more info.
92
93           convblessed
94               See "BLESSED OBJECT" for more info.
95
96           selfconvert
97               See "BLESSED OBJECT" for more info.
98
99           singlequote
100               See "CONVERT WITH SINGLE QUOTES" for more info.
101
102           quotapos
103               See "SINGLE QUOTATION OPTION".
104
105       objToJson( $object )
106       objToJson( $object, $hashref )
107           takes perl data structure (basically, they are scalars, arrayrefs
108           and hashrefs) and returns JSON formated string.
109
110            my $obj = [1, 2, {foo => bar}];
111            my $js  = $json->objToJson($obj);
112            # [1,2,{"foo":"bar"}]
113
114           By default, returned string is one-line. However, you can get
115           pretty-printed data with "pretty" option. Please see below "PRETTY
116           PRINTING".
117
118            my $js  = $json->objToJson($obj, {pretty => 1, indent => 2});
119            # [
120            #   1,
121            #   2,
122            #   {
123            #     "foo" : "bar"
124            #   }
125            # ]
126
127       jsonToObj( $js )
128           takes a JSON formated data and returns a perl data structure.
129
130       autoconv()
131       autoconv($bool)
132           This is an accessor to "autoconv". See "AUTOCONVERT" for more info.
133
134       pretty()
135       pretty($bool)
136           This is an accessor to "pretty". It takes true or false.  When
137           prrety is true, "objToJson()" returns prrety-printed string.  See
138           "PRETTY PRINTING" for more info.
139
140       indent()
141       indent($integer)
142           This is an accessor to "indent".  See "PRETTY PRINTING" for more
143           info.
144
145       delimiter()
146           This is an accessor to "delimiter".  See "PRETTY PRINTING" for more
147           info.
148
149       unmapping()
150       unmapping($bool)
151           This is an accessor to "unmapping".  See "UNMAPPING OPTION" for
152           more info.
153
154       keysort()
155       keysort($coderef)
156           This is an accessor to "keysort".  See "HASH KEY SORT ORDER" for
157           more info.
158
159       convblessed()
160       convblessed($bool)
161           This is an accessor to "convblessed".  See "BLESSED OBJECT" for
162           more info.
163
164       selfconvert()
165       selfconvert($bool)
166           This is an accessor to "selfconvert".  See "BLESSED OBJECT" for
167           more info.
168
169       singlequote()
170       singlequote($bool)
171           This is an accessor to "singlequote".  See "CONVERT WITH SINGLE
172           QUOTES" for more info.
173

MAPPING

175        (JSON) {"param" : []}
176        ( => Perl) {'param' => []};
177
178        (JSON) {"param" : {}}
179        ( => Perl) {'param' => {}};
180
181        (JSON) {"param" : "string"}
182        ( => Perl) {'param' => 'string'};
183
184        JSON {"param" : null}
185         => Perl {'param' => bless( {'value' => undef}, 'JSON::NotString' )};
186         or {'param' => undef}
187
188        (JSON) {"param" : true}
189        ( => Perl) {'param' => bless( {'value' => 'true'}, 'JSON::NotString' )};
190         or {'param' => 1}
191
192        (JSON) {"param" : false}
193        ( => Perl) {'param' => bless( {'value' => 'false'}, 'JSON::NotString' )};
194         or {'param' => 2}
195
196        (JSON) {"param" : 0xff}
197        ( => Perl) {'param' => 255};
198
199        (JSON) {"param" : 010}
200        ( => Perl) {'param' => 8};
201
202       These JSON::NotString objects are overloaded so you don't care about.
203       Since 1.00, "UnMapping option" is added. When that option is set,
204       {"param" : null} will be converted into {'param' => undef}, insted of
205       {'param' => bless( {'value' => undef}, 'JSON::NotString' )}.
206
207       Perl's "undef" is converted to 'null'.
208

PRETTY PRINTING

210       If you'd like your JSON output to be pretty-printed, pass the "pretty"
211       parameter to objToJson(). You can affect the indentation (which
212       defaults to 2) by passing the "indent" parameter to objToJson().
213
214         my $str = $json->objToJson($obj, {pretty => 1, indent => 4});
215
216       In addition, you can set some number to "delimiter" option.  The avail‐
217       able numbers are only 0, 1 and 2.  In pretty-printing mode, when
218       "delimiter" is 1, one space is added after ':' in object keys. If
219       "delimiter" is 2, it is ' : ' and 0 is ':' (default is 2). If you give
220       3 or more to it, the value is taken as 2.
221

AUTOCONVERT

223       By default, $JSON::AUTOCONVERT is true.
224
225        (Perl) {num => 10.02}
226        ( => JSON) {"num" : 10.02}
227
228       it is not "{"num" : "10.02"}".
229
230       But set false value with $JSON::AUTOCONVERT:
231
232        (Perl) {num => 10.02}
233        ( => JSON) {"num" : "10.02"}
234
235       it is not "{"num" : 10.02}".
236
237       You can explicitly sepcify:
238
239        $obj = {
240           id     => JSON::Number(10.02),
241           bool1  => JSON::True,
242           bool2  => JSON::False,
243           noval  => JSON::Null,
244        };
245
246        $json->objToJson($obj);
247        # {"noval" : null, "bool2" : false, "bool1" : true, "id" : 10.02}
248
249       "JSON::Number()" returns "undef" when an argument invalid format.
250

UNMAPPING OPTION

252       By default, $JSON::UnMapping is false and JSON::Parser converts "null",
253       "true", "false" into "JSON::NotString" objects.  You can set true into
254       $JSON::UnMapping to stop the mapping function.  In that case,
255       JSON::Parser will convert "null", "true", "false" into "undef", 1, 0.
256

BARE KEY OPTION

258       You can set a true value into $JSON::BareKey for JSON::Parser to parse
259       bare keys of objects.
260
261        local $JSON::BareKey = 1;
262        $obj = jsonToObj('{foo:"bar"}');
263

SINGLE QUOTATION OPTION

265       You can set a true value into $JSON::QuotApos for JSON::Parser to parse
266       any keys and values quoted by single quotations.
267
268        local $JSON::QuotApos = 1;
269        $obj = jsonToObj(q⎪{"foo":'bar'}⎪);
270        $obj = jsonToObj(q⎪{'foo':'bar'}⎪);
271
272       With $JSON::BareKey:
273
274        local $JSON::BareKey  = 1;
275        local $JSON::QuotApos = 1;
276        $obj = jsonToObj(q⎪{foo:'bar'}⎪);
277

HASH KEY SORT ORDER

279       By default objToJSON will serialize hashes with their keys in random
280       order.  To control the ordering of hash keys, you can provide a stan‐
281       dard 'sort' function that will be used to control how hashes are con‐
282       verted.
283
284       You can provide either a fully qualified function name or a CODEREF to
285       $JSON::KeySort or $obj->keysort.
286
287       If you give any integers (excluded 0), the sort function will work as:
288
289        sub { $a cmp $b }
290
291       Note that since the sort function is external to the JSON module the
292       magical $a and $b arguments will not be in the same package.  In order
293       to gain access to the sorting arguments, you must either:
294
295         o use the ($$) prototype (slow)
296         o Fully qualify $a and $b from the JSON::Converter namespace
297
298       See the documentation on sort for more information.
299
300        local $JSON::KeySort = 'My::Package::sort_function';
301
302        or
303
304        local $JSON::KeySort = \&_some_function;
305
306        sub sort_function {
307           $JSON::Converter::a cmp $JSON::Converter::b;
308        }
309
310        or
311
312        sub sort_function ($$) {
313           my ($a, $b) = @_;
314
315           $a cmp $b
316        }
317

BLESSED OBJECT

319       By default, JSON::Converter doesn't deal with any blessed object
320       (returns "undef" or "null" in the JSON format).  If you use $JSON::Con‐
321       vBlessed or "convblessed" option, the module can convert most blessed
322       object (hashref or arrayref).
323
324         local $JSON::ConvBlessed = 1;
325         print objToJson($blessed);
326
327       This option slows down the converting speed.
328
329       If you use $JSON::SelfConvert or "selfconvert" option, the module will
330       test for a "toJson()" method on the object, and will rely on this
331       method to obtain the converted value of the object.
332

UTF8

334       You can set a true value into $JSON::UTF8 for JSON::Parser and
335       JSON::Converter to set UTF8 flag into strings contain utf8.
336

CONVERT WITH SINGLE QUOTES

338       You can set a true value into $JSON::SingleQuote for JSON::Converter to
339       quote any keys and values with single quotations.
340
341       You want to parse single quoted JSON data, See "SINGLE QUOTATION
342       OPTION".
343

EXPORT

345       "objToJson", "jsonToObj".
346

TODO

348       Which name is more desirable? JSONRPC or JSON::RPC.
349
350       SingleQuote and QuotApos...
351

ACKNOWLEDGEMENTS

358       I owe most JSONRPC idea to XMLRPC::Lite and SOAP::Lite.
359
360       SHIMADA pointed out many problems to me.
361
362       Mike Castle <dalgoda[at]ix.netcom.com> suggested better packaging way.
363
364       Jeremy Muhlich <jmuhlich[at]bitflood.org> help me escaped character
365       handling in JSON::Parser.
366
367       Adam Sussman <adam.sussman[at]ticketmaster.com> suggested the octal and
368       hexadecimal formats as number.  Sussman also sent the 'key sort' and
369       'hex number autoconv' patch and 'HASH KEY SORT ORDER' section.
370
371       Tatsuhiko Miyagawa <miyagawa[at]bulknews.net> taught a terrible typo
372       and gave some suggestions.
373
374       David Wheeler <david[at]kineticode.com> suggested me supporting pretty-
375       printing and gave a part of "PRETTY PRINTING".
376
377       Rusty Phillips <rphillips[at]edats.com> suggested me supporting the
378       query object other than CGI.pm for JSONRPC::Transport::HTTP::CGI.
379
380       Felipe Gasper <gasperfm[at]uc.edu> pointed to a problem of JSON::Not‐
381       String with undef.  And show me patches for 'bare key option' & 'single
382       quotation option'.
383
384       Yaman Saqqa <abulyomon[at]gmail.com> helped my decision to support the
385       bare key option.
386
387       Alden DoRosario <adorosario[at]chitika.com> tought JSON::Con‐
388       veter::_stringfy (<= 0.992) is very slow.
389
390       Brad Baxter sent to 'key sort' patch and thought a bug in JSON.
391
392       Jacob and Jay Buffington sent 'blessed object conversion' patch.
393
394       Thanks to Peter Edwards, IVAN, and all testers for bug reports.
395
396       Yann Kerherve sent 'selfconverter' patch(code, document and test).
397
398       Annocpan users comment on JSON pod. See http://annocpan.org/pod/JSON
399
400       And Thanks very much to JSON by JSON.org (Douglas Crockford) and JSON-
401       RPC by http://json-rpc.org/
402

AUTHOR

404       Makamaka Hannyaharamitu, <makamaka[at]cpan.org>
405

COPYRIGHT AND LICENSE

407       Copyright 2005-2007 by Makamaka Hannyaharamitu
408
409       This library is free software; you can redistribute it and/or modify it
410       under the same terms as Perl itself.
411
412
413
414perl v5.8.8                       2007-05-10                           JSON(3)