[ViewVC] Diff of: cvs/JSON-XS/README

Comparing JSON-XS/README (file contents):
Revision 1.20 by root, Tue Nov 13 22:59:08 2007 UTC vs.
Revision 1.21 by root, Tue Dec 4 10:37:42 2007 UTC

      # OO-interface
      $coder = JSON::XS->new->ascii->pretty->allow_nonref;
      $pretty_printed_unencoded = $coder->encode ($perl_scalar);
      $perl_scalar = $coder->decode ($unicode_json_text);
+     # Note that JSON version 2.0 and above will automatically use JSON::XS
+     # if available, at virtually no speed overhead either, so you should
+     # be able to just:
+     use JSON;
+     # and do the same things, except that you have a pure-perl fallback now.
 DESCRIPTION
     This module converts Perl data structures to JSON and vice versa. Its
     primary goal is to be *correct* and its secondary goal is to be *fast*.
     To reach the latter goal it was written in C.
+    Beginning with version 2.0 of the JSON module, when both JSON and
+    JSON::XS are installed, then JSON will fall back on JSON::XS (this can
+    be overriden) with no overhead due to emulation (by inheritign
+    constructor and methods). If JSON::XS is not available, it will fall
+    back to the compatible JSON::PP module as backend, so using JSON instead
+    of JSON::XS gives you a portable JSON API that can be fast when you need
+    and doesn't require a C compiler when that is a problem.
     As this is the n-th-something JSON module on CPAN, what was the reason
     to write yet another JSON module? While it seems there are many JSON
     modules, none of them correctly handle all corner cases, and in most
     cases their maintainers are unresponsive, gone missing, or not listening
            my $json = JSON::XS->new->utf8->space_after->encode ({a => [1,2]})
            => {"a": [1, 2]}
     $json = $json->ascii ([$enable])
+    $enabled = $json->get_ascii
         If $enable is true (or missing), then the "encode" method will not
         generate characters outside the code range 0..127 (which is ASCII).
         Any Unicode characters outside that range will be escaped using
         either a single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL
         escape sequence, as per RFC4627. The resulting encoded JSON text can
           JSON::XS->new->ascii (1)->encode ([chr 0x10401])
           => ["\ud801\udc01"]
     $json = $json->latin1 ([$enable])
+    $enabled = $json->get_latin1
         If $enable is true (or missing), then the "encode" method will
         encode the resulting JSON text as latin1 (or iso-8859-1), escaping
         any characters outside the code range 0..255. The resulting string
         can be treated as a latin1-encoded JSON text or a native Unicode
         string. The "decode" method will not be affected in any way by this
           JSON::XS->new->latin1->encode (["\x{89}\x{abc}"]
           => ["\x{89}\\u0abc"]    # (perl syntax, U+abc escaped, U+89 not)
     $json = $json->utf8 ([$enable])
+    $enabled = $json->get_utf8
         If $enable is true (or missing), then the "encode" method will
         encode the JSON result into UTF-8, as required by many protocols,
         while the "decode" method expects to be handled an UTF-8-encoded
         string. Please note that UTF-8-encoded strings do not contain any
         characters outside the range 0..255, they are thus useful for
                  2
               ]
            }
     $json = $json->indent ([$enable])
+    $enabled = $json->get_indent
         If $enable is true (or missing), then the "encode" method will use a
         multiline format as output, putting every array member or
         object/hash key-value pair into its own line, indenting them
         properly.
         the resulting JSON text is guaranteed not to contain any "newlines".
         This setting has no effect when decoding JSON texts.
     $json = $json->space_before ([$enable])
+    $enabled = $json->get_space_before
         If $enable is true (or missing), then the "encode" method will add
         an extra optional space before the ":" separating keys from values
         in JSON objects.
         If $enable is false, then the "encode" method will not add any extra
         Example, space_before enabled, space_after and indent disabled:
            {"key" :"value"}
     $json = $json->space_after ([$enable])
+    $enabled = $json->get_space_after
         If $enable is true (or missing), then the "encode" method will add
         an extra optional space after the ":" separating keys from values in
         JSON objects and extra whitespace after the "," separating key-value
         pairs and array members.
         Example, space_before and indent disabled, space_after enabled:
            {"key": "value"}
     $json = $json->relaxed ([$enable])
+    $enabled = $json->get_relaxed
         If $enable is true (or missing), then "decode" will accept some
         extensions to normal JSON syntax (see below). "encode" will not be
         affected in anyway. *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
                  1, # this comment not allowed in JSON
                     # neither this one...
               ]
     $json = $json->canonical ([$enable])
+    $enabled = $json->get_canonical
         If $enable is true (or missing), then the "encode" method will
         output JSON objects by sorting their keys. This is adding a
         comparatively high overhead.
         If $enable is false, then the "encode" method will output key-value
         in Perl.
         This setting has no effect when decoding JSON texts.
     $json = $json->allow_nonref ([$enable])
+    $enabled = $json->get_allow_nonref
         If $enable is true (or missing), then the "encode" method can
         convert a non-reference into its corresponding string, number or
         null JSON value, which is an extension to RFC4627. Likewise,
         "decode" will accept those JSON values instead of croaking.
            JSON::XS->new->allow_nonref->encode ("Hello, World!")
            => "Hello, World!"
     $json = $json->allow_blessed ([$enable])
+    $enabled = $json->get_allow_blessed
         If $enable is true (or missing), then the "encode" method will not
         barf when it encounters a blessed reference. Instead, the value of
         the convert_blessed option will decide whether "null"
-        ("convert_blessed" disabled or no "to_json" method found) or a
+        ("convert_blessed" disabled or no "TO_JSON" method found) or a
         representation of the object ("convert_blessed" enabled and
-        "to_json" method found) is being encoded. Has no effect on "decode".
+        "TO_JSON" method found) is being encoded. Has no effect on "decode".
         If $enable is false (the default), then "encode" will throw an
         exception when it encounters a blessed object.
     $json = $json->convert_blessed ([$enable])
+    $enabled = $json->get_convert_blessed
         If $enable is true (or missing), then "encode", upon encountering a
         blessed object, will check for the availability of the "TO_JSON"
         method on the object's class. If found, it will be called in scalar
         context and the resulting scalar will be encoded instead of the
         object. If no "TO_JSON" method is found, the value of
               { __widget__ => $self->{id} }
            }
     $json = $json->shrink ([$enable])
+    $enabled = $json->get_shrink
         Perl usually over-allocates memory a bit when allocating space for
         strings. This flag optionally resizes strings generated by either
         "encode" or "decode" to their minimum size possible. This can save
         memory when your JSON texts are either very very long or you have
         many short strings. It will also try to downgrade any strings to
         converting strings that look like integers or floats into integers
         or floats internally (there is no difference on the Perl level),
         saving space.
     $json = $json->max_depth ([$maximum_nesting_depth])
+    $max_depth = $json->get_max_depth
         Sets the maximum nesting level (default 512) accepted while encoding
         or decoding. If the JSON text or Perl data structure has an equal or
         higher nesting level then this limit, then the encoder and decoder
         will stop and croak at that point.
         See SECURITY CONSIDERATIONS, below, for more info on why this is
         useful.
     $json = $json->max_size ([$maximum_string_size])
+    $max_size = $json->get_max_size
         Set the maximum length a JSON text may have (in bytes) where
         decoding is being attempted. The default is 0, meaning no limit.
         When "decode" is called on a string longer then this number of
         characters it will not attempt to decode the string but throw an
         exception. This setting has no effect on "encode" (yet).
     It shows the number of encodes/decodes per second (JSON::XS uses the
     functional interface, while JSON::XS/2 uses the OO interface with
     pretty-printing and hashkey sorting enabled, JSON::XS/3 enables shrink).
     Higher is better:
-       Storable   |  15779.925 |  14169.946 |
-       -----------+------------+------------+
        module     |     encode |     decode |
        -----------|------------|------------|
-       JSON       |   4990.842 |   4088.813 |
+       JSON 1.x   |   4990.842 |   4088.813 |
        JSON::DWIW |  51653.990 |  71575.154 |
        JSON::PC   |  65948.176 |  74631.744 |
        JSON::PP   |   8931.652 |   3817.168 |
        JSON::Syck |  24877.248 |  27776.848 |
        JSON::XS   | 388361.481 | 227951.304 |
     Using a longer test string (roughly 18KB, generated from Yahoo! Locals
     search API (http://nanoref.com/yahooapis/mgPdGg):
        module     |     encode |     decode |
        -----------|------------|------------|
-       JSON       |     55.260 |     34.971 |
+       JSON 1.x   |     55.260 |     34.971 |
        JSON::DWIW |    825.228 |   1082.513 |
        JSON::PC   |   3571.444 |   2394.829 |
        JSON::PP   |    210.987 |     32.574 |
        JSON::Syck |    552.551 |    787.544 |
        JSON::XS   |   5780.463 |   4854.519 |

Diff Legend

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

Comparing JSON-XS/README (file contents): Revision 1.20 by root, Tue Nov 13 22:59:08 2007 UTC vs. Revision 1.21 by root, Tue Dec 4 10:37:42 2007 UTC

Diff Legend

Comparing JSON-XS/README (file contents):
Revision 1.20 by root, Tue Nov 13 22:59:08 2007 UTC vs.
Revision 1.21 by root, Tue Dec 4 10:37:42 2007 UTC