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

Comparing JSON-XS/XS.pm (file contents):
Revision 1.77 by root, Tue Dec 4 10:37:42 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);
 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:
 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.77 by root, Tue Dec 4 10:37:42 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.77 by root, Tue Dec 4 10:37:42 2007 UTC vs.
Revision 1.83 by root, Sun Jan 20 19:19:07 2008 UTC