[ViewVC] Diff of: cvs/JSON-XS/XS.pm

Comparing JSON-XS/XS.pm (file contents):
Revision 1.51 by root, Mon Jul 2 01:12:27 2007 UTC vs.
Revision 1.63 by root, Thu Oct 11 23:07:43 2007 UTC

+=encoding utf-8
 =head1 NAME
 JSON::XS - JSON serialising/deserialising, done correctly and fast
+JSON::XS - 正しくて高速な JSON シリアライザ/デシリアライザ
+           (http://fleur.hio.jp/perldoc/mix/lib/JSON/XS.html)
 =head1 SYNOPSIS
  use JSON::XS;
 package JSON::XS;
 use strict;
-our $VERSION = '1.4';
+our $VERSION = '1.5';
 our @ISA = qw(Exporter);
 our @EXPORT = qw(to_json from_json);
 use Exporter;
 =over 4
 =item $json_text = to_json $perl_scalar
-Converts the given Perl data structure (a simple scalar or a reference to
+Converts the given Perl data structure to a UTF-8 encoded, binary string
-a hash or array) to a UTF-8 encoded, binary string (that is, the string contains
+(that is, the string contains octets only). Croaks on error.
-octets only). Croaks on error.
 This function call is functionally identical to:
    $json_text = JSON::XS->new->utf8->encode ($perl_scalar)
 except being faster.
 =item $perl_scalar = from_json $json_text
-The opposite of C<to_json>: expects an UTF-8 (binary) string and tries to
+The opposite of C<to_json>: expects an UTF-8 (binary) string and tries
-parse that as an UTF-8 encoded JSON text, returning the resulting simple
+to parse that as an UTF-8 encoded JSON text, returning the resulting
-scalar or reference. Croaks on error.
+reference. Croaks on error.
 This function call is functionally identical to:
    $perl_scalar = JSON::XS->new->utf8->decode ($json_text)
 See MAPPING, below, for more information on how JSON values are mapped to
 Perl.
 =back
+=head1 A FEW NOTES ON UNICODE AND PERL
+Since this often leads to confusion, here are a few very clear words on
+how Unicode works in Perl, modulo bugs.
+=over 4
+=item 1. Perl strings can store characters with ordinal values > 255.
+This enables you to store unicode characters as single characters in a
+Perl string - very natural.
+=item 2. Perl does I<not> associate an encoding with your strings.
+Unless you force it to, e.g. when matching it against a regex, or printing
+the scalar to a file, in which case Perl either interprets your string as
+locale-encoded text, octets/binary, or as Unicode, depending on various
+settings. In no case is an encoding stored together with your data, it is
+I<use> that decides encoding, not any magical metadata.
+=item 3. The internal utf-8 flag has no meaning with regards to the
+encoding of your string.
+Just ignore that flag unless you debug a Perl bug, a module written in
+XS or want to dive into the internals of perl. Otherwise it will only
+confuse you, as, despite the name, it says nothing about how your string
+is encoded. You can have unicode strings with that flag set, with that
+flag clear, and you can have binary data with that flag set and that flag
+clear. Other possibilities exist, too.
+If you didn't know about that flag, just the better, pretend it doesn't
+exist.
+=item 4. A "Unicode String" is simply a string where each character can be
+validly interpreted as a Unicode codepoint.
+If you have UTF-8 encoded data, it is no longer a Unicode string, but a
+Unicode string encoded in UTF-8, giving you a binary string.
+=item 5. A string containing "high" (> 255) character values is I<not> a UTF-8 string.
+Its a fact. Learn to live with it.
+=back
+I hope this helps :)
 =head1 OBJECT-ORIENTED INTERFACE
 The object oriented interface lets you configure your own encoding or
 Example, space_before and indent disabled, space_after enabled:
    {"key": "value"}
+=item $json = $json->relaxed ([$enable])
+If C<$enable> is true (or missing), then C<decode> will accept some
+extensions to normal JSON syntax (see below). C<encode> will not be
+affected in anyway. I<Be aware that this option makes you accept invalid
+JSON texts as if they were valid!>. I suggest only to use this option to
+parse application-specific files written by humans (configuration files,
+resource files etc.)
+If C<$enable> is false (the default), then C<decode> will only accept
+valid JSON texts.
+Currently accepted extensions are:
+=over 4
+=item * list items can have an end-comma
+JSON I<separates> array elements and key-value pairs with commas. This
+can be annoying if you write JSON texts manually and want to be able to
+quickly append elements, so this extension accepts comma at the end of
+such items not just between them:
+   [
+      1,
+      2, <- this comma not normally allowed
+   ]
+   {
+      "k1": "v1",
+      "k2": "v2", <- this comma not normally allowed
+   }
+=item * shell-style '#'-comments
+Whenever JSON allows whitespace, shell-style comments are additionally
+allowed. They are terminated by the first carriage-return or line-feed
+character, after which more white-space and comments are allowed.
+  [
+     1, # this comment not allowed in JSON
+        # neither this one...
+  ]
+=back
 =item $json = $json->canonical ([$enable])
 If C<$enable> is true (or missing), then the C<encode> method will output JSON objects
 by sorting their keys. This is adding a comparatively high overhead.
 enabled by this setting.
 If C<$enable> is false, then the C<allow_blessed> setting will decide what
 to do when a blessed object is found.
-=item $json = $json->filter_json_object ([$coderef])
+=item $json = $json->filter_json_object ([$coderef->($hashref)])
 When C<$coderef> is specified, it will be called from C<decode> each
 time it decodes a JSON object. The only argument is a reference to the
 newly-created hash. If the code references returns a single scalar (which
 need not be a reference), this value (i.e. a copy of that scalar to avoid
 aliasing) is inserted into the deserialised data structure. If it returns
 an empty list (NOTE: I<not> C<undef>, which is a valid scalar), the
 original deserialised hash will be inserted. This setting can slow down
 decoding considerably.
-When C<$coderef> is omitted or undefined, C<decode> will not change the
+When C<$coderef> is omitted or undefined, any existing callback will
-deserialised hash in any way. This is maximally fast.
+be removed and C<decode> will not change the deserialised hash in any
+way.
 Example, convert all JSON objects into the integer 5:
    my $js = JSON::XS->new->filter_json_object (sub { 5 });
    # returns [5]
    $js->decode ('[{}]')
-   # throw an exception because allow_nonref is not enabled:
+   # throw an exception because allow_nonref is not enabled
+   # so a lone 5 is not allowed.
    $js->decode ('{"a":1, "b":2}');
-=item $json = $json->filter_json_single_key_object ([$coderef])
+=item $json = $json->filter_json_single_key_object ($key [=> $coderef->($value)])
-Works like C<filter_json_object>, but is only called for JSON objects
+Works remotely similar to C<filter_json_object>, but is only called for
-having only a single key.
+JSON objects having a single key named C<$key>.
 This C<$coderef> is called before the one specified via
-C<filter_json_object>, if any. If it returns something, that will be
+C<filter_json_object>, if any. It gets passed the single value in the JSON
-inserted into the data structure. If it returns nothing, the callback
+object. If it returns a single value, it will be inserted into the data
-from C<filter_json_object> will be called next. If you want to force
+structure. If it returns nothing (not even C<undef> but the empty list),
-insertion of single-key objects even in the presence of a mutating
+the callback from C<filter_json_object> will be called next, as if no
-C<filter_json_object> callback, simply return the passed hash.
+single-key callback were specified.
+If C<$coderef> is omitted or undefined, the corresponding callback will be
+disabled. There can only ever be one callback for a given key.
 As this callback gets called less often then the C<filter_json_object>
 one, decoding speed will not usually suffer as much. Therefore, single-key
 objects make excellent targets to serialise Perl objects into, especially
 as single-key JSON objects are as close to the type-tagged value concept
 into the corresponding C<< $WIDGET{<id>} >> object:
    # return whatever is in $WIDGET{5}:
    JSON::XS
       ->new
-      ->filter_json_single_key_object (sub {
+      ->filter_json_single_key_object (__widget__ => sub {
-         exists $_[0]{__widget__}
-            ? $WIDGET{ $_[0]{__widget__} }
+            $WIDGET{ $_[0] }
-            : ()
          })
       ->decode ('{"__widget__": 5')
    # this can be used with a TO_JSON method in some "widget" class
    # for serialisation to json:
 are represented by the same codepoints in the Perl string, so no manual
 decoding is necessary.
 =item number
-A JSON number becomes either an integer or numeric (floating point)
+A JSON number becomes either an integer, numeric (floating point) or
-scalar in perl, depending on its range and any fractional parts. On the
+string scalar in perl, depending on its range and any fractional parts. On
-Perl level, there is no difference between those as Perl handles all the
+the Perl level, there is no difference between those as Perl handles all
-conversion details, but an integer may take slightly less memory and might
+the conversion details, but an integer may take slightly less memory and
-represent more values exactly than (floating point) numbers.
+might represent more values exactly than (floating point) numbers.
+If the number consists of digits only, JSON::XS will try to represent
+it as an integer value. If that fails, it will try to represent it as
+a numeric (floating point) value if that is possible without loss of
+precision. Otherwise it will preserve the number as a string value.
+Numbers containing a fractional or exponential part will always be
+represented as numeric (floating point) values, possibly at a loss of
+precision.
+This might create round-tripping problems as numbers might become strings,
+but as Perl is typeless there is no other way to do it.
 =item true, false
 These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>,
 respectively. They are overloaded to act almost exactly like the numbers
    to_json [\0,JSON::XS::true]      # yields [false,true]
 =item JSON::XS::true, JSON::XS::false
 These special values become JSON true and JSON false values,
-respectively. You cna alos use C<\1> and C<\0> directly if you want.
+respectively. You can also use C<\1> and C<\0> directly if you want.
 =item blessed objects
 Blessed objects are not allowed. JSON::XS currently tries to encode their
 underlying representation (hash- or arrayref), but this behaviour might
 still relatively early in its development. If you keep reporting bugs they
 will be fixed swiftly, though.
 =cut
-our $true  = do { bless \(my $dummy = "1"), "JSON::XS::Boolean" };
+our $true  = do { bless \(my $dummy = 1), "JSON::XS::Boolean" };
-our $false = do { bless \(my $dummy = "0"), "JSON::XS::Boolean" };
+our $false = do { bless \(my $dummy = 0), "JSON::XS::Boolean" };
 sub true()  { $true  }
 sub false() { $false }
 sub is_bool($) {

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing JSON-XS/XS.pm (file contents): Revision 1.51 by root, Mon Jul 2 01:12:27 2007 UTC vs. Revision 1.63 by root, Thu Oct 11 23:07:43 2007 UTC

Diff Legend

Comparing JSON-XS/XS.pm (file contents):
Revision 1.51 by root, Mon Jul 2 01:12:27 2007 UTC vs.
Revision 1.63 by root, Thu Oct 11 23:07:43 2007 UTC