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.2 by root, Thu Mar 22 17:28:50 2007 UTC vs.
Revision 1.3 by root, Thu Mar 22 18:10:29 2007 UTC

… …
111strings. All boolean flags described below are by default I<disabled>. 111strings. All boolean flags described below are by default I<disabled>.
112 112
113The mutators for flags all return the JSON object again and thus calls can 113The mutators for flags all return the JSON object again and thus calls can
114be chained: 114be chained:
115 115
116 my $json = JSON::XS->new->utf8(1)->pretty(1)->encode ({a => [1,2]}) 116 my $json = JSON::XS->new->utf8(1)->space_after(1)->encode ({a => [1,2]})
117 => {"a" : [1, 2]} 117 => {"a": [1, 2]}
118 118
119=item $json = $json->ascii ($enable) 119=item $json = $json->ascii ($enable)
120 120
121If C<$enable> is true, then the C<encode> method will not generate 121If C<$enable> is true, then the C<encode> method will not generate
122characters outside the code range C<0..127>. Any unicode characters 122characters outside the code range C<0..127>. Any unicode characters
123outside that range will be escaped using either a single \uXXXX (BMP 123outside that range will be escaped using either a single \uXXXX (BMP
124characters) or a double \uHHHH\uLLLLL escape sequence, as per RFC4627. 124characters) or a double \uHHHH\uLLLLL escape sequence, as per RFC4627.
125 125
126If C<$enable> is false, then the C<encode> method will not escape Unicode 126If C<$enable> is false, then the C<encode> method will not escape Unicode
127characters unless necessary. 127characters unless necessary.
128
129 JSON::XS->new->ascii (1)->encode (chr 0x10401)
130 => \ud801\udc01
128 131
129=item $json = $json->utf8 ($enable) 132=item $json = $json->utf8 ($enable)
130 133
131If C<$enable> is true, then the C<encode> method will encode the JSON 134If C<$enable> is true, then the C<encode> method will encode the JSON
132string into UTF-8, as required by many protocols, while the C<decode> 135string into UTF-8, as required by many protocols, while the C<decode>
… …
137If C<$enable> is false, then the C<encode> method will return the JSON 140If C<$enable> is false, then the C<encode> method will return the JSON
138string as a (non-encoded) unicode string, while C<decode> expects thus a 141string as a (non-encoded) unicode string, while C<decode> expects thus a
139unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs 142unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs
140to be done yourself, e.g. using the Encode module. 143to be done yourself, e.g. using the Encode module.
141 144
142=item $json = $json->pretty ($enabla) 145=item $json = $json->pretty ($enable)
143 146
144This enables (or disables) all of the C<indent>, C<space_before> and 147This enables (or disables) all of the C<indent>, C<space_before> and
145C<space_after> (and in the future possibly more) settings in one call to 148C<space_after> (and in the future possibly more) flags in one call to
146generate the most readable (or most compact) form possible. 149generate the most readable (or most compact) form possible.
150
151 my $json = JSON::XS->new->pretty(1)->encode ({a => [1,2]})
152 =>
153 {
154 "a" : [
155 1,
156 2
157 ]
158 }
147 159
148=item $json = $json->indent ($enable) 160=item $json = $json->indent ($enable)
149 161
150If C<$enable> is true, then the C<encode> method will use a multiline 162If C<$enable> is true, then the C<encode> method will use a multiline
151format as output, putting every array member or object/hash key-value pair 163format as output, putting every array member or object/hash key-value pair
… …
192the same JSON string (given the same overall settings). If it is disabled, 204the same JSON string (given the same overall settings). If it is disabled,
193the same hash migh be encoded differently even if contains the same data, 205the same hash migh be encoded differently even if contains the same data,
194as key-value pairs have no inherent ordering in Perl. 206as key-value pairs have no inherent ordering in Perl.
195 207
196This setting has no effect when decoding JSON strings. 208This setting has no effect when decoding JSON strings.
209
210=item $json = $json->allow_nonref ($enable)
211
212If C<$enable> is true, then the C<encode> method can convert a
213non-reference into its corresponding string, number or null JSON value,
214which is an extension to RFC4627. Likewise, C<decode> will accept those JSON
215values instead of croaking.
216
217If C<$enable> is false, then the C<encode> method will croak if it isn't
218passed an arrayref or hashref, as JSON strings must either be an object
219or array. Likewise, C<decode> will croak if given something that is not a
220JSON object or array.
197 221
198=item $json_string = $json->encode ($perl_scalar) 222=item $json_string = $json->encode ($perl_scalar)
199 223
200Converts the given Perl data structure (a simple scalar or a reference 224Converts the given Perl data structure (a simple scalar or a reference
201to a hash or array) to its JSON representation. Simple scalars will be 225to a hash or array) to its JSON representation. Simple scalars will be
… …
213Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes 237Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes
214C<1>, C<false> becomes C<0> and C<null> becomes C<undef>. 238C<1>, C<false> becomes C<0> and C<null> becomes C<undef>.
215 239
216=back 240=back
217 241
242=head1 COMPARISON
243
244As already mentioned, this module was created because none of the existing
245JSON modules could be made to work correctly. First I will describe the
246problems (or pleasures) I encountered with various existing JSON modules,
247followed by some benchmark values.
248
249=over 4
250
251=item JSON
252
253Slow (but very portable, as it is written in pure Perl).
254
255Undocumented/buggy Unicode handling (how JSON handles unicode values is
256undocumented. One can get far by feeding it unicode strings and doing
257en-/decoding oneself, but unicode escapes are not working properly).
258
259No roundtripping (strings get clobbered if they look like numbers, e.g.
260the string C<2.0> will encode to C<2.0> instead of C<"2.0">, and that will
261decode into the number 2.
262
263=item JSON::PC
264
265Very fast.
266
267Very inflexible (no human-readable format supported, format pretty much
268undocumented. I need at least a format for easy reading by humans and a
269single-line compact format for use in a protocol, and preferably a way to
270generate ASCII-only JSON strings).
271
272Undocumented/buggy Unicode handling.
273
274No roundtripping.
275
276Has problems handling many Perl values.
277
278Does not even generate valid JSON (C<{1,2}> gets converted to C<{1:2}>
279which is not a valid JSON string.
280
281Unmaintained (maintainer unresponsive for many months, bugs are not
282getting fixed).
283
284=item JSON::Syck
285
286Very buggy (often crashes).
287
288Very inflexible.
289
290Completely broken (and confusingly documented) Unicode handling (unicode
291escapes are not working properly, you need to set ImplicitUnicode to
292I<different> values on en- and decoding to get symmetric behaviour).
293
294No roundtripping (simple cases work, but this depends on wether the scalar
295value was used in a numeric context or not).
296
297Dumping hashes may skip hash values depending on iterator state.
298
299Unmaintained (maintainer unresponsive for many months, bugs are not
300getting fixed).
301
302Does not check input for validity (i.e. will accept non-JSON input and
303return "something" instead of raising an exception. This is a security
304issue: imagine two banks transfering money between each other using
305JSON. One bank might parse a given non-JSON request and deduct money,
306while the other might reject the transaction with a syntax error. While a
307good protocol will at least recover, that is extra unnecessary work and
308the transaction will still not succeed).
309
310=item JSON::DWIW
311
312Very fast. Very natural. Very nice.
313
314Undocumented unicode handling (but the best of the pack. Unicode escapes
315still don't get parsed properly).
316
317Very inflexible.
318
319No roundtripping.
320
321Does not check input for validity.
322
323=back
324
325=head2 SPEED
326
218=cut 327=cut
219 328
2201; 3291;
221 330
222=head1 AUTHOR 331=head1 AUTHOR

Diff Legend

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