NAME
JSON - parse and convert to JSON (JavaScript Object Notation).
SYNOPSIS
use JSON;
$obj = {
id => ["foo", "bar", { aa => 'bb'}],
hoge => 'boge'
};
$js = objToJson($obj);
# this is {"id":["foo","bar",{"aa":"bb"}],"hoge":"boge"}.
$obj = jsonToObj($js);
# the data structure was restored.
# OOP
my $json = new JSON;
$obj = {id => 'foo', method => 'echo', params => ['a','b']};
$js = $json->objToJson($obj);
$obj = $json->jsonToObj($js);
# pretty-printing
$js = $json->objToJson($obj, {pretty => 1, indent => 2});
$json = JSON->new(pretty => 1, delimiter => 0);
$json->objToJson($obj);
TRANSITION PLAN
In the next large update version, JSON and JSONRPC modules are split.
JSON::Parser and JSON::Converter are deleted from JSON dist.
JSON and JSON::PP in JSON dist.
JSON becomes wrapper to JSON::XS and/or JSON::PP.
JSONRPC* and Apache::JSONRPC are deleted from JSON dist.
JSONRPC::Client, JSONRPC::Server and JSONRPC::Procedure in JSON::RPC dist.
Modules in JSON::RPC dist supports JSONRPC protocol v1.1 and 1.0.
DESCRIPTION
This module converts between JSON (JavaScript Object Notation) and Perl data structure into each other. For JSON, See to http://www.crockford.com/JSON/.
METHODS
- new()
- new( %options )
-
returns a JSON object. The object delegates the converting and parsing process to JSON::Converter and JSON::Parser.
my $json = new JSON;
new
can take some options.my $json = new JSON (autoconv => 0, pretty => 1);
Following options are supported:
- autoconv
-
See "AUTOCONVERT" for more info.
- skipinvalid
-
objToJson()
doesdie()
when it encounters any invalid data (for instance, coderefs). Ifskipinvalid
is set with true, the function convets these invalid data into JSON format'snull
. - execcoderef
-
objToJson()
doesdie()
when it encounters any code reference. However, ifexeccoderef
is set with true, executes the coderef and uses returned value. - pretty
-
See "PRETTY PRINTING" for more info.
- indent
-
See "PRETTY PRINTING" for more info.
- delimiter
-
See "PRETTY PRINTING" for more info.
- keysort
-
See "HASH KEY SORT ORDER" for more info.
- convblessed
-
See "BLESSED OBJECT" for more info.
- selfconvert
-
See "BLESSED OBJECT" for more info.
- singlequote
-
See "CONVERT WITH SINGLE QUOTES" for more info.
- objToJson( $object )
- objToJson( $object, $hashref )
-
takes perl data structure (basically, they are scalars, arrayrefs and hashrefs) and returns JSON formated string.
my $obj = [1, 2, {foo => bar}]; my $js = $json->objToJson($obj); # [1,2,{"foo":"bar"}]
By default, returned string is one-line. However, you can get pretty-printed data with
pretty
option. Please see below "PRETTY PRINTING".my $js = $json->objToJson($obj, {pretty => 1, indent => 2}); # [ # 1, # 2, # { # "foo" : "bar" # } # ]
- jsonToObj( $js )
-
takes a JSON formated data and returns a perl data structure.
- autoconv()
- autoconv($bool)
-
This is an accessor to
autoconv
. See "AUTOCONVERT" for more info. - pretty()
- pretty($bool)
-
This is an accessor to
pretty
. It takes true or false. When prrety is true,objToJson()
returns prrety-printed string. See "PRETTY PRINTING" for more info. - indent()
- indent($integer)
-
This is an accessor to
indent
. See "PRETTY PRINTING" for more info. - delimiter()
-
This is an accessor to
delimiter
. See "PRETTY PRINTING" for more info. - unmapping()
- unmapping($bool)
-
This is an accessor to
unmapping
. See "UNMAPPING OPTION" for more info. - keysort()
- keysort($coderef)
-
This is an accessor to
keysort
. See "HASH KEY SORT ORDER" for more info. - convblessed()
- convblessed($bool)
-
This is an accessor to
convblessed
. See "BLESSED OBJECT" for more info. - selfconvert()
- selfconvert($bool)
-
This is an accessor to
selfconvert
. See "BLESSED OBJECT" for more info. - singlequote()
- singlequote($bool)
-
This is an accessor to
singlequote
. See "CONVERT WITH SINGLE QUOTES" for more info.
MAPPING
(JSON) {"param" : []}
( => Perl) {'param' => []};
(JSON) {"param" : {}}
( => Perl) {'param' => {}};
(JSON) {"param" : "string"}
( => Perl) {'param' => 'string'};
JSON {"param" : null}
=> Perl {'param' => bless( {'value' => undef}, 'JSON::NotString' )};
or {'param' => undef}
(JSON) {"param" : true}
( => Perl) {'param' => bless( {'value' => 'true'}, 'JSON::NotString' )};
or {'param' => 1}
(JSON) {"param" : false}
( => Perl) {'param' => bless( {'value' => 'false'}, 'JSON::NotString' )};
or {'param' => 2}
(JSON) {"param" : 0xff}
( => Perl) {'param' => 255};
(JSON) {"param" : 010}
( => Perl) {'param' => 8};
These JSON::NotString objects are overloaded so you don't care about. Since 1.00, "UnMapping option" is added. When that option is set, {"param" : null} will be converted into {'param' => undef}, insted of {'param' => bless( {'value' => undef}, 'JSON::NotString' )}.
Perl's undef
is converted to 'null'.
PRETTY PRINTING
If you'd like your JSON output to be pretty-printed, pass the pretty
parameter to objToJson(). You can affect the indentation (which defaults to 2) by passing the indent
parameter to objToJson().
my $str = $json->objToJson($obj, {pretty => 1, indent => 4});
In addition, you can set some number to delimiter
option. The available numbers are only 0, 1 and 2. In pretty-printing mode, when delimiter
is 1, one space is added after ':' in object keys. If delimiter
is 2, it is ' : ' and 0 is ':' (default is 2). If you give 3 or more to it, the value is taken as 2.
AUTOCONVERT
By default, $JSON::AUTOCONVERT is true.
(Perl) {num => 10.02}
( => JSON) {"num" : 10.02}
it is not {"num" : "10.02"}
.
But set false value with $JSON::AUTOCONVERT:
(Perl) {num => 10.02}
( => JSON) {"num" : "10.02"}
it is not {"num" : 10.02}
.
You can explicitly sepcify:
$obj = {
id => JSON::Number(10.02),
bool1 => JSON::True,
bool2 => JSON::False,
noval => JSON::Null,
};
$json->objToJson($obj);
# {"noval" : null, "bool2" : false, "bool1" : true, "id" : 10.02}
JSON::Number()
returns undef
when an argument invalid format.
UNMAPPING OPTION
By default, $JSON::UnMapping is false and JSON::Parser converts null
, true
, false
into JSON::NotString
objects. You can set true into $JSON::UnMapping to stop the mapping function. In that case, JSON::Parser will convert null
, true
, false
into undef
, 1, 0.
BARE KEY OPTION
You can set a true value into $JSON::BareKey for JSON::Parser to parse bare keys of objects.
local $JSON::BareKey = 1;
$obj = jsonToObj('{foo:"bar"}');
SINGLE QUOTATION OPTION
You can set a true value into $JSON::QuotApos for JSON::Parser to parse any keys and values quoted by single quotations.
local $JSON::QuotApos = 1;
$obj = jsonToObj(q|{"foo":'bar'}|);
$obj = jsonToObj(q|{'foo':'bar'}|);
With $JSON::BareKey:
local $JSON::BareKey = 1;
local $JSON::QuotApos = 1;
$obj = jsonToObj(q|{foo:'bar'}|);
HASH KEY SORT ORDER
By default objToJSON will serialize hashes with their keys in random order. To control the ordering of hash keys, you can provide a standard 'sort' function that will be used to control how hashes are converted.
You can provide either a fully qualified function name or a CODEREF to $JSON::KeySort or $obj->keysort.
If you give any integers (excluded 0), the sort function will work as:
sub { $a cmp $b }
Note that since the sort function is external to the JSON module the magical $a and $b arguments will not be in the same package. In order to gain access to the sorting arguments, you must either:
o use the ($$) prototype (slow)
o Fully qualify $a and $b from the JSON::Converter namespace
See the documentation on sort for more information.
local $JSON::KeySort = 'My::Package::sort_function';
or
local $JSON::KeySort = \&_some_function;
sub sort_function {
$JSON::Converter::a cmp $JSON::Converter::b;
}
or
sub sort_function ($$) {
my ($a, $b) = @_;
$a cmp $b
}
BLESSED OBJECT
By default, JSON::Converter doesn't deal with any blessed object (returns undef
or null
in the JSON format). If you use $JSON::ConvBlessed or convblessed
option, the module can convert most blessed object (hashref or arrayref).
local $JSON::ConvBlessed = 1;
print objToJson($blessed);
This option slows down the converting speed.
If you use $JSON::SelfConvert or selfconvert
option, the module will test for a toJson()
method on the object, and will rely on this method to obtain the converted value of the object.
UTF8
You can set a true value into $JSON::UTF8 for JSON::Parser and JSON::Converter to set UTF8 flag into strings contain utf8.
CONVERT WITH SINGLE QUOTES
You can set a true value into $JSON::SingleQuote for JSON::Converter to quote any keys and values with single quotations.
You want to parse single quoted JSON data, See "SINGLE QUOTATION OPTION".
EXPORT
objToJson
, jsonToObj
.
TODO
Which name is more desirable? JSONRPC or JSON::RPC.
SingleQuote and QuotApos...
SEE ALSO
http://www.crockford.com/JSON/, JSON::Parser, JSON::Converter
If you want the speed and the saving of memory usage, check JSON::Syck.
ACKNOWLEDGEMENTS
I owe most JSONRPC idea to XMLRPC::Lite and SOAP::Lite.
SHIMADA pointed out many problems to me.
Mike Castle <dalgoda[at]ix.netcom.com> suggested better packaging way.
Jeremy Muhlich <jmuhlich[at]bitflood.org> help me escaped character handling in JSON::Parser.
Adam Sussman <adam.sussman[at]ticketmaster.com> suggested the octal and hexadecimal formats as number. Sussman also sent the 'key sort' and 'hex number autoconv' patch and 'HASH KEY SORT ORDER' section.
Tatsuhiko Miyagawa <miyagawa[at]bulknews.net> taught a terrible typo and gave some suggestions.
David Wheeler <david[at]kineticode.com> suggested me supporting pretty-printing and gave a part of "PRETTY PRINTING".
Rusty Phillips <rphillips[at]edats.com> suggested me supporting the query object other than CGI.pm for JSONRPC::Transport::HTTP::CGI.
Felipe Gasper <gasperfm[at]uc.edu> pointed to a problem of JSON::NotString with undef. And show me patches for 'bare key option' & 'single quotation option'.
Yaman Saqqa <abulyomon[at]gmail.com> helped my decision to support the bare key option.
Alden DoRosario <adorosario[at]chitika.com> tought JSON::Conveter::_stringfy (<= 0.992) is very slow.
Brad Baxter sent to 'key sort' patch and thought a bug in JSON.
Jacob and Jay Buffington sent 'blessed object conversion' patch.
Thanks to Peter Edwards, IVAN, and all testers for bug reports.
Yann Kerherve sent 'selfconverter' patch(code, document and test).
Annocpan users comment on JSON pod. See http://annocpan.org/pod/JSON
And Thanks very much to JSON by JSON.org (Douglas Crockford) and JSON-RPC by http://json-rpc.org/
AUTHOR
Makamaka Hannyaharamitu, <makamaka[at]cpan.org>
COPYRIGHT AND LICENSE
Copyright 2005-2007 by Makamaka Hannyaharamitu
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.