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

Comparing JSON-XS/XS.pm (file contents):
Revision 1.169 by root, Thu Nov 15 20:49:12 2018 UTC vs.
Revision 1.170 by root, Thu Nov 15 22:35:35 2018 UTC

 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
-overridden) with no overhead due to emulation (by inheriting 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 it 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
-reports for other reasons.
 See MAPPING, below, on how JSON::XS maps perl values to JSON values and
 vice versa.
 =head2 FEATURES
-=over 4
+=over
 =item * correct Unicode handling
 This module knows how to handle Unicode, documents how and when it does
 so, and even documents what "correct" means.
 package JSON::XS;
 use common::sense;
-our $VERSION = 3.04;
+our $VERSION = '4.0';
 our @ISA = qw(Exporter);
 our @EXPORT = qw(encode_json decode_json);
 use Exporter;
 =head1 FUNCTIONAL INTERFACE
 The following convenience methods are provided by this module. They are
 exported by default:
-=over 4
+=over
 =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.
 =head1 A FEW NOTES ON UNICODE AND PERL
 Since this often leads to confusion, here are a few very clear words on
 how Unicode works in Perl, modulo bugs.
-=over 4
+=over
 =item 1. Perl strings can store characters with ordinal values > 255.
 This enables you to store Unicode characters as single characters in a
 Perl string - very natural.
 =head1 OBJECT-ORIENTED INTERFACE
 The object oriented interface lets you configure your own encoding or
 decoding style, within the limits of supported formats.
-=over 4
+=over
 =item $json = new JSON::XS
 Creates a new JSON::XS object that can be used to de/encode JSON
 strings. All boolean flags described below are by default I<disabled>
 If C<$enable> is false (the default), then C<decode> will only accept
 valid JSON texts.
 Currently accepted extensions are:
-=over 4
+=over
 =item * list items can have an end-comma
 JSON I<separates> array elements and key-value pairs with commas. This
 can be annoying if you write JSON texts manually and want to be able to
 to set resource limits (e.g. C<max_size>) to ensure the parser will stop
 parsing in the presence if syntax errors.
 The following methods implement this incremental parser.
-=over 4
+=over
 =item [void, scalar or list context] = $json->incr_parse ([$string])
 This is the central parsing function. It can both append new text and
 extract objects from the stream accumulated so far (both of these
 =back
 =head2 LIMITATIONS
-All options that affect decoding are supported, except
+The incremental parser is a non-exact parser: it works by gathering as
-C<allow_nonref>. The reason for this is that it cannot be made to work
+much text as possible that I<could> be a valid JSON text, followed by
-sensibly: JSON objects and arrays are self-delimited, i.e. you can
+trying to decode it.
-concatenate them back to back and still decode them perfectly. This does
-not hold true for JSON numbers, however.
-For example, is the string C<1> a single JSON number, or is it simply the
+That means it sometimes needs to read more data than strictly necessary to
-start of C<12>? Or is C<12> a single JSON number, or the concatenation
+diagnose an invalid JSON text. For example, after parsing the following
-of C<1> and C<2>? In neither case you can tell, and this is why JSON::XS
+fragment, the parser I<could> stop with an error, as this fragment
-takes the conservative route and disallows this case.
+I<cannot> be the beginning of a valid JSON text:
+   [,
+In reality, hopwever, the parser might continue to read data until a
+length limit is exceeded or it finds a closing bracket.
 =head2 EXAMPLES
 Some examples will make all this clearer. First, a simple example that
 works similarly to C<decode_prefix>: We want to decode the JSON object at
 refers to the abstract Perl language itself.
 =head2 JSON -> PERL
-=over 4
+=over
 =item object
 A JSON object becomes a reference to a hash in Perl. No ordering of object
 keys is preserved (JSON does not preserve object key ordering itself).
 The mapping from Perl to JSON is slightly more difficult, as Perl is a
 truly typeless language, so we can only guess which JSON type is meant by
 a Perl value.
-=over 4
+=over
 =item hash references
 Perl hash references become JSON objects. As there is no inherent
 ordering in hash keys (or JSON objects), they will usually be encoded
 What happens when C<JSON::XS> encounters a Perl object depends on the
 C<allow_blessed>, C<convert_blessed> and C<allow_tags> settings, which are
 used in this order:
-=over 4
+=over
 =item 1. C<allow_tags> is enabled and the object has a C<FREEZE> method.
 In this case, C<JSON::XS> uses the L<Types::Serialiser> object
 serialisation protocol to create a tagged JSON value, using a nonstandard
 takes those codepoint numbers and I<encodes> them, in our case into
 octets. Unicode is (among other things) a codeset, UTF-8 is an encoding,
 and ISO-8859-1 (= latin 1) and ASCII are both codesets I<and> encodings at
 the same time, which can be confusing.
-=over 4
+=over
 =item C<utf8> flag disabled
 When C<utf8> is disabled (the default), then C<encode>/C<decode> generate
 and expect Unicode strings, that is, characters with high ordinal Unicode
 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
 high that you will run into severe interoperability problems when you
 least expect it.
-=over 4
+=over
 =item (*)
 I have been pressured multiple times by Brian Ingerson (one of the
 authors of the YAML specification) to remove this paragraph, despite him
 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 getting
 security right).
-=head2 "OLD" VS. "NEW" JSON (RFC 4627 VS. RFC 7159)
+=head2 "OLD" VS. "NEW" JSON (RFC4627 VS. RFC7159)
 JSON originally required JSON texts to represent an array or object -
 scalar values were explicitly not allowed. This has changed, and versions
 of JSON::XS beginning with C<4.0> reflect this by allowing scalar values
 by default.
 This is a somewhat unhappy situation, and the blame can fully be put on
 JSON's inmventor, Douglas Crockford, who unilaterally changed the format
 in 2006 without consulting the IETF, forcing the IETF to either fork the
 format or go with it (as I was told, the IETF wasn't amused).
+=head1 RELATIONSHIP WITH I-JSON
+JSON is a somewhat sloppily-defined format - it carries around obvious
+Javascript baggage, such as not really defining number range, probably
+because Javascript only has one type of numbers: IEEE 64 bit floats
+("binary64").
+For this reaosn, RFC7493 defines "Internet JSON", which is a restricted
+subset of JSON that is supposedly more interoperable on the internet.
+While C<JSON::XS> does not offer specific support for I-JSON, it of course
+accepts valid I-JSON and by default implements some of the limitations
+of I-JSON, such as parsing numbers as perl numbers, which are usually a
+superset of binary64 numbers.
+To generate I-JSON, follow these rules:
+=over
+=item * always generate UTF-8
+I-JSON must be encoded in UTF-8, the default for C<encode_json>.
+=item * numbers should be within IEEE 754 binary64 range
+Basically all existing perl installations use binary64 to represent
+floating point numbers, so all you need to do is to avoid large integers.
+=item * objects must not have duplicate keys
+This is trivially done, as C<JSON::XS> does not allow duplicate keys.
+=item * do not generate scalar JSON texts, use C<< ->allow_nonref (0) >>
+I-JSON strongly requests you to only encode arrays and objects into JSON.
+=item * times should be strings in ISO 8601 format
+There are a myriad of modules on CPAN dealing with ISO 8601 - search for
+C<ISO8601> on CPAN and use one.
+=item * encode binary data as base64
+While it's tempting to just dump binary data as a string (and let
+C<JSON::XS> do the escaping), for I-JSON, it's I<recommended> to encode
+binary data as base64.
+=back
+There are some other considerations - read RFC7493 for the details if
+interested.
 =head1 INTEROPERABILITY WITH OTHER MODULES
 C<JSON::XS> uses the L<Types::Serialiser> module to provide boolean
 Again, this has some limitations - the magic string must not be encoded
 with character escapes, and the constructor arguments must be non-empty.
-=head1 RFC7159
-Since this module was written, Google has written a new JSON RFC, RFC 7159
-(and RFC7158). Unfortunately, this RFC breaks compatibility with both the
-original JSON specification on www.json.org and RFC4627.
-As far as I can see, you can get partial compatibility when parsing by
-using C<< ->allow_nonref >>. However, consider the security implications
-of doing so.
-I haven't decided yet when to break compatibility with RFC4627 by default
-(and potentially leave applications insecure) and change the default to
-follow RFC7159, but application authors are well advised to call C<<
-->allow_nonref(0) >> even if this is the current default, if they cannot
-handle non-reference values, in preparation for the day when the default
-will change.
 =head1 (I-)THREADS
 This module is I<not> guaranteed to be ithread (or MULTIPLICITY-) safe
 and there are no plans to change this. Note that perl's builtin so-called
 threads/ithreads are officially deprecated and should not be used.
 categories you need, such as C<LC_MESSAGES> or C<LC_CTYPE>.
 If you need C<LC_NUMERIC>, you should enable it only around the code that
 actually needs it (avoiding stringification of numbers), and restore it
 afterwards.
+=head1 SOME HISTORY
+At the time this module was created there already were a number of JSON
+modules available on CPAN, so what was the reason to write yet another
+JSON module? While it seems there are many JSON modules, none of them
+correctly handled all corner cases, and in most cases their maintainers
+are unresponsive, gone missing, or not listening to bug reports for other
+reasons.
+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
+overridden) with no overhead due to emulation (by inheriting 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 it and
+doesn't require a C compiler when that is a problem.
+Somewhere around version 3, this module was forked into
+C<Cpanel::JSON::XS>, because its maintainer had serious trouble
+understanding JSON and insisted on a fork with many bugs "fixed" that
+weren't actually bugs, while spreading FUD about this module without
+actually giving any details on his accusations. You be the judge, but
+in my personal opinion, if you want quality, you will stay away from
+dangerous forks like that.
 =head1 BUGS
 While the goal of this module is to be correct, that unfortunately does

Diff Legend

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

Comparing JSON-XS/XS.pm (file contents): Revision 1.169 by root, Thu Nov 15 20:49:12 2018 UTC vs. Revision 1.170 by root, Thu Nov 15 22:35:35 2018 UTC

Diff Legend

Comparing JSON-XS/XS.pm (file contents):
Revision 1.169 by root, Thu Nov 15 20:49:12 2018 UTC vs.
Revision 1.170 by root, Thu Nov 15 22:35:35 2018 UTC