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

Comparing JSON-XS/XS.pm (file contents):
Revision 1.143 by root, Fri Oct 25 20:02: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;
112	use XSLoader;	112	use XSLoader;
		113
		114	use Types::Serialiser ();
113		115
114	=head1 FUNCTIONAL INTERFACE	116	=head1 FUNCTIONAL INTERFACE
115		117
116	The following convenience methods are provided by this module. They are	118	The following convenience methods are provided by this module. They are
117	exported by default:	119	exported by default:
…		…
138	This function call is functionally identical to:	140	This function call is functionally identical to:
139		141
140	$perl_scalar = JSON::XS->new->utf8->decode ($json_text)	142	$perl_scalar = JSON::XS->new->utf8->decode ($json_text)
141		143
142	Except being faster.	144	Except being faster.
143
144	=item $is_boolean = JSON::XS::is_bool $scalar
145
146	Returns true if the passed scalar represents either JSON::XS::true or
147	JSON::XS::false, two constants that act like C<1> and C<0>, respectively
148	and are used to represent JSON C<true> and C<false> values in Perl.
149
150	See MAPPING, below, for more information on how JSON values are mapped to
151	Perl.
152		145
153	=back	146	=back
154		147
155		148
156	=head1 A FEW NOTES ON UNICODE AND PERL	149	=head1 A FEW NOTES ON UNICODE AND PERL
…		…
983	floating point, JSON::XS only guarantees precision up to but not including	976	floating point, JSON::XS only guarantees precision up to but not including
984	the least significant bit.	977	the least significant bit.
985		978
986	=item true, false	979	=item true, false
987		980
988	These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>,	981	These JSON atoms become C<Types::Serialiser::true> and
989	respectively. They are overloaded to act almost exactly like the numbers	982	C<Types::Serialiser::false>, respectively. They are overloaded to act
990	C<1> and C<0>. You can check whether a scalar is a JSON boolean by using	983	almost exactly like the numbers C<1> and C<0>. You can check whether
991	the C<JSON::XS::is_bool> function.	984	a scalar is a JSON boolean by using the C<Types::Serialiser::is_bool>
		985	function (after C<use Types::Serialier>, of course).
992		986
993	=item null	987	=item null
994		988
995	A JSON null atom becomes C<undef> in Perl.	989	A JSON null atom becomes C<undef> in Perl.
		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.
996		1005
997	=back	1006	=back
998		1007
999		1008
1000	=head2 PERL -> JSON	1009	=head2 PERL -> JSON
…		…
1021		1030
1022	=item other references	1031	=item other references
1023		1032
1024	Other unblessed references are generally not allowed and will cause an	1033	Other unblessed references are generally not allowed and will cause an
1025	exception to be thrown, except for references to the integers C<0> and	1034	exception to be thrown, except for references to the integers C<0> and
1026	C<1>, which get turned into C<false> and C<true> atoms in JSON. You can	1035	C<1>, which get turned into C<false> and C<true> atoms in JSON.
1027	also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability.
1028		1036
		1037	Since C<JSON::XS> uses the boolean model from L<Types::Serialiser>, you
		1038	can also C<use Types::Serialiser> and then use C<Types::Serialiser::false>
		1039	and C<Types::Serialiser::true> to improve readability.
		1040
		1041	use Types::Serialiser;
1029	encode_json [\0, JSON::XS::true] # yields [false,true]	1042	encode_json [\0, Types::Serialiser::true] # yields [false,true]
1030		1043
1031	=item JSON::XS::true, JSON::XS::false	1044	=item Types::Serialiser::true, Types::Serialiser::false
1032		1045
1033	These special values become JSON true and JSON false values,	1046	These special values from the L<Types::Serialiser> module become JSON true
1034	respectively. You can also use C<\1> and C<\0> directly if you want.	1047	and JSON false values, respectively. You can also use C<\1> and C<\0>
		1048	directly if you want.
1035		1049
1036	=item blessed objects	1050	=item blessed objects
1037		1051
1038	Blessed objects are not directly representable in JSON. See the	1052	Blessed objects are not directly representable in JSON, but C<JSON::XS>
1039	C<allow_blessed> and C<convert_blessed> methods on various options on	1053	allows various ways of handling objects. See "OBJECT SERIALISATION",
1040	how to deal with this: basically, you can choose between throwing an	1054	below, for details.
1041	exception, encoding the reference as if it weren't blessed, or provide
1042	your own serialiser method.
1043		1055
1044	=item simple scalars	1056	=item simple scalars
1045		1057
1046	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
1047	difficult objects to encode: JSON::XS will encode undefined scalars as	1059	difficult objects to encode: JSON::XS will encode undefined scalars as
…		…
1083	extensions to the floating point numbers of your platform, such as	1095	extensions to the floating point numbers of your platform, such as
1084	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
1085	error to pass those in.	1097	error to pass those in.
1086		1098
1087	=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	}
1088		1201
1089		1202
1090	=head1 ENCODING/CODESET FLAG NOTES	1203	=head1 ENCODING/CODESET FLAG NOTES
1091		1204
1092	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
…		…
1415	are browser design bugs, but it is still you who will have to deal with	1528	are browser design bugs, but it is still you who will have to deal with
1416	it, as major browser developers care only for features, not about getting	1529	it, as major browser developers care only for features, not about getting
1417	security right).	1530	security right).
1418		1531
1419		1532
		1533	=head1 INTEROPERABILITY WITH OTHER MODULES
		1534
		1535	C<JSON::XS> uses the L<Types::Serialiser> module to provide boolean
		1536	constants. That means that the JSON true and false values will be
		1537	comaptible to true and false values of iother modules that do the same,
		1538	such as L<JSON::PP> and L<CBOR::XS>.
		1539
		1540
1420	=head1 THREADS	1541	=head1 THREADS
1421		1542
1422	This module is I<not> guaranteed to be thread safe and there are no	1543	This module is I<not> guaranteed to be thread safe and there are no
1423	plans to change this until Perl gets thread support (as opposed to the	1544	plans to change this until Perl gets thread support (as opposed to the
1424	horribly slow so-called "threads" which are simply slow and bloated	1545	horribly slow so-called "threads" which are simply slow and bloated
…		…
1454	Please refrain from using rt.cpan.org or any other bug reporting	1575	Please refrain from using rt.cpan.org or any other bug reporting
1455	service. I put the contact address into my modules for a reason.	1576	service. I put the contact address into my modules for a reason.
1456		1577
1457	=cut	1578	=cut
1458		1579
1459	our $true = do { bless \(my $dummy = 1), "JSON::XS::Boolean" };	1580	BEGIN {
1460	our $false = do { bless \(my $dummy = 0), "JSON::XS::Boolean" };	1581	*true = \$Types::Serialiser::true;
		1582	*true = \&Types::Serialiser::true;
		1583	*false = \$Types::Serialiser::false;
		1584	*false = \&Types::Serialiser::false;
		1585	*is_bool = \&Types::Serialiser::is_bool;
1461		1586
1462	sub true() { $true }	1587	JSON::XS::Boolean:: = Types::Serialiser::Boolean::;
1463	sub false() { $false }
1464
1465	sub is_bool($) {
1466	UNIVERSAL::isa $_[0], "JSON::XS::Boolean"
1467	# or UNIVERSAL::isa $_[0], "JSON::Literal"
1468	}	1588	}
1469		1589
1470	XSLoader::load "JSON::XS", $VERSION;	1590	XSLoader::load "JSON::XS", $VERSION;
1471
1472	package JSON::XS::Boolean;
1473
1474	use overload
1475	"0+" => sub { ${$_[0]} },
1476	"++" => sub { $_[0] = ${$_[0]} + 1 },
1477	"--" => sub { $_[0] = ${$_[0]} - 1 },
1478	fallback => 1;
1479
1480	1;
1481		1591
1482	=head1 SEE ALSO	1592	=head1 SEE ALSO
1483		1593
1484	The F<json_xs> command line utility for quick experiments.	1594	The F<json_xs> command line utility for quick experiments.
1485		1595
…		…
1488	Marc Lehmann <schmorp@schmorp.de>	1598	Marc Lehmann <schmorp@schmorp.de>
1489	http://home.schmorp.de/	1599	http://home.schmorp.de/
1490		1600
1491	=cut	1601	=cut
1492		1602
		1603	1
		1604

Diff Legend

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

Comparing JSON-XS/XS.pm (file contents): Revision 1.143 by root, Fri Oct 25 20:02: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.143 by root, Fri Oct 25 20:02:54 2013 UTC vs.
Revision 1.145 by root, Tue Oct 29 00:06:40 2013 UTC