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.146 by root, Tue Oct 29 00:18:55 2013 UTC vs.
Revision 1.153 by root, Sun Mar 2 20:41:14 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;
… …
467 467
468=item $json = $json->allow_blessed ([$enable]) 468=item $json = $json->allow_blessed ([$enable])
469 469
470=item $enabled = $json->get_allow_blessed 470=item $enabled = $json->get_allow_blessed
471 471
472See "OBJECT SERIALISATION" for details. 472See L<OBJECT SERIALISATION> for details.
473 473
474If C<$enable> is true (or missing), then the C<encode> method will not 474If C<$enable> is true (or missing), then the C<encode> method will not
475barf when it encounters a blessed reference that it cannot convert 475barf when it encounters a blessed reference that it cannot convert
476otherwise. Instead, a JSON C<null> value is encoded instead of the object. 476otherwise. Instead, a JSON C<null> value is encoded instead of the object.
477 477
… …
483 483
484=item $json = $json->convert_blessed ([$enable]) 484=item $json = $json->convert_blessed ([$enable])
485 485
486=item $enabled = $json->get_convert_blessed 486=item $enabled = $json->get_convert_blessed
487 487
488See "OBJECT SERIALISATION" for details. 488See L<OBJECT SERIALISATION> for details.
489 489
490If C<$enable> is true (or missing), then C<encode>, upon encountering a 490If 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 491blessed 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 492on the object's class. If found, it will be called in scalar context and
493the resulting scalar will be encoded instead of the object. 493the resulting scalar will be encoded instead of the object.
… …
507 507
508=item $json = $json->allow_tags ([$enable]) 508=item $json = $json->allow_tags ([$enable])
509 509
510=item $enabled = $json->allow_tags 510=item $enabled = $json->allow_tags
511 511
512See "OBJECT SERIALISATION" for details. 512See L<OBJECT SERIALISATION> for details.
513 513
514If C<$enable> is true (or missing), then C<encode>, upon encountering a 514If 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 515blessed 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 516the object's class. If found, it will be used to serialise the object into
517a nonstandard tagged JSON value (that JSON decoders cannot decode). 517a nonstandard tagged JSON value (that JSON decoders cannot decode).
… …
1017Another nonstandard extension to the JSON syntax, enabled with the 1017Another nonstandard extension to the JSON syntax, enabled with the
1018C<allow_tags> setting, are tagged values. In this implementation, the 1018C<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 1019I<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. 1020I<value> must be a JSON array encoding optional constructor arguments.
1021 1021
1022See "OBJECT SERIALISATION", below, for details. 1022See L<OBJECT SERIALISATION>, below, for details.
1023 1023
1024=back 1024=back
1025 1025
1026 1026
1027=head2 PERL -> JSON 1027=head2 PERL -> JSON
… …
1066directly if you want. 1066directly if you want.
1067 1067
1068=item blessed objects 1068=item blessed objects
1069 1069
1070Blessed objects are not directly representable in JSON, but C<JSON::XS> 1070Blessed objects are not directly representable in JSON, but C<JSON::XS>
1071allows various ways of handling objects. See "OBJECT SERIALISATION", 1071allows various ways of handling objects. See L<OBJECT SERIALISATION>,
1072below, for details. 1072below, for details.
1073 1073
1074=item simple scalars 1074=item simple scalars
1075 1075
1076Simple Perl scalars (any scalar that is not a reference) are the most 1076Simple 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 1129C<allow_blessed>, C<convert_blessed> and C<allow_tags> settings, which are
1130used in this order: 1130used in this order:
1131 1131
1132=over 4 1132=over 4
1133 1133
1134=item 1. C<allow_tags> is enabled and object has a C<FREEZE> method. 1134=item 1. C<allow_tags> is enabled and the object has a C<FREEZE> method.
1135 1135
1136In this case, C<JSON::XS> uses the L<Types::Serialiser> object 1136In this case, C<JSON::XS> uses the L<Types::Serialiser> object
1137serialisation protocol to create a tagged JSON value, using a nonstandard 1137serialisation protocol to create a tagged JSON value, using a nonstandard
1138extension to the JSON syntax. 1138extension to the JSON syntax.
1139 1139
… …
1145more). These values and the paclkage/classname of the object will then be 1145more). These values and the paclkage/classname of the object will then be
1146encoded as a tagged JSON value in the following format: 1146encoded as a tagged JSON value in the following format:
1147 1147
1148 ("classname")[FREEZE return values...] 1148 ("classname")[FREEZE return values...]
1149 1149
1150e.g.:
1151
1152 ("URI")["http://www.google.com/"]
1153 ("MyDate")[2013,10,29]
1154 ("ImageData::JPEG")["Z3...VlCg=="]
1155
1150For example, the hypothetical C<My::Object> C<FREEZE> method might use the 1156For example, the hypothetical C<My::Object> C<FREEZE> method might use the
1151objects C<type> and C<id> members to encode the object: 1157objects C<type> and C<id> members to encode the object:
1152 1158
1153 sub My::Object::FREEZE { 1159 sub My::Object::FREEZE {
1154 my ($self, $serialiser) = @_; 1160 my ($self, $serialiser) = @_;
1155 1161
1156 ($self->{type}, $self->{id}) 1162 ($self->{type}, $self->{id})
1157 } 1163 }
1158 1164
1159=item 2. C<convert_blessed> is enabled and object has a C<TO_JSON> method. 1165=item 2. C<convert_blessed> is enabled and the object has a C<TO_JSON> method.
1160 1166
1161In this case, the C<TO_JSON> method of the object is invoked in scalar 1167In 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 1168context. It must return a single scalar that can be directly encoded into
1163JSON. This scalar replaces the object in the JSON text. 1169JSON. This scalar replaces the object in the JSON text.
1164 1170
… …
1555constants. That means that the JSON true and false values will be 1561constants. That means that the JSON true and false values will be
1556comaptible to true and false values of iother modules that do the same, 1562comaptible to true and false values of iother modules that do the same,
1557such as L<JSON::PP> and L<CBOR::XS>. 1563such as L<JSON::PP> and L<CBOR::XS>.
1558 1564
1559 1565
1566=head1 INTEROPERABILITY WITH OTHER JSON DECODERS
1567
1568As long as you only serialise data that can be directly expressed in JSON,
1569C<JSON::XS> is incapable of generating invalid JSON output (modulo bugs,
1570but C<JSON::XS> has found more bugs in the official JSON testsuite (1)
1571than the official JSON testsuite has found in C<JSON::XS> (0)).
1572
1573When you have trouble decoding JSON generated by this module using other
1574decoders, then it is very likely that you have an encoding mismatch or the
1575other decoder is broken.
1576
1577When decoding, C<JSON::XS> is strict by default and will likely catch all
1578errors. There are currently two settings that change this: C<relaxed>
1579makes C<JSON::XS> accept (but not generate) some non-standard extensions,
1580and C<allow_tags> will allow you to encode and decode Perl objects, at the
1581cost of not outputting valid JSON anymore.
1582
1583=head2 TAGGED VALUE SYNTAX AND STANDARD JSON EN/DECODERS
1584
1585When you use C<allow_tags> to use the extended (and also nonstandard and
1586invalid) JSON syntax for serialised objects, and you still want to decode
1587the generated When you want to serialise objects, you can run a regex
1588to replace the tagged syntax by standard JSON arrays (it only works for
1589"normal" packagesnames without comma, newlines or single colons). First,
1590the readable Perl version:
1591
1592 # if your FREEZE methods return no values, you need this replace first:
1593 $json =~ s/\( \s* (" (?: [^\\":,]+|\\.|::)* ") \s* \) \s* \[\s*\]/[$1]/gx;
1594
1595 # this works for non-empty constructor arg lists:
1596 $json =~ s/\( \s* (" (?: [^\\":,]+|\\.|::)* ") \s* \) \s* \[/[$1,/gx;
1597
1598And here is a less readable version that is easy to adapt to other
1599languages:
1600
1601 $json =~ s/\(\s*("([^\\":,]+|\\.|::)*")\s*\)\s*\[/[$1,/g;
1602
1603Here is an ECMAScript version (same regex):
1604
1605 json = json.replace (/\(\s*("([^\\":,]+|\\.|::)*")\s*\)\s*\[/g, "[$1,");
1606
1607Since this syntax converts to standard JSON arrays, it might be hard to
1608distinguish serialised objects from normal arrays. You can prepend a
1609"magic number" as first array element to reduce chances of a collision:
1610
1611 $json =~ s/\(\s*("([^\\":,]+|\\.|::)*")\s*\)\s*\[/["XU1peReLzT4ggEllLanBYq4G9VzliwKF",$1,/g;
1612
1613And after decoding the JSON text, you could walk the data
1614structure looking for arrays with a first element of
1615C<XU1peReLzT4ggEllLanBYq4G9VzliwKF>.
1616
1617The same approach cna be used to create the tagged format with another
1618encoder. First, you create an array with the magic string as first member,
1619the classname as second, and constructor arguments last, encode it as part
1620of your JSON structure, and then:
1621
1622 $json =~ s/\[\s*"XU1peReLzT4ggEllLanBYq4G9VzliwKF"\s*,\s*("([^\\":,]+|\\.|::)*")\s*,/($1)[/g;
1623
1624Again, this has some limitations - the magic string must not be encoded
1625with character escapes, and the constructor arguments must be non-empty.
1626
1627
1628=head1 RFC7158
1629
1630Since this module was written, Google has written a new JSON RFC, RFC
16317158. Unfortunately, this RFC breaks compatibility with both the original
1632JSON specification on www.json.org and RFC4627.
1633
1634As far as I can see, you can get partial compatibility when parsing by
1635using C<< ->allow_nonref >>. However, consider thew security implications
1636of doing so.
1637
1638I haven't decided yet whether to break compatibility with RFC4627 by
1639default (and potentially leave applications insecure), or change the
1640default to follow RFC7158.
1641
1642
1560=head1 THREADS 1643=head1 THREADS
1561 1644
1562This module is I<not> guaranteed to be thread safe and there are no 1645This 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 1646plans to change this until Perl gets thread support (as opposed to the
1564horribly slow so-called "threads" which are simply slow and bloated 1647horribly slow so-called "threads" which are simply slow and bloated

Diff Legend

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