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

Comparing JSON-XS/XS.pm (file contents):
Revision 1.74 by root, Wed Nov 28 13:57:15 2007 UTC vs.
Revision 1.83 by root, Sun Jan 20 19:19:07 2008 UTC

  use JSON::XS;
  # exported functions, they croak on error
  # and expect/generate UTF-8
- $utf8_encoded_json_text = to_json $perl_hash_or_arrayref;
+ $utf8_encoded_json_text = encode_json $perl_hash_or_arrayref;
- $perl_hash_or_arrayref  = from_json $utf8_encoded_json_text;
+ $perl_hash_or_arrayref  = decode_json $utf8_encoded_json_text;
  # 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.
 =head1 DESCRIPTION
 This module converts Perl data structures to JSON and vice versa. Its
 primary goal is to be I<correct> and its secondary goal is to be
 I<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 to bug
 package JSON::XS;
 use strict;
-our $VERSION = '2.0';
+our $VERSION = '2.01';
 our @ISA = qw(Exporter);
-our @EXPORT = qw(to_json from_json);
+our @EXPORT = qw(encode_json decode_json to_json from_json);
+sub to_json($) {
+   require Carp;
+   Carp::croak ("JSON::XS::to_json has been renamed to encode_json, either downgrade to pre-2.0 versions of JSON::XS or rename the call");
+}
+sub from_json($) {
+   require Carp;
+   Carp::croak ("JSON::XS::from_json has been renamed to decode_json, either downgrade to pre-2.0 versions of JSON::XS or rename the call");
+}
 use Exporter;
 use XSLoader;
 =head1 FUNCTIONAL INTERFACE
 The following convenience methods are provided by this module. They are
 exported by default:
 =over 4
-=item $json_text = to_json $perl_scalar
+=item $json_text = encode_json $perl_scalar
 Converts the given Perl data structure to a UTF-8 encoded, binary string
 (that is, the string contains 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
+=item $perl_scalar = decode_json $json_text
-The opposite of C<to_json>: expects an UTF-8 (binary) string and tries
+The opposite of C<encode_json>: expects an UTF-8 (binary) string and tries
 to parse that as an UTF-8 encoded JSON text, returning the resulting
 reference. Croaks on error.
 This function call is functionally identical to:
    JSON::XS->new->allow_nonref->encode ("Hello, World!")
    => "Hello, World!"
 =item $json = $json->allow_blessed ([$enable])
-=item $enabled = $json->get_allow_bless
+=item $enabled = $json->get_allow_blessed
 If C<$enable> is true (or missing), then the C<encode> method will not
 barf when it encounters a blessed reference. Instead, the value of the
 B<convert_blessed> option will decide whether C<null> (C<convert_blessed>
-disabled or no C<to_json> method found) or a representation of the
+disabled or no C<TO_JSON> method found) or a representation of the
-object (C<convert_blessed> enabled and C<to_json> method found) is being
+object (C<convert_blessed> enabled and C<TO_JSON> method found) is being
 encoded. Has no effect on C<decode>.
 If C<$enable> is false (the default), then C<encode> will throw an
 exception when it encounters a blessed object.
 The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON>
 returns other blessed objects, those will be handled in the same
 way. C<TO_JSON> must take care of not causing an endless recursion cycle
 (== crash) in this case. The name of C<TO_JSON> was chosen because other
 methods called by the Perl core (== not by the user of the object) are
-usually in upper case letters and to avoid collisions with the C<to_json>
+usually in upper case letters and to avoid collisions with any C<to_json>
-function.
+function or method.
 This setting does not yet influence C<decode> in any way, but in the
 future, global hooks might get installed that influence C<decode> and are
 enabled by this setting.
 Other unblessed references are generally not allowed and will cause an
 exception to be thrown, except for references to the integers C<0> and
 C<1>, which get turned into C<false> and C<true> atoms in JSON. You can
 also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability.
-   to_json [\0,JSON::XS::true]      # yields [false,true]
+   encode_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 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
+Blessed objects are not directly representable in JSON. See the
-underlying representation (hash- or arrayref), but this behaviour might
+C<allow_blessed> and C<convert_blessed> methods on various options on
-change in future versions.
+how to deal with this: basically, you can choose between throwing an
+exception, encoding the reference as if it weren't blessed, or provide
+your own serialiser method.
 =item simple scalars
 Simple Perl scalars (any scalar that is not a reference) are the most
 difficult objects to encode: JSON::XS will encode undefined scalars as
-JSON null value, scalars that have last been used in a string context
+JSON C<null> values, scalars that have last been used in a string context
-before encoding as JSON strings and anything else as number value:
+before encoding as JSON strings, and anything else as number value:
    # dump as number
-   to_json [2]                      # yields [2]
+   encode_json [2]                      # yields [2]
-   to_json [-3.0e17]                # yields [-3e+17]
+   encode_json [-3.0e17]                # yields [-3e+17]
-   my $value = 5; to_json [$value]  # yields [5]
+   my $value = 5; encode_json [$value]  # yields [5]
    # used as string, so dump as string
    print $value;
-   to_json [$value]                 # yields ["5"]
+   encode_json [$value]                 # yields ["5"]
    # undef becomes null
-   to_json [undef]                  # yields [null]
+   encode_json [undef]                  # yields [null]
 You can force the type to be a JSON string by stringifying it:
    my $x = 3.1; # some variable containing a number
    "$x";        # stringified
    my $x = "3"; # some variable containing a string
    $x += 0;     # numify it, ensuring it will be dumped as a number
    $x *= 1;     # same thing, the choice is yours.
 You can not currently force the type in other, less obscure, ways. Tell me
-if you need this capability.
+if you need this capability (but don't forget to explain why its needed
+:).
 =back
 =head1 COMPARISON
 =back
 =head2 JSON and YAML
-You often hear that JSON is a subset (or a close subset) of YAML. This is,
+You often hear that JSON is a subset of YAML. This is, however, a mass
-however, a mass hysteria and very far from the truth. In general, there is
+hysteria(*) and very far from the truth. In general, there is no way to
-no way to configure JSON::XS to output a data structure as valid YAML.
+configure JSON::XS to output a data structure as valid YAML that works for
+all cases.
 If you really must use JSON::XS to generate YAML, you should use this
 algorithm (subject to change in future versions):
    my $to_yaml = JSON::XS->new->utf8->space_after (1);
    my $yaml = $to_yaml->encode ($ref) . "\n";
-This will usually generate JSON texts that also parse as valid
+This will I<usually> generate JSON texts that also parse as valid
 YAML. Please note that YAML has hardcoded limits on (simple) object key
-lengths that JSON doesn't have, so you should make sure that your hash
+lengths that JSON doesn't have and also has different and incompatible
+unicode handling, so you should make sure that your hash keys are
-keys are noticeably shorter than the 1024 characters YAML allows.
+noticeably shorter than the 1024 "stream characters" YAML allows and that
+you do not have codepoints with values outside the Unicode BMP (basic
+multilingual page). YAML also does not allow C<\/> sequences in strings
+(which JSON::XS does not I<currently> generate).
-There might be other incompatibilities that I am not aware of. In general
+There might be other incompatibilities that I am not aware of (or the YAML
+specification has been changed yet again - it does so quite often). In
-you should not try to generate YAML with a JSON generator or vice versa,
+general you should not try to generate YAML with a JSON generator or vice
-or try to parse JSON with a YAML parser or vice versa: chances are high
+versa, or try to parse JSON with a YAML parser or vice versa: chances are
-that you will run into severe interoperability problems.
+high that you will run into severe interoperability problems when you
+least expect it.
+=over 4
+=item (*)
+This is spread actively by the YAML team, however. For many years now they
+claim YAML were a superset of JSON, even when proven otherwise.
+Even the author of this manpage was at some point accused of providing
+"incorrect" information, despite the evidence presented (claims ranged
+from "your documentation contains inaccurate and negative statements about
+YAML" (the only negative comment is this footnote, and it didn't exist
+back then; the question on which claims were inaccurate was never answered
+etc.) to "the YAML spec is not up-to-date" (the *real* and supposedly
+JSON-compatible spec is apparently not currently publicly available)
+to actual requests to replace this section by *incorrect* information,
+suppressing information about the real problem).
+So whenever you are told that YAML was a superset of JSON, first check
+wether it is really true (it might be when you check it, but it certainly
+was not true when this was written). I would much prefer if the YAML team
+would spent their time on actually making JSON compatibility a truth
+(JSON, after all, has a very small and simple specification) instead of
+trying to lobby/force people into reporting untruths.
+=back
 =head2 SPEED
 It seems that JSON::XS is surprisingly fast, as shown in the following
 Third, JSON::XS recurses using the C stack when decoding objects and
 arrays. The C stack is a limited resource: for instance, on my amd64
 machine with 8MB of stack size I can decode around 180k nested arrays but
 only 14k nested JSON objects (due to perl itself recursing deeply on croak
-to free the temporary). If that is exceeded, the program crashes. to be
+to free the temporary). If that is exceeded, the program crashes. To be
 conservative, the default nesting limit is set to 512. If your process
 has a smaller stack, you should adjust this setting accordingly with the
 C<max_depth> method.
 And last but least, something else could bomb you that I forgot to think
 If you are using JSON::XS to return packets to consumption
 by JavaScript scripts in a browser you should have a look at
 L<http://jpsykes.com/47/practical-csrf-and-json-security> to see whether
 you are vulnerable to some common attack vectors (which really are browser
 design bugs, but it is still you who will have to deal with it, as major
-browser developers care only for features, not about doing security
+browser developers care only for features, not about getting security
 right).
 =head1 THREADS

Diff Legend

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

Comparing JSON-XS/XS.pm (file contents): Revision 1.74 by root, Wed Nov 28 13:57:15 2007 UTC vs. Revision 1.83 by root, Sun Jan 20 19:19:07 2008 UTC

Diff Legend

Comparing JSON-XS/XS.pm (file contents):
Revision 1.74 by root, Wed Nov 28 13:57:15 2007 UTC vs.
Revision 1.83 by root, Sun Jan 20 19:19:07 2008 UTC