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);

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() does die() when it encounters any invalid data (for instance, coderefs). If skipinvalid is set with true, the function convets these invalid data into JSON format's null.

execcoderef

objToJson() does die() when it encounters any code reference. However, if execcoderef is set with true, executes the coderef and uses returned value.

pretty

See "PRETY PRINTING" for more info.

indent

See "PRETY PRINTING" for more info.

delimiter

See "PRETY PRINTING" 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 "PRETY 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 "PRETY PRINTING" for more info.

indent()

indent($integer)

This is an accessor to indent. See "PRETY PRINTING" for more info.

delimiter()

This is an accessor to delimiter. See "PRETY PRINTING" 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' )};
 
 (JSON) {"param" : true}
 ( => Perl) {'param' => bless( {'value' => 'true'}, 'JSON::NotString' )};
 
 (JSON) {"param" : false}
 ( => Perl) {'param' => bless( {'value' => 'false'}, 'JSON::NotString' )};
 
 (JSON) {"param" : -1.23}
 ( => Perl) {'param' => bless( {'value' => '-1.23'}, 'JSON::NotString' )};

 (JSON) {"param" : 0xff}
 ( => Perl) {'param' => 255};

 (JSON) {"param" : 010}
 ( => Perl) {'param' => 8};

These JSON::NotString objects are overloaded so you don't care about.

Perl's undef is converted to 'null'.

PRETY 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.

EXPORT

objToJson, jsonToObj.

TODO

JSONRPC::Transport::HTTP::Daemon in JSON 1.00

SEE ALSO

http://www.crockford.com/JSON/, JSON::Parser, JSON::Converter

ACKNOWLEDGEMENTS

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.

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 "PRETY PRINTING".

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 by Makamaka Hannyaharamitu

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm JSON

perl -MCPAN -e shell
install JSON