[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.61 by root, Wed Sep 12 17:42:36 2007 UTC

 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;
 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.61 by root, Wed Sep 12 17:42:36 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.61 by root, Wed Sep 12 17:42:36 2007 UTC