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

Comparing JSON-XS/XS.pm (file contents):
Revision 1.144 by root, Mon Oct 28 23:19:54 2013 UTC vs.
Revision 1.145 by root, Tue Oct 29 00:06:40 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 = 2.34;	106	our $VERSION = '3.0';
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;
…		…
986		986
987	=item null	987	=item null
988		988
989	A JSON null atom becomes C<undef> in Perl.	989	A JSON null atom becomes C<undef> in Perl.
990		990
		991	=item shell-style comments (C<< # I<text> >>)
		992
		993	As a nonstandard extension to the JSON syntax that is enabled by the
		994	C<relaxed> setting, shell-style comments are allowed. They can start
		995	anywhere outside strings and go till the end of the line.
		996
		997	=item tagged values (C<< (I<tag>)I<value> >>).
		998
		999	Another nonstandard extension to the JSON syntax, enabled with the
		1000	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
		1002	I<value> must be a JSON array encoding optional constructor arguments.
		1003
		1004	See "OBJECT SERIALISATION", below, for details.
		1005
991	=back	1006	=back
992		1007
993		1008
994	=head2 PERL -> JSON	1009	=head2 PERL -> JSON
995		1010
…		…
1032	and JSON false values, respectively. You can also use C<\1> and C<\0>	1047	and JSON false values, respectively. You can also use C<\1> and C<\0>
1033	directly if you want.	1048	directly if you want.
1034		1049
1035	=item blessed objects	1050	=item blessed objects
1036		1051
1037	Blessed objects are not directly representable in JSON. See the	1052	Blessed objects are not directly representable in JSON, but C<JSON::XS>
1038	C<allow_blessed> and C<convert_blessed> methods on various options on	1053	allows various ways of handling objects. See "OBJECT SERIALISATION",
1039	how to deal with this: basically, you can choose between throwing an	1054	below, for details.
1040	exception, encoding the reference as if it weren't blessed, or provide
1041	your own serialiser method.
1042		1055
1043	=item simple scalars	1056	=item simple scalars
1044		1057
1045	Simple Perl scalars (any scalar that is not a reference) are the most	1058	Simple Perl scalars (any scalar that is not a reference) are the most
1046	difficult objects to encode: JSON::XS will encode undefined scalars as	1059	difficult objects to encode: JSON::XS will encode undefined scalars as
…		…
1082	extensions to the floating point numbers of your platform, such as	1095	extensions to the floating point numbers of your platform, such as
1083	infinities or NaN's - these cannot be represented in JSON, and it is an	1096	infinities or NaN's - these cannot be represented in JSON, and it is an
1084	error to pass those in.	1097	error to pass those in.
1085		1098
1086	=back	1099	=back
		1100
		1101	=head2 OBJECT SERIALISATION
		1102
		1103	As JSON cannot directly represent Perl objects, you have to choose between
		1104	a pure JSON representation (without the ability to deserialise the object
		1105	automatically again), and a nonstandard extension to the JSON syntax,
		1106	tagged values.
		1107
		1108	=head3 SERIALISATION
		1109
		1110	What happens when C<JSON::XS> encounters a Perl object depends on the
		1111	C<allow_blessed>, C<convert_blessed> and C<allow_tags> settings, which are
		1112	used in this order:
		1113
		1114	=over 4
		1115
		1116	=item 1. C<allow_tags> is enabled and object has a C<FREEZE> method.
		1117
		1118	In this case, C<JSON::XS> uses the L<Types::Serialiser> object
		1119	serialisation protocol to create a tagged JSON value, using a nonstandard
		1120	extension to the JSON syntax.
		1121
		1122	This works by invoking the C<FREEZE> method on the object, with the first
		1123	argument being the object to serialise, and the second argument being the
		1124	constant string C<JSON> to distinguish it from other serialisers.
		1125
		1126	The C<FREEZE> method can return any number of values (i.e. zero or
		1127	more). These values and the paclkage/classname of the object will then be
		1128	encoded as a tagged JSON value in the following format:
		1129
		1130	("classname")[FREEZE return values...]
		1131
		1132	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:
		1134
		1135	sub My::Object::FREEZE {
		1136	my ($self, $serialiser) = @_;
		1137
		1138	($self->{type}, $self->{id})
		1139	}
		1140
		1141	=item 2. C<convert_blessed> is enabled and object has a C<TO_JSON> method.
		1142
		1143	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
		1145	JSON. This scalar replaces the object in the JSON text.
		1146
		1147	For example, the following C<TO_JSON> method will convert all L<URI>
		1148	objects to JSON strings when serialised. The fatc that these values
		1149	originally were L<URI> objects is lost.
		1150
		1151	sub URI::TO_JSON {
		1152	my ($uri) = @_;
		1153	$uri->as_string
		1154	}
		1155
		1156	=item 3. C<allow_blessed> is enabled.
		1157
		1158	The object will be serialised as a JSON null value.
		1159
		1160	=item 4. none of the above
		1161
		1162	If none of the settings are enabled or the respective methods are missing,
		1163	C<JSON::XS> throws an exception.
		1164
		1165	=back
		1166
		1167	=head3 DESERIALISATION
		1168
		1169	For deserialisation there are only two cases to consider: either
		1170	nonstandard tagging was used, in which case C<allow_tags> decides,
		1171	or objects cannot be automatically be deserialised, in which
		1172	case you can use postprocessing or the C<filter_json_object> or
		1173	C<filter_json_single_key_object> callbacks to get some real objects our of
		1174	your JSON.
		1175
		1176	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
		1178	error will result (as if tagged values were not part of the grammar).
		1179
		1180	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
		1182	method, the decoding will fail with an error.
		1183
		1184	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
		1186	values from the JSON array (the values originally returned by the
		1187	C<FREEZE> method) as remaining arguments.
		1188
		1189	The method must then return the object. While technically you can return
		1190	any Perl scalar, you might have to enable the C<enable_nonref> setting to
		1191	make that work in all cases, so better return an actual blessed reference.
		1192
		1193	As an example, let's implement a C<THAW> function that regenerates the
		1194	C<My::Object> from the C<FREEZE> example earlier:
		1195
		1196	sub My::Object::THAW {
		1197	my ($class, $serialiser, $type, $id) = @_;
		1198
		1199	$class->new (type => $type, id => $id)
		1200	}
1087		1201
1088		1202
1089	=head1 ENCODING/CODESET FLAG NOTES	1203	=head1 ENCODING/CODESET FLAG NOTES
1090		1204
1091	The interested reader might have seen a number of flags that signify	1205	The interested reader might have seen a number of flags that signify

Diff Legend

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

Comparing JSON-XS/XS.pm (file contents): Revision 1.144 by root, Mon Oct 28 23:19:54 2013 UTC vs. Revision 1.145 by root, Tue Oct 29 00:06:40 2013 UTC

Diff Legend

Comparing JSON-XS/XS.pm (file contents):
Revision 1.144 by root, Mon Oct 28 23:19:54 2013 UTC vs.
Revision 1.145 by root, Tue Oct 29 00:06:40 2013 UTC