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.147 by root, Tue Oct 29 00:19:08 2013 UTC vs.
Revision 1.155 by root, Mon Nov 24 18:42:51 2014 UTC

… …
101 101
102package JSON::XS; 102package JSON::XS;
103 103
104use common::sense; 104use common::sense;
105 105
106our $VERSION = '3.0'; 106our $VERSION = 3.01;
107our @ISA = qw(Exporter); 107our @ISA = qw(Exporter);
108 108
109our @EXPORT = qw(encode_json decode_json); 109our @EXPORT = qw(encode_json decode_json);
110 110
111use Exporter; 111use Exporter;
… …
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 ] 407 ]
408 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
417 ]
418
409=back 419=back
410 420
411=item $json = $json->canonical ([$enable]) 421=item $json = $json->canonical ([$enable])
412 422
413=item $enabled = $json->get_canonical 423=item $enabled = $json->get_canonical
… …
483 493
484=item $json = $json->convert_blessed ([$enable]) 494=item $json = $json->convert_blessed ([$enable])
485 495
486=item $enabled = $json->get_convert_blessed 496=item $enabled = $json->get_convert_blessed
487 497
488See "OBJECT SERIALISATION" for details. 498See L<OBJECT SERIALISATION> for details.
489 499
490If C<$enable> is true (or missing), then C<encode>, upon encountering a 500If C<$enable> is true (or missing), then C<encode>, upon encountering a
491blessed object, will check for the availability of the C<TO_JSON> method 501blessed object, will check for the availability of the C<TO_JSON> method
492on the object's class. If found, it will be called in scalar context and 502on the object's class. If found, it will be called in scalar context and
493the resulting scalar will be encoded instead of the object. 503the resulting scalar will be encoded instead of the object.
… …
507 517
508=item $json = $json->allow_tags ([$enable]) 518=item $json = $json->allow_tags ([$enable])
509 519
510=item $enabled = $json->allow_tags 520=item $enabled = $json->allow_tags
511 521
512See "OBJECT SERIALISATION" for details. 522See L<OBJECT SERIALISATION> for details.
513 523
514If C<$enable> is true (or missing), then C<encode>, upon encountering a 524If C<$enable> is true (or missing), then C<encode>, upon encountering a
515blessed object, will check for the availability of the C<FREEZE> method on 525blessed object, will check for the availability of the C<FREEZE> method on
516the object's class. If found, it will be used to serialise the object into 526the object's class. If found, it will be used to serialise the object into
517a nonstandard tagged JSON value (that JSON decoders cannot decode). 527a nonstandard tagged JSON value (that JSON decoders cannot decode).
… …
1017Another nonstandard extension to the JSON syntax, enabled with the 1027Another nonstandard extension to the JSON syntax, enabled with the
1018C<allow_tags> setting, are tagged values. In this implementation, the 1028C<allow_tags> setting, are tagged values. In this implementation, the
1019I<tag> must be a perl package/class name encoded as a JSON string, and the 1029I<tag> must be a perl package/class name encoded as a JSON string, and the
1020I<value> must be a JSON array encoding optional constructor arguments. 1030I<value> must be a JSON array encoding optional constructor arguments.
1021 1031
1022See "OBJECT SERIALISATION", below, for details. 1032See L<OBJECT SERIALISATION>, below, for details.
1023 1033
1024=back 1034=back
1025 1035
1026 1036
1027=head2 PERL -> JSON 1037=head2 PERL -> JSON
… …
1066directly if you want. 1076directly if you want.
1067 1077
1068=item blessed objects 1078=item blessed objects
1069 1079
1070Blessed objects are not directly representable in JSON, but C<JSON::XS> 1080Blessed objects are not directly representable in JSON, but C<JSON::XS>
1071allows various ways of handling objects. See "OBJECT SERIALISATION", 1081allows various ways of handling objects. See L<OBJECT SERIALISATION>,
1072below, for details. 1082below, for details.
1073 1083
1074=item simple scalars 1084=item simple scalars
1075 1085
1076Simple Perl scalars (any scalar that is not a reference) are the most 1086Simple Perl scalars (any scalar that is not a reference) are the most
… …
1129C<allow_blessed>, C<convert_blessed> and C<allow_tags> settings, which are 1139C<allow_blessed>, C<convert_blessed> and C<allow_tags> settings, which are
1130used in this order: 1140used in this order:
1131 1141
1132=over 4 1142=over 4
1133 1143
1134=item 1. C<allow_tags> is enabled and object has a C<FREEZE> method. 1144=item 1. C<allow_tags> is enabled and the object has a C<FREEZE> method.
1135 1145
1136In this case, C<JSON::XS> uses the L<Types::Serialiser> object 1146In this case, C<JSON::XS> uses the L<Types::Serialiser> object
1137serialisation protocol to create a tagged JSON value, using a nonstandard 1147serialisation protocol to create a tagged JSON value, using a nonstandard
1138extension to the JSON syntax. 1148extension to the JSON syntax.
1139 1149
… …
1145more). These values and the paclkage/classname of the object will then be 1155more). These values and the paclkage/classname of the object will then be
1146encoded as a tagged JSON value in the following format: 1156encoded as a tagged JSON value in the following format:
1147 1157
1148 ("classname")[FREEZE return values...] 1158 ("classname")[FREEZE return values...]
1149 1159
1160e.g.:
1161
1162 ("URI")["http://www.google.com/"]
1163 ("MyDate")[2013,10,29]
1164 ("ImageData::JPEG")["Z3...VlCg=="]
1165
1150For example, the hypothetical C<My::Object> C<FREEZE> method might use the 1166For example, the hypothetical C<My::Object> C<FREEZE> method might use the
1151objects C<type> and C<id> members to encode the object: 1167objects C<type> and C<id> members to encode the object:
1152 1168
1153 sub My::Object::FREEZE { 1169 sub My::Object::FREEZE {
1154 my ($self, $serialiser) = @_; 1170 my ($self, $serialiser) = @_;
1155 1171
1156 ($self->{type}, $self->{id}) 1172 ($self->{type}, $self->{id})
1157 } 1173 }
1158 1174
1159=item 2. C<convert_blessed> is enabled and object has a C<TO_JSON> method. 1175=item 2. C<convert_blessed> is enabled and the object has a C<TO_JSON> method.
1160 1176
1161In this case, the C<TO_JSON> method of the object is invoked in scalar 1177In this case, the C<TO_JSON> method of the object is invoked in scalar
1162context. It must return a single scalar that can be directly encoded into 1178context. It must return a single scalar that can be directly encoded into
1163JSON. This scalar replaces the object in the JSON text. 1179JSON. This scalar replaces the object in the JSON text.
1164 1180
… …
1555constants. That means that the JSON true and false values will be 1571constants. That means that the JSON true and false values will be
1556comaptible 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,
1557such as L<JSON::PP> and L<CBOR::XS>. 1573such as L<JSON::PP> and L<CBOR::XS>.
1558 1574
1559 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
1560=head1 THREADS 1656=head1 THREADS
1561 1657
1562This 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
1563plans 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
1564horribly 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