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

Comparing JSON-XS/XS.pm (file contents):
Revision 1.145 by root, Tue Oct 29 00:06:40 2013 UTC vs.
Revision 1.151 by root, Tue Oct 29 15:55:49 2013 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;
…		…
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
		472	See L<OBJECT SERIALISATION> for details.
		473
472	If C<$enable> is true (or missing), then the C<encode> method will not	474	If C<$enable> is true (or missing), then the C<encode> method will not
473	barf when it encounters a blessed reference. Instead, the value of the	475	barf when it encounters a blessed reference that it cannot convert
474	B<convert_blessed> option will decide whether C<null> (C<convert_blessed>	476	otherwise. Instead, a JSON C<null> value is encoded instead of the object.
475	disabled or no C<TO_JSON> method found) or a representation of the
476	object (C<convert_blessed> enabled and C<TO_JSON> method found) is being
477	encoded. Has no effect on C<decode>.
478		477
479	If C<$enable> is false (the default), then C<encode> will throw an	478	If C<$enable> is false (the default), then C<encode> will throw an
480	exception when it encounters a blessed object.	479	exception when it encounters a blessed object that it cannot convert
		480	otherwise.
		481
		482	This 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
		488	See L<OBJECT SERIALISATION> for details.
485		489
486	If C<$enable> is true (or missing), then C<encode>, upon encountering a	490	If C<$enable> is true (or missing), then C<encode>, upon encountering a
487	blessed object, will check for the availability of the C<TO_JSON> method	491	blessed object, will check for the availability of the C<TO_JSON> method
488	on the object's class. If found, it will be called in scalar context	492	on the object's class. If found, it will be called in scalar context and
489	and the resulting scalar will be encoded instead of the object. If no	493	the resulting scalar will be encoded instead of the object.
490	C<TO_JSON> method is found, the value of C<allow_blessed> will decide what
491	to do.
492		494
493	The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON>	495	The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON>
494	returns other blessed objects, those will be handled in the same	496	returns other blessed objects, those will be handled in the same
495	way. C<TO_JSON> must take care of not causing an endless recursion cycle	497	way. 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
497	methods called by the Perl core (== not by the user of the object) are	499	methods called by the Perl core (== not by the user of the object) are
498	usually in upper case letters and to avoid collisions with any C<to_json>	500	usually in upper case letters and to avoid collisions with any C<to_json>
499	function or method.	501	function or method.
500		502
501	This setting does not yet influence C<decode> in any way, but in the	503	If C<$enable> is false (the default), then C<encode> will not consider
502	future, global hooks might get installed that influence C<decode> and are	504	this type of conversion.
503	enabled by this setting.
504		505
505	If C<$enable> is false, then the C<allow_blessed> setting will decide what	506	This setting has no effect on C<decode>.
506	to do when a blessed object is found.	507
		508	=item $json = $json->allow_tags ([$enable])
		509
		510	=item $enabled = $json->allow_tags
		511
		512	See L<OBJECT SERIALISATION> for details.
		513
		514	If C<$enable> is true (or missing), then C<encode>, upon encountering a
		515	blessed object, will check for the availability of the C<FREEZE> method on
		516	the object's class. If found, it will be used to serialise the object into
		517	a nonstandard tagged JSON value (that JSON decoders cannot decode).
		518
		519	It also causes C<decode> to parse such tagged JSON values and deserialise
		520	them via a call to the C<THAW> method.
		521
		522	If C<$enable> is false (the default), then C<encode> will not consider
		523	this type of conversion, and tagged JSON values will cause a parse error
		524	in 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
510	When C<$coderef> is specified, it will be called from C<decode> each	528	When C<$coderef> is specified, it will be called from C<decode> each
511	time it decodes a JSON object. The only argument is a reference to the	529	time it decodes a JSON object. The only argument is a reference to the
…		…
999	Another nonstandard extension to the JSON syntax, enabled with the	1017	Another nonstandard extension to the JSON syntax, enabled with the
1000	C<allow_tags> setting, are tagged values. In this implementation, the	1018	C<allow_tags> setting, are tagged values. In this implementation, the
1001	I<tag> must be a perl package/class name encoded as a JSON string, and the	1019	I<tag> must be a perl package/class name encoded as a JSON string, and the
1002	I<value> must be a JSON array encoding optional constructor arguments.	1020	I<value> must be a JSON array encoding optional constructor arguments.
1003		1021
1004	See "OBJECT SERIALISATION", below, for details.	1022	See L<OBJECT SERIALISATION>, below, for details.
1005		1023
1006	=back	1024	=back
1007		1025
1008		1026
1009	=head2 PERL -> JSON	1027	=head2 PERL -> JSON
…		…
1048	directly if you want.	1066	directly if you want.
1049		1067
1050	=item blessed objects	1068	=item blessed objects
1051		1069
1052	Blessed objects are not directly representable in JSON, but C<JSON::XS>	1070	Blessed objects are not directly representable in JSON, but C<JSON::XS>
1053	allows various ways of handling objects. See "OBJECT SERIALISATION",	1071	allows various ways of handling objects. See L<OBJECT SERIALISATION>,
1054	below, for details.	1072	below, for details.
1055		1073
1056	=item simple scalars	1074	=item simple scalars
1057		1075
1058	Simple Perl scalars (any scalar that is not a reference) are the most	1076	Simple Perl scalars (any scalar that is not a reference) are the most
…		…
1111	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
1112	used in this order:	1130	used in this order:
1113		1131
1114	=over 4	1132	=over 4
1115		1133
1116	=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.
1117		1135
1118	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
1119	serialisation protocol to create a tagged JSON value, using a nonstandard	1137	serialisation protocol to create a tagged JSON value, using a nonstandard
1120	extension to the JSON syntax.	1138	extension to the JSON syntax.
1121		1139
…		…
1127	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
1128	encoded as a tagged JSON value in the following format:	1146	encoded as a tagged JSON value in the following format:
1129		1147
1130	("classname")[FREEZE return values...]	1148	("classname")[FREEZE return values...]
1131		1149
		1150	e.g.:
		1151
		1152	("URI")["http://www.google.com/"]
		1153	("MyDate")[2013,10,29]
		1154	("ImageData::JPEG")["Z3...VlCg=="]
		1155
1132	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
1133	objects C<type> and C<id> members to encode the object:	1157	objects C<type> and C<id> members to encode the object:
1134		1158
1135	sub My::Object::FREEZE {	1159	sub My::Object::FREEZE {
1136	my ($self, $serialiser) = @_;	1160	my ($self, $serialiser) = @_;
1137		1161
1138	($self->{type}, $self->{id})	1162	($self->{type}, $self->{id})
1139	}	1163	}
1140		1164
1141	=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.
1142		1166
1143	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
1144	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
1145	JSON. This scalar replaces the object in the JSON text.	1169	JSON. This scalar replaces the object in the JSON text.
1146		1170
…		…
1176	This section only considers the tagged value case: I a tagged JSON object	1200	This section only considers the tagged value case: I a tagged JSON object
1177	is encountered during decoding and C<allow_tags> is disabled, a parse	1201	is encountered during decoding and C<allow_tags> is disabled, a parse
1178	error will result (as if tagged values were not part of the grammar).	1202	error will result (as if tagged values were not part of the grammar).
1179		1203
1180	If C<allow_tags> is enabled, C<JSON::XS> will look up the C<THAW> method	1204	If C<allow_tags> is enabled, C<JSON::XS> will look up the C<THAW> method
1181	of the package/classname used during serialisation. If there is no such	1205	of the package/classname used during serialisation (it will not attempt
		1206	to load the package as a Perl module). If there is no such method, the
1182	method, the decoding will fail with an error.	1207	decoding will fail with an error.
1183		1208
1184	Otherwise, the C<THAW> method is invoked with the classname as first	1209	Otherwise, the C<THAW> method is invoked with the classname as first
1185	argument, the constant string C<JSON> as second argument, and all the	1210	argument, the constant string C<JSON> as second argument, and all the
1186	values from the JSON array (the values originally returned by the	1211	values from the JSON array (the values originally returned by the
1187	C<FREEZE> method) as remaining arguments.	1212	C<FREEZE> method) as remaining arguments.

Diff Legend

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

Comparing JSON-XS/XS.pm (file contents): Revision 1.145 by root, Tue Oct 29 00:06:40 2013 UTC vs. Revision 1.151 by root, Tue Oct 29 15:55:49 2013 UTC

Diff Legend

Comparing JSON-XS/XS.pm (file contents):
Revision 1.145 by root, Tue Oct 29 00:06:40 2013 UTC vs.
Revision 1.151 by root, Tue Oct 29 15:55:49 2013 UTC