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

Comparing JSON-XS/XS.pm (file contents):
Revision 1.89 by root, Wed Mar 19 13:54:53 2008 UTC vs.
Revision 1.93 by root, Sat Mar 22 22:21:33 2008 UTC

+=head1 NAME
 =encoding utf-8
-=head1 NAME
 JSON::XS - JSON serialising/deserialising, done correctly and fast
 JSON::XS - 正しくて高速な JSON シリアライザ/デシリアライザ
            (http://fleur.hio.jp/perldoc/mix/lib/JSON/XS.html)
 package JSON::XS;
 use strict;
-our $VERSION = '2.01';
+our $VERSION = '2.1';
 our @ISA = qw(Exporter);
 our @EXPORT = qw(encode_json decode_json to_json from_json);
 sub to_json($) {
 If C<$enable> is false, then the C<encode> method will not escape Unicode
 characters unless required by the JSON syntax or other flags. This results
 in a faster and more compact format.
+See also the section I<ENCODING/CODESET FLAG NOTES> later in this
+document.
 The main use for this flag is to produce JSON texts that can be
 transmitted over a 7-bit channel, as the encoded JSON texts will not
 contain any 8 bit characters.
   JSON::XS->new->ascii (1)->encode ([chr 0x10401])
 will not be affected in any way by this flag, as C<decode> by default
 expects Unicode, which is a strict superset of latin1.
 If C<$enable> is false, then the C<encode> method will not escape Unicode
 characters unless required by the JSON syntax or other flags.
+See also the section I<ENCODING/CODESET FLAG NOTES> later in this
+document.
 The main use for this flag is efficiently encoding binary data as JSON
 text, as most octets will not be escaped, resulting in a smaller encoded
 size. The disadvantage is that the resulting JSON text is encoded
 in latin1 (and must correctly be treated as such when storing and
 If C<$enable> is false, then the C<encode> method will return the JSON
 string as a (non-encoded) Unicode string, while C<decode> expects thus a
 Unicode string.  Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs
 to be done yourself, e.g. using the Encode module.
+See also the section I<ENCODING/CODESET FLAG NOTES> later in this
+document.
 Example, output UTF-16BE-encoded JSON:
   use Encode;
   $jsontext = encode "UTF-16BE", JSON::XS->new->encode ($object);
    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 (but don't forget to explain why its needed
+if you need this capability (but don't forget to explain why it's needed
 :).
 =back
 The interested reader might have seen a number of flags that signify
 encodings or codesets - C<utf8>, C<latin1> and C<ascii>. There seems to be
 some confusion on what these do, so here is a short comparison:
-C<utf8> controls wether the JSON text created by C<encode> (and expected
+C<utf8> controls whether the JSON text created by C<encode> (and expected
 by C<decode>) is UTF-8 encoded or not, while C<latin1> and C<ascii> only
-control wether C<encode> escapes character values outside their respective
+control whether C<encode> escapes character values outside their respective
 codeset range. Neither of these flags conflict with each other, although
 some combinations make less sense than others.
 Care has been taken to make all flags symmetrical with respect to
 C<encode> and C<decode>, that is, texts encoded with any combination of
 =head2 JSON and YAML
 You often hear that JSON is a subset of YAML. This is, however, a mass
-hysteria(*) and very far from the truth. In general, there is no way to
+hysteria(*) and very far from the truth (as of the time of this writing),
+so let me state it clearly: I<in general, there is no way to configure
-configure JSON::XS to output a data structure as valid YAML that works for
+JSON::XS to output a data structure as valid YAML> that works in all
-all cases.
+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);
 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 and also has different and incompatible
 unicode handling, so you should make sure that your hash keys are
 noticeably shorter than the 1024 "stream characters" YAML allows and that
-you do not have codepoints with values outside the Unicode BMP (basic
+you do not have characters with codepoint values outside the Unicode BMP
-multilingual page). YAML also does not allow C<\/> sequences in strings
+(basic multilingual page). YAML also does not allow C<\/> sequences in
-(which JSON::XS does not I<currently> generate).
+strings (which JSON::XS does not I<currently> generate, but other JSON
+generators might).
 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
 general you should not try to generate YAML with a JSON generator or vice
 versa, or try to parse JSON with a YAML parser or vice versa: chances are
 =over 4
 =item (*)
-This is spread actively by the YAML team, however. For many years now they
+I have been pressured multiple times by Brian Ingerson (one of the
-claim YAML were a superset of JSON, even when proven otherwise.
+authors of the YAML specification) to remove this paragraph, despite him
+acknowledging that the actual incompatibilities exist. As I was personally
+bitten by this "JSON is YAML" lie, I refused and said I will continue to
+educate people about these issues, so others do not run into the same
+problem again and again. After this, Brian called me a (quote)I<complete
+and worthless idiot>(unquote).
-Even the author of this manpage was at some point accused of providing
+In my opinion, instead of pressuring and insulting people who actually
-"incorrect" information, despite the evidence presented (claims ranged
+clarify issues with YAML and the wrong statements of some of its
-from "your documentation contains inaccurate and negative statements about
+proponents, I would kindly suggest reading the JSON spec (which is not
-YAML" (the only negative comment is this footnote, and it didn't exist
+that difficult or long) and finally make YAML compatible to it, and
-back then; the question on which claims were inaccurate was never answered
+educating users about the changes, instead of spreading lies about the
-etc.) to "the YAML spec is not up-to-date" (the *real* and supposedly
+real compatibility for many I<years> and trying to silence people who
-JSON-compatible spec is apparently not currently publicly available)
+point out that it isn't true.
-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
 =head1 THREADS
 This module is I<not> guaranteed to be thread safe and there are no
 plans to change this until Perl gets thread support (as opposed to the
 horribly slow so-called "threads" which are simply slow and bloated
-process simulations - use fork, its I<much> faster, cheaper, better).
+process simulations - use fork, it's I<much> faster, cheaper, better).
 (It might actually work, but you have been warned).
 =head1 BUGS
 While the goal of this module is to be correct, that unfortunately does
-not mean its bug-free, only that I think its design is bug-free. It is
+not mean it's bug-free, only that I think its design is bug-free. It is
 still relatively early in its development. If you keep reporting bugs they
 will be fixed swiftly, though.
 Please refrain from using rt.cpan.org or any other bug reporting
 service. I put the contact address into my modules for a reason.
    "--"     => sub { $_[0] = ${$_[0]} - 1 },
    fallback => 1;
 1;
+=head1 SEE ALSO
+The F<json_xs> command line utility for quick experiments.
 =head1 AUTHOR
  Marc Lehmann <schmorp@schmorp.de>
  http://home.schmorp.de/

Diff Legend

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

Comparing JSON-XS/XS.pm (file contents): Revision 1.89 by root, Wed Mar 19 13:54:53 2008 UTC vs. Revision 1.93 by root, Sat Mar 22 22:21:33 2008 UTC

Diff Legend

Comparing JSON-XS/XS.pm (file contents):
Revision 1.89 by root, Wed Mar 19 13:54:53 2008 UTC vs.
Revision 1.93 by root, Sat Mar 22 22:21:33 2008 UTC