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

Comparing JSON-XS/XS.pm (file contents):
Revision 1.148 by root, Tue Oct 29 00:19:45 2013 UTC vs.
Revision 1.153 by root, Sun Mar 2 20:41:14 2014 UTC

…		…
101		101
102	package JSON::XS;	102	package JSON::XS;
103		103
104	use common::sense;	104	use common::sense;
105		105
106	our $VERSION = '3.0';	106	our $VERSION = 3.01;
107	our @ISA = qw(Exporter);	107	our @ISA = qw(Exporter);
108		108
109	our @EXPORT = qw(encode_json decode_json);	109	our @EXPORT = qw(encode_json decode_json);
110		110
111	use Exporter;	111	use Exporter;
…		…
1129	C<allow_blessed>, C<convert_blessed> and C<allow_tags> settings, which are	1129	C<allow_blessed>, C<convert_blessed> and C<allow_tags> settings, which are
1130	used in this order:	1130	used 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
1136	In this case, C<JSON::XS> uses the L<Types::Serialiser> object	1136	In this case, C<JSON::XS> uses the L<Types::Serialiser> object
1137	serialisation protocol to create a tagged JSON value, using a nonstandard	1137	serialisation protocol to create a tagged JSON value, using a nonstandard
1138	extension to the JSON syntax.	1138	extension to the JSON syntax.
1139		1139
…		…
1145	more). These values and the paclkage/classname of the object will then be	1145	more). These values and the paclkage/classname of the object will then be
1146	encoded as a tagged JSON value in the following format:	1146	encoded as a tagged JSON value in the following format:
1147		1147
1148	("classname")[FREEZE return values...]	1148	("classname")[FREEZE return values...]
1149		1149
		1150	e.g.:
		1151
		1152	("URI")["http://www.google.com/"]
		1153	("MyDate")[2013,10,29]
		1154	("ImageData::JPEG")["Z3...VlCg=="]
		1155
1150	For example, the hypothetical C<My::Object> C<FREEZE> method might use the	1156	For example, the hypothetical C<My::Object> C<FREEZE> method might use the
1151	objects C<type> and C<id> members to encode the object:	1157	objects 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
1161	In this case, the C<TO_JSON> method of the object is invoked in scalar	1167	In this case, the C<TO_JSON> method of the object is invoked in scalar
1162	context. It must return a single scalar that can be directly encoded into	1168	context. It must return a single scalar that can be directly encoded into
1163	JSON. This scalar replaces the object in the JSON text.	1169	JSON. This scalar replaces the object in the JSON text.
1164		1170
…		…
1555	constants. That means that the JSON true and false values will be	1561	constants. That means that the JSON true and false values will be
1556	comaptible to true and false values of iother modules that do the same,	1562	comaptible to true and false values of iother modules that do the same,
1557	such as L<JSON::PP> and L<CBOR::XS>.	1563	such as L<JSON::PP> and L<CBOR::XS>.
1558		1564
1559		1565
		1566	=head1 INTEROPERABILITY WITH OTHER JSON DECODERS
		1567
		1568	As long as you only serialise data that can be directly expressed in JSON,
		1569	C<JSON::XS> is incapable of generating invalid JSON output (modulo bugs,
		1570	but C<JSON::XS> has found more bugs in the official JSON testsuite (1)
		1571	than the official JSON testsuite has found in C<JSON::XS> (0)).
		1572
		1573	When you have trouble decoding JSON generated by this module using other
		1574	decoders, then it is very likely that you have an encoding mismatch or the
		1575	other decoder is broken.
		1576
		1577	When decoding, C<JSON::XS> is strict by default and will likely catch all
		1578	errors. There are currently two settings that change this: C<relaxed>
		1579	makes C<JSON::XS> accept (but not generate) some non-standard extensions,
		1580	and C<allow_tags> will allow you to encode and decode Perl objects, at the
		1581	cost of not outputting valid JSON anymore.
		1582
		1583	=head2 TAGGED VALUE SYNTAX AND STANDARD JSON EN/DECODERS
		1584
		1585	When you use C<allow_tags> to use the extended (and also nonstandard and
		1586	invalid) JSON syntax for serialised objects, and you still want to decode
		1587	the generated When you want to serialise objects, you can run a regex
		1588	to replace the tagged syntax by standard JSON arrays (it only works for
		1589	"normal" packagesnames without comma, newlines or single colons). First,
		1590	the 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
		1598	And here is a less readable version that is easy to adapt to other
		1599	languages:
		1600
		1601	$json =~ s/$\s("([^\\":,]+\|\\.\|::)")\s$\s\[/[$1,/g;
		1602
		1603	Here is an ECMAScript version (same regex):
		1604
		1605	json = json.replace (/$\s("([^\\":,]+\|\\.\|::)")\s$\s\[/g, "[$1,");
		1606
		1607	Since this syntax converts to standard JSON arrays, it might be hard to
		1608	distinguish 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
		1613	And after decoding the JSON text, you could walk the data
		1614	structure looking for arrays with a first element of
		1615	C<XU1peReLzT4ggEllLanBYq4G9VzliwKF>.
		1616
		1617	The same approach cna be used to create the tagged format with another
		1618	encoder. First, you create an array with the magic string as first member,
		1619	the classname as second, and constructor arguments last, encode it as part
		1620	of your JSON structure, and then:
		1621
		1622	$json =~ s/\[\s"XU1peReLzT4ggEllLanBYq4G9VzliwKF"\s,\s("([^\\":,]+\|\\.\|::)")\s*,/($1)[/g;
		1623
		1624	Again, this has some limitations - the magic string must not be encoded
		1625	with character escapes, and the constructor arguments must be non-empty.
		1626
		1627
		1628	=head1 RFC7158
		1629
		1630	Since this module was written, Google has written a new JSON RFC, RFC
		1631	7158. Unfortunately, this RFC breaks compatibility with both the original
		1632	JSON specification on www.json.org and RFC4627.
		1633
		1634	As far as I can see, you can get partial compatibility when parsing by
		1635	using C<< ->allow_nonref >>. However, consider thew security implications
		1636	of doing so.
		1637
		1638	I haven't decided yet whether to break compatibility with RFC4627 by
		1639	default (and potentially leave applications insecure), or change the
		1640	default to follow RFC7158.
		1641
		1642
1560	=head1 THREADS	1643	=head1 THREADS
1561		1644
1562	This module is I<not> guaranteed to be thread safe and there are no	1645	This module is I<not> guaranteed to be thread safe and there are no
1563	plans to change this until Perl gets thread support (as opposed to the	1646	plans to change this until Perl gets thread support (as opposed to the
1564	horribly slow so-called "threads" which are simply slow and bloated	1647	horribly slow so-called "threads" which are simply slow and bloated

Diff Legend

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

Comparing JSON-XS/XS.pm (file contents): Revision 1.148 by root, Tue Oct 29 00:19:45 2013 UTC vs. Revision 1.153 by root, Sun Mar 2 20:41:14 2014 UTC

Diff Legend

Comparing JSON-XS/XS.pm (file contents):
Revision 1.148 by root, Tue Oct 29 00:19:45 2013 UTC vs.
Revision 1.153 by root, Sun Mar 2 20:41:14 2014 UTC