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

Comparing JSON-XS/XS.pm (file contents):
Revision 1.78 by root, Wed Dec 5 10:59:28 2007 UTC vs.
Revision 1.83 by root, Sun Jan 20 19:19:07 2008 UTC

 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
    encode_json [2]                      # yields [2]
    encode_json [-3.0e17]                # yields [-3e+17]
    my $value = 5; encode_json [$value]  # yields [5]
    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.78 by root, Wed Dec 5 10:59:28 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.78 by root, Wed Dec 5 10:59:28 2007 UTC vs.
Revision 1.83 by root, Sun Jan 20 19:19:07 2008 UTC