Проект OpenNet: MAN JSON (3) Библиотечные вызовы (FreeBSD и Linux)

Интерактивная система просмотра системных руководств (man-ов)

JSON (3)

>> JSON (3) ( Разные man: Библиотечные вызовы )

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

unmapping()

This is an accessor to "unmapping". See ``UNMAPPING OPTION'' 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'.

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.

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

EXPORT

"objToJson", "jsonToObj".

TODO

"JSONRPC::Transport::HTTP::Daemon" in JSON 1.00 (The code has be actually written in JSONRPC::Transport::HTTP.)

Shall I support not only {``foo'' : ``bar''} but {foo : ``bar''} or {'foo' : 'bar'} also?

Which name is more desirable? JSONRPC or JSON::RPC.

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.

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

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.

And Thanks very much to JSON by JSON.org (Douglas Crockford) and JSON-RPC by http://json-rpc.org/