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.144 by root, Mon Oct 28 23:19:54 2013 UTC vs.
Revision 1.154 by root, Sun Mar 2 22:09:38 2014 UTC

101 101
102package JSON::XS; 102package JSON::XS;
103 103
104use common::sense; 104use common::sense;
105 105
106our $VERSION = 2.34; 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 L<OBJECT SERIALISATION> for details.
473
472If 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
473barf when it encounters a blessed reference. Instead, the value of the 475barf when it encounters a blessed reference that it cannot convert
474B<convert_blessed> option will decide whether C<null> (C<convert_blessed> 476otherwise. Instead, a JSON C<null> value is encoded instead of the object.
475disabled or no C<TO_JSON> method found) or a representation of the
476object (C<convert_blessed> enabled and C<TO_JSON> method found) is being
477encoded. Has no effect on C<decode>.
478 477
479If C<$enable> is false (the default), then C<encode> will throw an 478If C<$enable> is false (the default), then C<encode> will throw an
480exception when it encounters a blessed object. 479exception when it encounters a blessed object that it cannot convert
480otherwise.
481
482This setting has no effect on C<decode>.
481 483
482=item $json = $json->convert_blessed ([$enable]) 484=item $json = $json->convert_blessed ([$enable])
483 485
484=item $enabled = $json->get_convert_blessed 486=item $enabled = $json->get_convert_blessed
487
488See L<OBJECT SERIALISATION> for details.
485 489
486If 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
487blessed 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
488on the object's class. If found, it will be called in scalar context 492on the object's class. If found, it will be called in scalar context and
489and the resulting scalar will be encoded instead of the object. If no 493the resulting scalar will be encoded instead of the object.
490C<TO_JSON> method is found, the value of C<allow_blessed> will decide what
491to do.
492 494
493The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON> 495The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON>
494returns other blessed objects, those will be handled in the same 496returns other blessed objects, those will be handled in the same
495way. C<TO_JSON> must take care of not causing an endless recursion cycle 497way. C<TO_JSON> must take care of not causing an endless recursion cycle
496(== crash) in this case. The name of C<TO_JSON> was chosen because other 498(== crash) in this case. The name of C<TO_JSON> was chosen because other
497methods called by the Perl core (== not by the user of the object) are 499methods called by the Perl core (== not by the user of the object) are
498usually in upper case letters and to avoid collisions with any C<to_json> 500usually in upper case letters and to avoid collisions with any C<to_json>
499function or method. 501function or method.
500 502
501This setting does not yet influence C<decode> in any way, but in the 503If C<$enable> is false (the default), then C<encode> will not consider
502future, global hooks might get installed that influence C<decode> and are 504this type of conversion.
503enabled by this setting.
504 505
505If C<$enable> is false, then the C<allow_blessed> setting will decide what 506This setting has no effect on C<decode>.
506to do when a blessed object is found. 507
508=item $json = $json->allow_tags ([$enable])
509
510=item $enabled = $json->allow_tags
511
512See L<OBJECT SERIALISATION> for details.
513
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
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).
518
519It also causes C<decode> to parse such tagged JSON values and deserialise
520them via a call to the C<THAW> method.
521
522If C<$enable> is false (the default), then C<encode> will not consider
523this type of conversion, and tagged JSON values will cause a parse error
524in C<decode>, as if tags were not part of the grammar.
507 525
508=item $json = $json->filter_json_object ([$coderef->($hashref)]) 526=item $json = $json->filter_json_object ([$coderef->($hashref)])
509 527
510When C<$coderef> is specified, it will be called from C<decode> each 528When C<$coderef> is specified, it will be called from C<decode> each
511time it decodes a JSON object. The only argument is a reference to the 529time it decodes a JSON object. The only argument is a reference to the
986 1004
987=item null 1005=item null
988 1006
989A JSON null atom becomes C<undef> in Perl. 1007A JSON null atom becomes C<undef> in Perl.
990 1008
1009=item shell-style comments (C<< # I<text> >>)
1010
1011As a nonstandard extension to the JSON syntax that is enabled by the
1012C<relaxed> setting, shell-style comments are allowed. They can start
1013anywhere outside strings and go till the end of the line.
1014
1015=item tagged values (C<< (I<tag>)I<value> >>).
1016
1017Another nonstandard extension to the JSON syntax, enabled with 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
1020I<value> must be a JSON array encoding optional constructor arguments.
1021
1022See L<OBJECT SERIALISATION>, below, for details.
1023
991=back 1024=back
992 1025
993 1026
994=head2 PERL -> JSON 1027=head2 PERL -> JSON
995 1028
1032and JSON false values, respectively. You can also use C<\1> and C<\0> 1065and JSON false values, respectively. You can also use C<\1> and C<\0>
1033directly if you want. 1066directly if you want.
1034 1067
1035=item blessed objects 1068=item blessed objects
1036 1069
1037Blessed objects are not directly representable in JSON. See the 1070Blessed objects are not directly representable in JSON, but C<JSON::XS>
1038C<allow_blessed> and C<convert_blessed> methods on various options on 1071allows various ways of handling objects. See L<OBJECT SERIALISATION>,
1039how to deal with this: basically, you can choose between throwing an 1072below, for details.
1040exception, encoding the reference as if it weren't blessed, or provide
1041your own serialiser method.
1042 1073
1043=item simple scalars 1074=item simple scalars
1044 1075
1045Simple 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
1046difficult objects to encode: JSON::XS will encode undefined scalars as 1077difficult objects to encode: JSON::XS will encode undefined scalars as
1082extensions to the floating point numbers of your platform, such as 1113extensions to the floating point numbers of your platform, such as
1083infinities or NaN's - these cannot be represented in JSON, and it is an 1114infinities or NaN's - these cannot be represented in JSON, and it is an
1084error to pass those in. 1115error to pass those in.
1085 1116
1086=back 1117=back
1118
1119=head2 OBJECT SERIALISATION
1120
1121As JSON cannot directly represent Perl objects, you have to choose between
1122a pure JSON representation (without the ability to deserialise the object
1123automatically again), and a nonstandard extension to the JSON syntax,
1124tagged values.
1125
1126=head3 SERIALISATION
1127
1128What happens when C<JSON::XS> encounters a Perl object depends on the
1129C<allow_blessed>, C<convert_blessed> and C<allow_tags> settings, which are
1130used in this order:
1131
1132=over 4
1133
1134=item 1. C<allow_tags> is enabled and the object has a C<FREEZE> method.
1135
1136In this case, C<JSON::XS> uses the L<Types::Serialiser> object
1137serialisation protocol to create a tagged JSON value, using a nonstandard
1138extension to the JSON syntax.
1139
1140This works by invoking the C<FREEZE> method on the object, with the first
1141argument being the object to serialise, and the second argument being the
1142constant string C<JSON> to distinguish it from other serialisers.
1143
1144The C<FREEZE> method can return any number of values (i.e. zero or
1145more). These values and the paclkage/classname of the object will then be
1146encoded as a tagged JSON value in the following format:
1147
1148 ("classname")[FREEZE return values...]
1149
1150e.g.:
1151
1152 ("URI")["http://www.google.com/"]
1153 ("MyDate")[2013,10,29]
1154 ("ImageData::JPEG")["Z3...VlCg=="]
1155
1156For example, the hypothetical C<My::Object> C<FREEZE> method might use the
1157objects C<type> and C<id> members to encode the object:
1158
1159 sub My::Object::FREEZE {
1160 my ($self, $serialiser) = @_;
1161
1162 ($self->{type}, $self->{id})
1163 }
1164
1165=item 2. C<convert_blessed> is enabled and the object has a C<TO_JSON> method.
1166
1167In this case, the C<TO_JSON> method of the object is invoked in scalar
1168context. It must return a single scalar that can be directly encoded into
1169JSON. This scalar replaces the object in the JSON text.
1170
1171For example, the following C<TO_JSON> method will convert all L<URI>
1172objects to JSON strings when serialised. The fatc that these values
1173originally were L<URI> objects is lost.
1174
1175 sub URI::TO_JSON {
1176 my ($uri) = @_;
1177 $uri->as_string
1178 }
1179
1180=item 3. C<allow_blessed> is enabled.
1181
1182The object will be serialised as a JSON null value.
1183
1184=item 4. none of the above
1185
1186If none of the settings are enabled or the respective methods are missing,
1187C<JSON::XS> throws an exception.
1188
1189=back
1190
1191=head3 DESERIALISATION
1192
1193For deserialisation there are only two cases to consider: either
1194nonstandard tagging was used, in which case C<allow_tags> decides,
1195or objects cannot be automatically be deserialised, in which
1196case you can use postprocessing or the C<filter_json_object> or
1197C<filter_json_single_key_object> callbacks to get some real objects our of
1198your JSON.
1199
1200This section only considers the tagged value case: I a tagged JSON object
1201is encountered during decoding and C<allow_tags> is disabled, a parse
1202error will result (as if tagged values were not part of the grammar).
1203
1204If C<allow_tags> is enabled, C<JSON::XS> will look up the C<THAW> method
1205of the package/classname used during serialisation (it will not attempt
1206to load the package as a Perl module). If there is no such method, the
1207decoding will fail with an error.
1208
1209Otherwise, the C<THAW> method is invoked with the classname as first
1210argument, the constant string C<JSON> as second argument, and all the
1211values from the JSON array (the values originally returned by the
1212C<FREEZE> method) as remaining arguments.
1213
1214The method must then return the object. While technically you can return
1215any Perl scalar, you might have to enable the C<enable_nonref> setting to
1216make that work in all cases, so better return an actual blessed reference.
1217
1218As an example, let's implement a C<THAW> function that regenerates the
1219C<My::Object> from the C<FREEZE> example earlier:
1220
1221 sub My::Object::THAW {
1222 my ($class, $serialiser, $type, $id) = @_;
1223
1224 $class->new (type => $type, id => $id)
1225 }
1087 1226
1088 1227
1089=head1 ENCODING/CODESET FLAG NOTES 1228=head1 ENCODING/CODESET FLAG NOTES
1090 1229
1091The interested reader might have seen a number of flags that signify 1230The interested reader might have seen a number of flags that signify
1422constants. That means that the JSON true and false values will be 1561constants. That means that the JSON true and false values will be
1423comaptible 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,
1424such as L<JSON::PP> and L<CBOR::XS>. 1563such as L<JSON::PP> and L<CBOR::XS>.
1425 1564
1426 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 can 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
1427=head1 THREADS 1643=head1 THREADS
1428 1644
1429This 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
1430plans 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
1431horribly 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