r55098 - in /branches/upstream/libjson-perl/current: Changes META.yml README lib/JSON.pm lib/JSON/PP.pm
angelabad-guest at users.alioth.debian.org
angelabad-guest at users.alioth.debian.org
Tue Mar 30 09:35:29 UTC 2010
Author: angelabad-guest
Date: Tue Mar 30 09:35:19 2010
New Revision: 55098
URL: http://svn.debian.org/wsvn/pkg-perl/?sc=1&rev=55098
Log:
[svn-upgrade] Integrating new upstream version, libjson-perl (2.19)
Modified:
branches/upstream/libjson-perl/current/Changes
branches/upstream/libjson-perl/current/META.yml
branches/upstream/libjson-perl/current/README
branches/upstream/libjson-perl/current/lib/JSON.pm
branches/upstream/libjson-perl/current/lib/JSON/PP.pm
Modified: branches/upstream/libjson-perl/current/Changes
URL: http://svn.debian.org/wsvn/pkg-perl/branches/upstream/libjson-perl/current/Changes?rev=55098&op=diff
==============================================================================
--- branches/upstream/libjson-perl/current/Changes (original)
+++ branches/upstream/libjson-perl/current/Changes Tue Mar 30 09:35:19 2010
@@ -15,6 +15,13 @@
!! Since 2.16, PP's relaxed option caused an infinite loop in some condition.
!! Recommend to update old versions.
+
+2.19 Tue Mar 30 13:40:24 2010
+ [JSON]
+ - fixed typo (rt#53535 by Angel Abad)
+ - added a recommendation
+ refering to (en|de)code_json to pod (suggested by tokuhirom)
+ - added 'HOW DO I DECODE A DATA FROM OUTER AND ENCODE TO OUTER' to pod.
2.18 Tue Mar 23 15:18:10 2010
[JSON]
Modified: branches/upstream/libjson-perl/current/META.yml
URL: http://svn.debian.org/wsvn/pkg-perl/branches/upstream/libjson-perl/current/META.yml?rev=55098&op=diff
==============================================================================
--- branches/upstream/libjson-perl/current/META.yml (original)
+++ branches/upstream/libjson-perl/current/META.yml Tue Mar 30 09:35:19 2010
@@ -1,6 +1,6 @@
--- #YAML:1.0
name: JSON
-version: 2.18
+version: 2.19
abstract: JSON (JavaScript Object Notation) encoder/decoder
author:
- Makamaka Hannyaharamitu, E<lt>makamaka[at]cpan.orgE<gt>
Modified: branches/upstream/libjson-perl/current/README
URL: http://svn.debian.org/wsvn/pkg-perl/branches/upstream/libjson-perl/current/README?rev=55098&op=diff
==============================================================================
--- branches/upstream/libjson-perl/current/README (original)
+++ branches/upstream/libjson-perl/current/README Tue Mar 30 09:35:19 2010
@@ -1,4 +1,4 @@
-JSON version 2.18
+JSON version 2.19
=================
INSTALLATION
@@ -16,33 +16,36 @@
SYNOPSIS
use JSON; # imports encode_json, decode_json, to_json and from_json.
- $json_text = to_json($perl_scalar);
- $perl_scalar = from_json($json_text);
+ # simple and fast interfaces (expect/generate UTF-8)
- # option-acceptable
- $json_text = to_json($perl_scalar, {ascii => 1});
- $perl_scalar = from_json($json_text, {utf8 => 1});
-
- # OOP
- $json = new JSON;
-
- $json_text = $json->encode($perl_scalar);
- $perl_scalar = $json->decode($json_text);
-
- # pretty-printing
- $json_text = $json->pretty->encode($perl_scalar);
-
- # simple interface
$utf8_encoded_json_text = encode_json $perl_hash_or_arrayref;
$perl_hash_or_arrayref = decode_json $utf8_encoded_json_text;
+ # OO-interface
+
+ $json = JSON->new->allow_nonref;
+
+ $json_text = $json->encode( $perl_scalar );
+ $perl_scalar = $json->decode( $json_text );
+
+ $pretty_printed = $json->pretty->encode( $perl_scalar ); # pretty-printing
+
# If you want to use PP only support features, call with '-support_by_pp'
- # When XS unsupported feature is enable, using PP de/encode.
+ # When XS unsupported feature is enable, using PP (de|en)code instead of XS ones.
use JSON -support_by_pp;
-
+
+ # option-acceptable interfaces (expect/generate UNICODE by default)
+
+ $json_text = to_json( $perl_scalar, { ascii => 1, pretty => 1 } );
+ $perl_scalar = from_json( $json_text, { utf8 => 1 } );
+
+ # Between (en|de)code_json and (to|from)_json, if you want to write
+ # a code which communicates to an outer world (encoded in UTF-8),
+ # recommend to use (en|de)code_json.
+
VERSION
- 2.18
+ 2.19
This version is compatible with JSON::XS 2.27 and later.
@@ -116,11 +119,11 @@
See to "FEATURES" in JSON::XS and "FEATURES" in JSON::PP.
* fast
- This module returns a JSON::XS object itself if avaliable. Compared
+ This module returns a JSON::XS object itself if available. Compared
to other JSON modules and other serialisers such as Storable,
JSON::XS usually compares favourably in terms of speed, too.
- If not avaliable, "JSON" returns a JSON::PP object instead of
+ If not available, "JSON" returns a JSON::PP object instead of
JSON::XS and it is very slow as pure-Perl.
* simple to use
@@ -139,49 +142,6 @@
Some documents are copied and modified from "FUNCTIONAL INTERFACE" in
JSON::XS. "to_json" and "from_json" are additional functions.
- to_json
- $json_text = to_json($perl_scalar)
-
- Converts the given Perl data structure to a json string.
-
- This function call is functionally identical to:
-
- $json_text = JSON->new->encode($perl_scalar)
-
- Takes a hash reference as the second.
-
- $json_text = to_json($perl_scalar, $flag_hashref)
-
- So,
-
- $json_text = encode_json($perl_scalar, {utf8 => 1, pretty => 1})
-
- equivalent to:
-
- $json_text = JSON->new->utf8(1)->pretty(1)->encode($perl_scalar)
-
- from_json
- $perl_scalar = from_json($json_text)
-
- The opposite of "to_json": expects a json string and tries to parse it,
- returning the resulting reference.
-
- This function call is functionally identical to:
-
- $perl_scalar = JSON->decode($json_text)
-
- Takes a hash reference as the second.
-
- $perl_scalar = from_json($json_text, $flag_hashref)
-
- So,
-
- $perl_scalar = from_json($json_text, {utf8 => 1})
-
- equivalent to:
-
- $perl_scalar = JSON->new->utf8(1)->decode($json_text)
-
encode_json
$json_text = encode_json $perl_scalar
@@ -203,6 +163,57 @@
$perl_scalar = JSON->new->utf8->decode($json_text)
+ to_json
+ $json_text = to_json($perl_scalar)
+
+ Converts the given Perl data structure to a json string.
+
+ This function call is functionally identical to:
+
+ $json_text = JSON->new->encode($perl_scalar)
+
+ Takes a hash reference as the second.
+
+ $json_text = to_json($perl_scalar, $flag_hashref)
+
+ So,
+
+ $json_text = encode_json($perl_scalar, {utf8 => 1, pretty => 1})
+
+ equivalent to:
+
+ $json_text = JSON->new->utf8(1)->pretty(1)->encode($perl_scalar)
+
+ If you want to write a modern perl code which communicates to outer
+ world, you should use "encode_json" (supposed that JSON data are encoded
+ in UTF-8).
+
+ from_json
+ $perl_scalar = from_json($json_text)
+
+ The opposite of "to_json": expects a json string and tries to parse it,
+ returning the resulting reference.
+
+ This function call is functionally identical to:
+
+ $perl_scalar = JSON->decode($json_text)
+
+ Takes a hash reference as the second.
+
+ $perl_scalar = from_json($json_text, $flag_hashref)
+
+ So,
+
+ $perl_scalar = from_json($json_text, {utf8 => 1})
+
+ equivalent to:
+
+ $perl_scalar = JSON->new->utf8(1)->decode($json_text)
+
+ If you want to write a modern perl code which communicates to outer
+ world, you should use "decode_json" (supposed that JSON data are encoded
+ in UTF-8).
+
JSON::is_bool
$is_boolean = JSON::is_bool($scalar)
@@ -223,6 +234,67 @@
See MAPPING, below, for more information on how JSON values are mapped
to Perl.
+
+HOW DO I DECODE A DATA FROM OUTER AND ENCODE TO OUTER
+ This section supposes that your perl vresion is 5.8 or later.
+
+ If you know a JSON text from an outer world - a network, a file content,
+ and so on, is encoded in UTF-8, you should use "decode_json" or "JSON"
+ module object with "utf8" enable. And the decoded data contains UNICODE
+ characters.
+
+ # from network
+ my $json = JSON->new->utf8;
+ my $json_text = CGI->new->param( 'json_data' );
+ my $perl_scalar = $json->decode( $json_text );
+
+ # from file content
+ local $/;
+ open( my $fh, '<', 'json.data' );
+ $json_text = <$fh>;
+ $perl_scalar = decode_json( $json_text );
+
+ If your data is not encoded in UTF-8, firstly you should "decode" it.
+
+ use Encode;
+ local $/;
+ open( my $fh, '<', 'json.data' ); # ex. this data is encoded in cp932.
+ $json_text = decode( 'cp932', <$fh> ); # UNICODE
+
+ # or you can write the below code.
+ #
+ # open( my $fh, '<:encoding(cp932)', 'json.data' );
+ # $json_text = <$fh>;
+
+ In this case, $json_text is UNICODE string. So you can not use
+ "decode_json" nor "JSON" module object with "utf8" enable. Instead of
+ them, you use "JSON" module object with "utf8" disable or "from_json".
+
+ $perl_scalar = $json->utf8(0)->decode( $json_text );
+ # or
+ $perl_scalar = from_json( $json_text );
+
+ And now, you want to convert your $perl_scalar into JSON data and send
+ it to an outer world - a network or a file content, and so on.
+
+ If your data contains UNICODE strings and you want the converted data to
+ be encoded in UTF-8, you should use "encode_json" or "JSON" module
+ object with "utf8" enable.
+
+ print encode_json( $perl_scalar ); # to a network? file? or display?
+ # or
+ print $json->utf8->encode( $perl_scalar );
+
+ And if $perl_scalar does not contain UNICODE, then your characters are
+ latin1 for perl. So you can not use "encode_json" nor "JSON" module
+ object with "utf8" enable. Instead of them, you use "JSON" module object
+ with "utf8" disable or "to_json".
+
+ $outer_json_text = $json->utf8(0)->encode( $perl_scalar );
+ # or
+ $outer_json_text = to_json( $perl_scalar );
+
+ See to Encode, perluniintro.
COMMON OBJECT-ORIENTED INTERFACE
new
@@ -726,7 +798,7 @@
$boolean = $json->property('utf8');
=> 1
- Sets the propery with a given boolean value.
+ Sets the property with a given boolean value.
$json = $json->property($property_name => $boolean);
@@ -1190,7 +1262,7 @@
Global variables are no longer available.
"JSON" class variables - $JSON::AUTOCONVERT, $JSON::BareKey, etc...
- - are not avaliable any longer. Instead, various features can be
+ - are not available any longer. Instead, various features can be
used through object methods.
Package JSON::Converter and JSON::Parser are deleted.
Modified: branches/upstream/libjson-perl/current/lib/JSON.pm
URL: http://svn.debian.org/wsvn/pkg-perl/branches/upstream/libjson-perl/current/lib/JSON.pm?rev=55098&op=diff
==============================================================================
--- branches/upstream/libjson-perl/current/lib/JSON.pm (original)
+++ branches/upstream/libjson-perl/current/lib/JSON.pm Tue Mar 30 09:35:19 2010
@@ -7,7 +7,7 @@
@JSON::EXPORT = qw(from_json to_json jsonToObj objToJson encode_json decode_json);
BEGIN {
- $JSON::VERSION = '2.18';
+ $JSON::VERSION = '2.19';
$JSON::DEBUG = 0 unless (defined $JSON::DEBUG);
}
@@ -578,36 +578,37 @@
use JSON; # imports encode_json, decode_json, to_json and from_json.
- $json_text = to_json($perl_scalar);
- $perl_scalar = from_json($json_text);
+ # simple and fast interfaces (expect/generate UTF-8)
- # option-acceptable
- $json_text = to_json($perl_scalar, {ascii => 1});
- $perl_scalar = from_json($json_text, {utf8 => 1});
-
- # OOP
- $json = new JSON;
-
- $json_text = $json->encode($perl_scalar);
- $perl_scalar = $json->decode($json_text);
-
- # pretty-printing
- $json_text = $json->pretty->encode($perl_scalar);
-
- # simple interface
$utf8_encoded_json_text = encode_json $perl_hash_or_arrayref;
$perl_hash_or_arrayref = decode_json $utf8_encoded_json_text;
+ # OO-interface
+
+ $json = JSON->new->allow_nonref;
+
+ $json_text = $json->encode( $perl_scalar );
+ $perl_scalar = $json->decode( $json_text );
+
+ $pretty_printed = $json->pretty->encode( $perl_scalar ); # pretty-printing
# If you want to use PP only support features, call with '-support_by_pp'
- # When XS unsupported feature is enable, using PP de/encode.
+ # When XS unsupported feature is enable, using PP (de|en)code instead of XS ones.
use JSON -support_by_pp;
-
-
+
+ # option-acceptable interfaces (expect/generate UNICODE by default)
+
+ $json_text = to_json( $perl_scalar, { ascii => 1, pretty => 1 } );
+ $perl_scalar = from_json( $json_text, { utf8 => 1 } );
+
+ # Between (en|de)code_json and (to|from)_json, if you want to write
+ # a code which communicates to an outer world (encoded in UTF-8),
+ # recommend to use (en|de)code_json.
+
=head1 VERSION
- 2.18
+ 2.19
This version is compatible with JSON::XS B<2.27> and later.
@@ -686,11 +687,11 @@
=item * fast
-This module returns a JSON::XS object itself if avaliable.
+This module returns a JSON::XS object itself if available.
Compared to other JSON modules and other serialisers such as Storable,
JSON::XS usually compares favourably in terms of speed, too.
-If not avaliable, C<JSON> returns a JSON::PP object instead of JSON::XS and
+If not available, C<JSON> returns a JSON::PP object instead of JSON::XS and
it is very slow as pure-Perl.
=item * simple to use
@@ -713,52 +714,6 @@
Some documents are copied and modified from L<JSON::XS/FUNCTIONAL INTERFACE>.
C<to_json> and C<from_json> are additional functions.
-=head2 to_json
-
- $json_text = to_json($perl_scalar)
-
-Converts the given Perl data structure to a json string.
-
-This function call is functionally identical to:
-
- $json_text = JSON->new->encode($perl_scalar)
-
-Takes a hash reference as the second.
-
- $json_text = to_json($perl_scalar, $flag_hashref)
-
-So,
-
- $json_text = encode_json($perl_scalar, {utf8 => 1, pretty => 1})
-
-equivalent to:
-
- $json_text = JSON->new->utf8(1)->pretty(1)->encode($perl_scalar)
-
-
-=head2 from_json
-
- $perl_scalar = from_json($json_text)
-
-The opposite of C<to_json>: expects a json string and tries
-to parse it, returning the resulting reference.
-
-This function call is functionally identical to:
-
- $perl_scalar = JSON->decode($json_text)
-
-Takes a hash reference as the second.
-
- $perl_scalar = from_json($json_text, $flag_hashref)
-
-So,
-
- $perl_scalar = from_json($json_text, {utf8 => 1})
-
-equivalent to:
-
- $perl_scalar = JSON->new->utf8(1)->decode($json_text)
-
=head2 encode_json
$json_text = encode_json $perl_scalar
@@ -781,6 +736,58 @@
$perl_scalar = JSON->new->utf8->decode($json_text)
+
+=head2 to_json
+
+ $json_text = to_json($perl_scalar)
+
+Converts the given Perl data structure to a json string.
+
+This function call is functionally identical to:
+
+ $json_text = JSON->new->encode($perl_scalar)
+
+Takes a hash reference as the second.
+
+ $json_text = to_json($perl_scalar, $flag_hashref)
+
+So,
+
+ $json_text = encode_json($perl_scalar, {utf8 => 1, pretty => 1})
+
+equivalent to:
+
+ $json_text = JSON->new->utf8(1)->pretty(1)->encode($perl_scalar)
+
+If you want to write a modern perl code which communicates to outer world,
+you should use C<encode_json> (supposed that JSON data are encoded in UTF-8).
+
+=head2 from_json
+
+ $perl_scalar = from_json($json_text)
+
+The opposite of C<to_json>: expects a json string and tries
+to parse it, returning the resulting reference.
+
+This function call is functionally identical to:
+
+ $perl_scalar = JSON->decode($json_text)
+
+Takes a hash reference as the second.
+
+ $perl_scalar = from_json($json_text, $flag_hashref)
+
+So,
+
+ $perl_scalar = from_json($json_text, {utf8 => 1})
+
+equivalent to:
+
+ $perl_scalar = JSON->new->utf8(1)->decode($json_text)
+
+If you want to write a modern perl code which communicates to outer world,
+you should use C<decode_json> (supposed that JSON data are encoded in UTF-8).
+
=head2 JSON::is_bool
$is_boolean = JSON::is_bool($scalar)
@@ -806,8 +813,67 @@
See L<MAPPING>, below, for more information on how JSON values are mapped to
Perl.
+=head1 HOW DO I DECODE A DATA FROM OUTER AND ENCODE TO OUTER
+
+This section supposes that your perl vresion is 5.8 or later.
+
+If you know a JSON text from an outer world - a network, a file content, and so on,
+is encoded in UTF-8, you should use C<decode_json> or C<JSON> module object
+with C<utf8> enable. And the decoded data contains UNICODE characters.
+
+ # from network
+ my $json = JSON->new->utf8;
+ my $json_text = CGI->new->param( 'json_data' );
+ my $perl_scalar = $json->decode( $json_text );
+
+ # from file content
+ local $/;
+ open( my $fh, '<', 'json.data' );
+ $json_text = <$fh>;
+ $perl_scalar = decode_json( $json_text );
+
+If your data is not encoded in UTF-8, firstly you should C<decode> it.
+
+ use Encode;
+ local $/;
+ open( my $fh, '<', 'json.data' ); # ex. this data is encoded in cp932.
+ $json_text = decode( 'cp932', <$fh> ); # UNICODE
+
+ # or you can write the below code.
+ #
+ # open( my $fh, '<:encoding(cp932)', 'json.data' );
+ # $json_text = <$fh>;
+
+In this case, C<$json_text> is UNICODE string.
+So you can B<not> use C<decode_json> nor C<JSON> module object with C<utf8> enable.
+Instead of them, you use C<JSON> module object with C<utf8> disable or C<from_json>.
+
+ $perl_scalar = $json->utf8(0)->decode( $json_text );
+ # or
+ $perl_scalar = from_json( $json_text );
+
+And now, you want to convert your C<$perl_scalar> into JSON data and
+send it to an outer world - a network or a file content, and so on.
+
+If your data contains UNICODE strings and you want the converted data to be encoded
+in UTF-8, you should use C<encode_json> or C<JSON> module object with C<utf8> enable.
+
+ print encode_json( $perl_scalar ); # to a network? file? or display?
+ # or
+ print $json->utf8->encode( $perl_scalar );
+
+And if C<$perl_scalar> does not contain UNICODE, then your characters are latin1 for perl.
+So you can B<not> use C<encode_json> nor C<JSON> module object with C<utf8> enable.
+Instead of them, you use C<JSON> module object with C<utf8> disable or C<to_json>.
+
+ $outer_json_text = $json->utf8(0)->encode( $perl_scalar );
+ # or
+ $outer_json_text = to_json( $perl_scalar );
+
+See to L<Encode>, L<perluniintro>.
+
+
=head1 COMMON OBJECT-ORIENTED INTERFACE
-
=head2 new
@@ -1343,7 +1409,7 @@
$boolean = $json->property('utf8');
=> 1
-Sets the propery with a given boolean value.
+Sets the property with a given boolean value.
$json = $json->property($property_name => $boolean);
@@ -1860,7 +1926,7 @@
=item Global variables are no longer available.
C<JSON> class variables - C<$JSON::AUTOCONVERT>, C<$JSON::BareKey>, etc...
-- are not avaliable any longer.
+- are not available any longer.
Instead, various features can be used through object methods.
Modified: branches/upstream/libjson-perl/current/lib/JSON/PP.pm
URL: http://svn.debian.org/wsvn/pkg-perl/branches/upstream/libjson-perl/current/lib/JSON/PP.pm?rev=55098&op=diff
==============================================================================
--- branches/upstream/libjson-perl/current/lib/JSON/PP.pm (original)
+++ branches/upstream/libjson-perl/current/lib/JSON/PP.pm Tue Mar 30 09:35:19 2010
@@ -11,7 +11,7 @@
use B ();
#use Devel::Peek;
-$JSON::PP::VERSION = '2.27001';
+$JSON::PP::VERSION = '2.27002';
@JSON::PP::EXPORT = qw(encode_json decode_json from_json to_json);
@@ -1706,7 +1706,7 @@
$enabled = $json->get_indent
-The default indent space lenght is three.
+The default indent space length is three.
You can use C<indent_length> to change the length.
=head2 space_before
More information about the Pkg-perl-cvs-commits
mailing list