ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/JSON-XS/XS.pm
(Generate patch)

Comparing JSON-XS/XS.pm (file contents):
Revision 1.151 by root, Tue Oct 29 15:55:49 2013 UTC vs.
Revision 1.155 by root, Mon Nov 24 18:42:51 2014 UTC

402character, after which more white-space and comments are allowed. 402character, after which more white-space and comments are allowed.
403 403
404 [ 404 [
405 1, # this comment not allowed in JSON 405 1, # this comment not allowed in JSON
406 # neither this one... 406 # neither this one...
407 ]
408
409=item * literal ASCII TAB characters in strings
410
411Literal ASCII TAB characters are now allowed in strings (and treated as
412C<\t>).
413
414 [
415 "Hello\tWorld",
416 "Hello<TAB>World", # literal <TAB> would not normally be allowed
407 ] 417 ]
408 418
409=back 419=back
410 420
411=item $json = $json->canonical ([$enable]) 421=item $json = $json->canonical ([$enable])
1561constants. That means that the JSON true and false values will be 1571constants. That means that the JSON true and false values will be
1562comaptible to true and false values of iother modules that do the same, 1572comaptible to true and false values of iother modules that do the same,
1563such as L<JSON::PP> and L<CBOR::XS>. 1573such as L<JSON::PP> and L<CBOR::XS>.
1564 1574
1565 1575
1576=head1 INTEROPERABILITY WITH OTHER JSON DECODERS
1577
1578As long as you only serialise data that can be directly expressed in JSON,
1579C<JSON::XS> is incapable of generating invalid JSON output (modulo bugs,
1580but C<JSON::XS> has found more bugs in the official JSON testsuite (1)
1581than the official JSON testsuite has found in C<JSON::XS> (0)).
1582
1583When you have trouble decoding JSON generated by this module using other
1584decoders, then it is very likely that you have an encoding mismatch or the
1585other decoder is broken.
1586
1587When decoding, C<JSON::XS> is strict by default and will likely catch all
1588errors. There are currently two settings that change this: C<relaxed>
1589makes C<JSON::XS> accept (but not generate) some non-standard extensions,
1590and C<allow_tags> will allow you to encode and decode Perl objects, at the
1591cost of not outputting valid JSON anymore.
1592
1593=head2 TAGGED VALUE SYNTAX AND STANDARD JSON EN/DECODERS
1594
1595When you use C<allow_tags> to use the extended (and also nonstandard and
1596invalid) JSON syntax for serialised objects, and you still want to decode
1597the generated When you want to serialise objects, you can run a regex
1598to replace the tagged syntax by standard JSON arrays (it only works for
1599"normal" packagesnames without comma, newlines or single colons). First,
1600the readable Perl version:
1601
1602 # if your FREEZE methods return no values, you need this replace first:
1603 $json =~ s/\( \s* (" (?: [^\\":,]+|\\.|::)* ") \s* \) \s* \[\s*\]/[$1]/gx;
1604
1605 # this works for non-empty constructor arg lists:
1606 $json =~ s/\( \s* (" (?: [^\\":,]+|\\.|::)* ") \s* \) \s* \[/[$1,/gx;
1607
1608And here is a less readable version that is easy to adapt to other
1609languages:
1610
1611 $json =~ s/\(\s*("([^\\":,]+|\\.|::)*")\s*\)\s*\[/[$1,/g;
1612
1613Here is an ECMAScript version (same regex):
1614
1615 json = json.replace (/\(\s*("([^\\":,]+|\\.|::)*")\s*\)\s*\[/g, "[$1,");
1616
1617Since this syntax converts to standard JSON arrays, it might be hard to
1618distinguish serialised objects from normal arrays. You can prepend a
1619"magic number" as first array element to reduce chances of a collision:
1620
1621 $json =~ s/\(\s*("([^\\":,]+|\\.|::)*")\s*\)\s*\[/["XU1peReLzT4ggEllLanBYq4G9VzliwKF",$1,/g;
1622
1623And after decoding the JSON text, you could walk the data
1624structure looking for arrays with a first element of
1625C<XU1peReLzT4ggEllLanBYq4G9VzliwKF>.
1626
1627The same approach can be used to create the tagged format with another
1628encoder. First, you create an array with the magic string as first member,
1629the classname as second, and constructor arguments last, encode it as part
1630of your JSON structure, and then:
1631
1632 $json =~ s/\[\s*"XU1peReLzT4ggEllLanBYq4G9VzliwKF"\s*,\s*("([^\\":,]+|\\.|::)*")\s*,/($1)[/g;
1633
1634Again, this has some limitations - the magic string must not be encoded
1635with character escapes, and the constructor arguments must be non-empty.
1636
1637
1638=head1 RFC7159
1639
1640Since this module was written, Google has written a new JSON RFC, RFC 7159
1641(and RFC7158). Unfortunately, this RFC breaks compatibility with both the
1642original JSON specification on www.json.org and RFC4627.
1643
1644As far as I can see, you can get partial compatibility when parsing by
1645using C<< ->allow_nonref >>. However, consider thew security implications
1646of doing so.
1647
1648I haven't decided yet when to break compatibility with RFC4627 by default
1649(and potentially leave applications insecure) and change the default to
1650follow RFC7159, but application authors are well advised to call C<<
1651->allow_nonref(0) >> even if this is the current default, if they cannot
1652handle non-reference values, in preparation for the day when the4 default
1653will change.
1654
1655
1566=head1 THREADS 1656=head1 THREADS
1567 1657
1568This module is I<not> guaranteed to be thread safe and there are no 1658This module is I<not> guaranteed to be thread safe and there are no
1569plans to change this until Perl gets thread support (as opposed to the 1659plans to change this until Perl gets thread support (as opposed to the
1570horribly slow so-called "threads" which are simply slow and bloated 1660horribly slow so-called "threads" which are simply slow and bloated

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines