1XS(3) User Contributed Perl Documentation XS(3)
2
6 JSON::XS - JSON serialising/deserialising, done correctly and fast
7 JSON::XS - 正しくて高速な JSON シリアライザ/デシリアライザ
9 (http://fleur.hio.jp/perldoc/mix/lib/JSON/XS.html)
10
12 use JSON::XS;
13 # exported functions, they croak on error
15 # and expect/generate UTF-8
16 $utf8_encoded_json_text = to_json $perl_hash_or_arrayref;
18 $perl_hash_or_arrayref = from_json $utf8_encoded_json_text;
19 # OO-interface
21 $coder = JSON::XS->new->ascii->pretty->allow_nonref;
23 $pretty_printed_unencoded = $coder->encode ($perl_scalar);
24 $perl_scalar = $coder->decode ($unicode_json_text);
25
27 This module converts Perl data structures to JSON and vice versa. Its
28 primary goal is to be correct and its secondary goal is to be fast. To
29 reach the latter goal it was written in C.
30 As this is the n-th-something JSON module on CPAN, what was the reason
32 to write yet another JSON module? While it seems there are many JSON
33 modules, none of them correctly handle all corner cases, and in most
34 cases their maintainers are unresponsive, gone missing, or not listen‐
35 ing to bug reports for other reasons.
36 See COMPARISON, below, for a comparison to some other JSON modules.
38 See MAPPING, below, on how JSON::XS maps perl values to JSON values and
40 vice versa.
41 FEATURES
43 * correct unicode handling
45 This module knows how to handle Unicode, and even documents how and
46 when it does so.
47 * round-trip integrity
49 When you serialise a perl data structure using only datatypes sup‐
50 ported by JSON, the deserialised data structure is identical on the
51 Perl level. (e.g. the string "2.0" doesn't suddenly become "2"
52 just because it looks like a number).
53 * strict checking of JSON correctness
55 There is no guessing, no generating of illegal JSON texts by
56 default, and only JSON is accepted as input by default (the latter
57 is a security feature).
58 * fast
60 Compared to other JSON modules, this module compares favourably in
61 terms of speed, too.
62 * simple to use
64 This module has both a simple functional interface as well as an OO
65 interface.
66 * reasonably versatile output formats
68 You can choose between the most compact guarenteed single-line for‐
69 mat possible (nice for simple line-based protocols), a pure-ascii
70 format (for when your transport is not 8-bit clean, still supports
71 the whole unicode range), or a pretty-printed format (for when you
72 want to read that stuff). Or you can combine those features in
73 whatever way you like.
74
76 The following convinience methods are provided by this module. They are
77 exported by default:
78 $json_text = to_json $perl_scalar
80 Converts the given Perl data structure to a UTF-8 encoded, binary
81 string (that is, the string contains octets only). Croaks on error.
82 This function call is functionally identical to:
84 $json_text = JSON::XS->new->utf8->encode ($perl_scalar)
86 except being faster.
88 $perl_scalar = from_json $json_text
90 The opposite of "to_json": expects an UTF-8 (binary) string and
91 tries to parse that as an UTF-8 encoded JSON text, returning the
92 resulting reference. Croaks on error.
93 This function call is functionally identical to:
95 $perl_scalar = JSON::XS->new->utf8->decode ($json_text)
97 except being faster.
99 $is_boolean = JSON::XS::is_bool $scalar
101 Returns true if the passed scalar represents either JSON::XS::true
102 or JSON::XS::false, two constants that act like 1 and 0, respec‐
103 tively and are used to represent JSON "true" and "false" values in
104 Perl.
105 See MAPPING, below, for more information on how JSON values are
107 mapped to Perl.
108
110 Since this often leads to confusion, here are a few very clear words on
111 how Unicode works in Perl, modulo bugs.
112 1. Perl strings can store characters with ordinal values > 255.
114 This enables you to store unicode characters as single characters
115 in a Perl string - very natural.
116 2. Perl does not associate an encoding with your strings.
118 Unless you force it to, e.g. when matching it against a regex, or
119 printing the scalar to a file, in which case Perl either interprets
120 your string as locale-encoded text, octets/binary, or as Unicode,
121 depending on various settings. In no case is an encoding stored
122 together with your data, it is use that decides encoding, not any
123 magical metadata.
124 3. The internal utf-8 flag has no meaning with regards to the encoding
126 of your string.
127 Just ignore that flag unless you debug a Perl bug, a module written
128 in XS or want to dive into the internals of perl. Otherwise it will
129 only confuse you, as, despite the name, it says nothing about how
130 your string is encoded. You can have unicode strings with that flag
131 set, with that flag clear, and you can have binary data with that
132 flag set and that flag clear. Other possibilities exist, too.
133 If you didn't know about that flag, just the better, pretend it
135 doesn't exist.
136 4. A "Unicode String" is simply a string where each character can be
138 validly interpreted as a Unicode codepoint.
139 If you have UTF-8 encoded data, it is no longer a Unicode string,
140 but a Unicode string encoded in UTF-8, giving you a binary string.
141 5. A string containing "high" (> 255) character values is not a UTF-8
143 string.
144 Its a fact. Learn to live with it.
145 I hope this helps :)
147
149 The object oriented interface lets you configure your own encoding or
150 decoding style, within the limits of supported formats.
151 $json = new JSON::XS
153 Creates a new JSON::XS object that can be used to de/encode JSON
154 strings. All boolean flags described below are by default disabled.
155 The mutators for flags all return the JSON object again and thus
157 calls can be chained:
158 my $json = JSON::XS->new->utf8->space_after->encode ({a => [1,2]})
160 => {"a": [1, 2]}
161 $json = $json->ascii ([$enable])
163 If $enable is true (or missing), then the "encode" method will not
164 generate characters outside the code range 0..127 (which is ASCII).
165 Any unicode characters outside that range will be escaped using
166 either a single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL
167 escape sequence, as per RFC4627. The resulting encoded JSON text
168 can be treated as a native unicode string, an ascii-encoded,
169 latin1-encoded or UTF-8 encoded string, or any other superset of
170 ASCII.
171 If $enable is false, then the "encode" method will not escape Uni‐
173 code characters unless required by the JSON syntax or other flags.
174 This results in a faster and more compact format.
175 The main use for this flag is to produce JSON texts that can be
177 transmitted over a 7-bit channel, as the encoded JSON texts will
178 not contain any 8 bit characters.
179 JSON::XS->new->ascii (1)->encode ([chr 0x10401])
181 => ["\ud801\udc01"]
182 $json = $json->latin1 ([$enable])
184 If $enable is true (or missing), then the "encode" method will
185 encode the resulting JSON text as latin1 (or iso-8859-1), escaping
186 any characters outside the code range 0..255. The resulting string
187 can be treated as a latin1-encoded JSON text or a native unicode
188 string. The "decode" method will not be affected in any way by this
189 flag, as "decode" by default expects unicode, which is a strict
190 superset of latin1.
191 If $enable is false, then the "encode" method will not escape Uni‐
193 code characters unless required by the JSON syntax or other flags.
194 The main use for this flag is efficiently encoding binary data as
196 JSON text, as most octets will not be escaped, resulting in a
197 smaller encoded size. The disadvantage is that the resulting JSON
198 text is encoded in latin1 (and must correctly be treated as such
199 when storing and transfering), a rare encoding for JSON. It is
200 therefore most useful when you want to store data structures known
201 to contain binary data efficiently in files or databases, not when
202 talking to other JSON encoders/decoders.
203 JSON::XS->new->latin1->encode (["\x{89}\x{abc}"]
205 => ["\x{89}\\u0abc"] # (perl syntax, U+abc escaped, U+89 not)
206 $json = $json->utf8 ([$enable])
208 If $enable is true (or missing), then the "encode" method will
209 encode the JSON result into UTF-8, as required by many protocols,
210 while the "decode" method expects to be handled an UTF-8-encoded
211 string. Please note that UTF-8-encoded strings do not contain any
212 characters outside the range 0..255, they are thus useful for byte‐
213 wise/binary I/O. In future versions, enabling this option might
214 enable autodetection of the UTF-16 and UTF-32 encoding families, as
215 described in RFC4627.
216 If $enable is false, then the "encode" method will return the JSON
218 string as a (non-encoded) unicode string, while "decode" expects
219 thus a unicode string. Any decoding or encoding (e.g. to UTF-8 or
220 UTF-16) needs to be done yourself, e.g. using the Encode module.
221 Example, output UTF-16BE-encoded JSON:
223 use Encode;
225 $jsontext = encode "UTF-16BE", JSON::XS->new->encode ($object);
226 Example, decode UTF-32LE-encoded JSON:
228 use Encode;
230 $object = JSON::XS->new->decode (decode "UTF-32LE", $jsontext);
231 $json = $json->pretty ([$enable])
233 This enables (or disables) all of the "indent", "space_before" and
234 "space_after" (and in the future possibly more) flags in one call
235 to generate the most readable (or most compact) form possible.
236 Example, pretty-print some simple structure:
238 my $json = JSON::XS->new->pretty(1)->encode ({a => [1,2]})
240 =>
241 {
242 "a" : [
243 1,
244 2
245 ]
246 }
247 $json = $json->indent ([$enable])
249 If $enable is true (or missing), then the "encode" method will use
250 a multiline format as output, putting every array member or
251 object/hash key-value pair into its own line, identing them prop‐
252 erly.
253 If $enable is false, no newlines or indenting will be produced, and
255 the resulting JSON text is guarenteed not to contain any "new‐
256 lines".
257 This setting has no effect when decoding JSON texts.
259 $json = $json->space_before ([$enable])
261 If $enable is true (or missing), then the "encode" method will add
262 an extra optional space before the ":" separating keys from values
263 in JSON objects.
264 If $enable is false, then the "encode" method will not add any
266 extra space at those places.
267 This setting has no effect when decoding JSON texts. You will also
269 most likely combine this setting with "space_after".
270 Example, space_before enabled, space_after and indent disabled:
272 {"key" :"value"}
274 $json = $json->space_after ([$enable])
276 If $enable is true (or missing), then the "encode" method will add
277 an extra optional space after the ":" separating keys from values
278 in JSON objects and extra whitespace after the "," separating key-
279 value pairs and array members.
280 If $enable is false, then the "encode" method will not add any
282 extra space at those places.
283 This setting has no effect when decoding JSON texts.
285 Example, space_before and indent disabled, space_after enabled:
287 {"key": "value"}
289 $json = $json->relaxed ([$enable])
291 If $enable is true (or missing), then "decode" will accept some
292 extensions to normal JSON syntax (see below). "encode" will not be
293 affected in anyway. Be aware that this option makes you accept
294 invalid JSON texts as if they were valid!. I suggest only to use
295 this option to parse application-specific files written by humans
296 (configuration files, resource files etc.)
297 If $enable is false (the default), then "decode" will only accept
299 valid JSON texts.
300 Currently accepted extensions are:
302 * list items can have an end-comma
304 JSON separates array elements and key-value pairs with commas.
305 This can be annoying if you write JSON texts manually and want
306 to be able to quickly append elements, so this extension
307 accepts comma at the end of such items not just between them:
308 [
310 1,
311 2, <- this comma not normally allowed
312 ]
313 {
314 "k1": "v1",
315 "k2": "v2", <- this comma not normally allowed
316 }
317 * shell-style '#'-comments
319 Whenever JSON allows whitespace, shell-style comments are addi‐
320 tionally allowed. They are terminated by the first carriage-
321 return or line-feed character, after which more white-space and
322 comments are allowed.
323 [
325 1, # this comment not allowed in JSON
326 # neither this one...
327 ]
328 $json = $json->canonical ([$enable])
330 If $enable is true (or missing), then the "encode" method will out‐
331 put JSON objects by sorting their keys. This is adding a compara‐
332 tively high overhead.
333 If $enable is false, then the "encode" method will output key-value
335 pairs in the order Perl stores them (which will likely change
336 between runs of the same script).
337 This option is useful if you want the same data structure to be
339 encoded as the same JSON text (given the same overall settings). If
340 it is disabled, the same hash migh be encoded differently even if
341 contains the same data, as key-value pairs have no inherent order‐
342 ing in Perl.
343 This setting has no effect when decoding JSON texts.
345 $json = $json->allow_nonref ([$enable])
347 If $enable is true (or missing), then the "encode" method can con‐
348 vert a non-reference into its corresponding string, number or null
349 JSON value, which is an extension to RFC4627. Likewise, "decode"
350 will accept those JSON values instead of croaking.
351 If $enable is false, then the "encode" method will croak if it
353 isn't passed an arrayref or hashref, as JSON texts must either be
354 an object or array. Likewise, "decode" will croak if given some‐
355 thing that is not a JSON object or array.
356 Example, encode a Perl scalar as JSON value with enabled
358 "allow_nonref", resulting in an invalid JSON text:
359 JSON::XS->new->allow_nonref->encode ("Hello, World!")
361 => "Hello, World!"
362 $json = $json->allow_blessed ([$enable])
364 If $enable is true (or missing), then the "encode" method will not
365 barf when it encounters a blessed reference. Instead, the value of
366 the convert_blessed option will decide wether "null" ("con‐
367 vert_blessed" disabled or no "to_json" method found) or a represen‐
368 tation of the object ("convert_blessed" enabled and "to_json"
369 method found) is being encoded. Has no effect on "decode".
370 If $enable is false (the default), then "encode" will throw an
372 exception when it encounters a blessed object.
373 $json = $json->convert_blessed ([$enable])
375 If $enable is true (or missing), then "encode", upon encountering a
376 blessed object, will check for the availability of the "TO_JSON"
377 method on the object's class. If found, it will be called in scalar
378 context and the resulting scalar will be encoded instead of the
379 object. If no "TO_JSON" method is found, the value of
380 "allow_blessed" will decide what to do.
381 The "TO_JSON" method may safely call die if it wants. If "TO_JSON"
383 returns other blessed objects, those will be handled in the same
384 way. "TO_JSON" must take care of not causing an endless recursion
385 cycle (== crash) in this case. The name of "TO_JSON" was chosen
386 because other methods called by the Perl core (== not by the user
387 of the object) are usually in upper case letters and to avoid col‐
388 lisions with the "to_json" function.
389 This setting does not yet influence "decode" in any way, but in the
391 future, global hooks might get installed that influence "decode"
392 and are enabled by this setting.
393 If $enable is false, then the "allow_blessed" setting will decide
395 what to do when a blessed object is found.
396 $json = $json->filter_json_object ([$coderef->($hashref)])
398 When $coderef is specified, it will be called from "decode" each
399 time it decodes a JSON object. The only argument is a reference to
400 the newly-created hash. If the code references returns a single
401 scalar (which need not be a reference), this value (i.e. a copy of
402 that scalar to avoid aliasing) is inserted into the deserialised
403 data structure. If it returns an empty list (NOTE: not "undef",
404 which is a valid scalar), the original deserialised hash will be
405 inserted. This setting can slow down decoding considerably.
406 When $coderef is omitted or undefined, any existing callback will
408 be removed and "decode" will not change the deserialised hash in
409 any way.
410 Example, convert all JSON objects into the integer 5:
412 my $js = JSON::XS->new->filter_json_object (sub { 5 });
414 # returns [5]
415 $js->decode ('[{}]')
416 # throw an exception because allow_nonref is not enabled
417 # so a lone 5 is not allowed.
418 $js->decode ('{"a":1, "b":2}');
419 $json = $json->filter_json_single_key_object ($key [=>
421 $coderef->($value)])
422 Works remotely similar to "filter_json_object", but is only called
423 for JSON objects having a single key named $key.
424 This $coderef is called before the one specified via "fil‐
426 ter_json_object", if any. It gets passed the single value in the
427 JSON object. If it returns a single value, it will be inserted into
428 the data structure. If it returns nothing (not even "undef" but the
429 empty list), the callback from "filter_json_object" will be called
430 next, as if no single-key callback were specified.
431 If $coderef is omitted or undefined, the corresponding callback
433 will be disabled. There can only ever be one callback for a given
434 key.
435 As this callback gets called less often then the "fil‐
437 ter_json_object" one, decoding speed will not usually suffer as
438 much. Therefore, single-key objects make excellent targets to seri‐
439 alise Perl objects into, especially as single-key JSON objects are
440 as close to the type-tagged value concept as JSON gets (its basi‐
441 cally an ID/VALUE tuple). Of course, JSON does not support this in
442 any way, so you need to make sure your data never looks like a
443 serialised Perl hash.
444 Typical names for the single object key are "__class_whatever__",
446 or "$__dollars_are_rarely_used__$" or "}ugly_brace_placement", or
447 even things like "__class_md5sum(classname)__", to reduce the risk
448 of clashing with real hashes.
449 Example, decode JSON objects of the form "{ "__widget__" => <id> }"
451 into the corresponding $WIDGET{<id>} object:
452 # return whatever is in $WIDGET{5}:
454 JSON::XS
455 ->new
456 ->filter_json_single_key_object (__widget__ => sub {
457 $WIDGET{ $_[0] }
458 })
459 ->decode ('{"__widget__": 5')
460 # this can be used with a TO_JSON method in some "widget" class
462 # for serialisation to json:
463 sub WidgetBase::TO_JSON {
464 my ($self) = @_;
465 unless ($self->{id}) {
467 $self->{id} = ..get..some..id..;
468 $WIDGET{$self->{id}} = $self;
469 }
470 { __widget__ => $self->{id} }
472 }
473 $json = $json->shrink ([$enable])
475 Perl usually over-allocates memory a bit when allocating space for
476 strings. This flag optionally resizes strings generated by either
477 "encode" or "decode" to their minimum size possible. This can save
478 memory when your JSON texts are either very very long or you have
479 many short strings. It will also try to downgrade any strings to
480 octet-form if possible: perl stores strings internally either in an
481 encoding called UTF-X or in octet-form. The latter cannot store
482 everything but uses less space in general (and some buggy Perl or C
483 code might even rely on that internal representation being used).
484 The actual definition of what shrink does might change in future
486 versions, but it will always try to save space at the expense of
487 time.
488 If $enable is true (or missing), the string returned by "encode"
490 will be shrunk-to-fit, while all strings generated by "decode" will
491 also be shrunk-to-fit.
492 If $enable is false, then the normal perl allocation algorithms are
494 used. If you work with your data, then this is likely to be
495 faster.
496 In the future, this setting might control other things, such as
498 converting strings that look like integers or floats into integers
499 or floats internally (there is no difference on the Perl level),
500 saving space.
501 $json = $json->max_depth ([$maximum_nesting_depth])
503 Sets the maximum nesting level (default 512) accepted while encod‐
504 ing or decoding. If the JSON text or Perl data structure has an
505 equal or higher nesting level then this limit, then the encoder and
506 decoder will stop and croak at that point.
507 Nesting level is defined by number of hash- or arrayrefs that the
509 encoder needs to traverse to reach a given point or the number of
510 "{" or "[" characters without their matching closing parenthesis
511 crossed to reach a given character in a string.
512 Setting the maximum depth to one disallows any nesting, so that
514 ensures that the object is only a single hash/object or array.
515 The argument to "max_depth" will be rounded up to the next highest
517 power of two. If no argument is given, the highest possible setting
518 will be used, which is rarely useful.
519 See SECURITY CONSIDERATIONS, below, for more info on why this is
521 useful.
522 $json = $json->max_size ([$maximum_string_size])
524 Set the maximum length a JSON text may have (in bytes) where decod‐
525 ing is being attempted. The default is 0, meaning no limit. When
526 "decode" is called on a string longer then this number of charac‐
527 ters it will not attempt to decode the string but throw an excep‐
528 tion. This setting has no effect on "encode" (yet).
529 The argument to "max_size" will be rounded up to the next highest
531 power of two (so may be more than requested). If no argument is
532 given, the limit check will be deactivated (same as when 0 is spec‐
533 ified).
534 See SECURITY CONSIDERATIONS, below, for more info on why this is
536 useful.
537 $json_text = $json->encode ($perl_scalar)
539 Converts the given Perl data structure (a simple scalar or a refer‐
540 ence to a hash or array) to its JSON representation. Simple scalars
541 will be converted into JSON string or number sequences, while ref‐
542 erences to arrays become JSON arrays and references to hashes
543 become JSON objects. Undefined Perl values (e.g. "undef") become
544 JSON "null" values. Neither "true" nor "false" values will be gen‐
545 erated.
546 $perl_scalar = $json->decode ($json_text)
548 The opposite of "encode": expects a JSON text and tries to parse
549 it, returning the resulting simple scalar or reference. Croaks on
550 error.
551 JSON numbers and strings become simple Perl scalars. JSON arrays
553 become Perl arrayrefs and JSON objects become Perl hashrefs. "true"
554 becomes 1, "false" becomes 0 and "null" becomes "undef".
555 ($perl_scalar, $characters) = $json->decode_prefix ($json_text)
557 This works like the "decode" method, but instead of raising an
558 exception when there is trailing garbage after the first JSON
559 object, it will silently stop parsing there and return the number
560 of characters consumed so far.
561 This is useful if your JSON texts are not delimited by an outer
563 protocol (which is not the brightest thing to do in the first
564 place) and you need to know where the JSON text ends.
565 JSON::XS->new->decode_prefix ("[1] the tail")
567 => ([], 3)
568
570 This section describes how JSON::XS maps Perl values to JSON values and
571 vice versa. These mappings are designed to "do the right thing" in most
572 circumstances automatically, preserving round-tripping characteristics
573 (what you put in comes out as something equivalent).
574 For the more enlightened: note that in the following descriptions, low‐
576 ercase perl refers to the Perl interpreter, while uppcercase Perl
577 refers to the abstract Perl language itself.
578 JSON -> PERL
580 object
582 A JSON object becomes a reference to a hash in Perl. No ordering of
583 object keys is preserved (JSON does not preserver object key order‐
584 ing itself).
585 array
587 A JSON array becomes a reference to an array in Perl.
588 string
590 A JSON string becomes a string scalar in Perl - Unicode codepoints
591 in JSON are represented by the same codepoints in the Perl string,
592 so no manual decoding is necessary.
593 number
595 A JSON number becomes either an integer, numeric (floating point)
596 or string scalar in perl, depending on its range and any fractional
597 parts. On the Perl level, there is no difference between those as
598 Perl handles all the conversion details, but an integer may take
599 slightly less memory and might represent more values exactly than
600 (floating point) numbers.
601 If the number consists of digits only, JSON::XS will try to repre‐
603 sent it as an integer value. If that fails, it will try to repre‐
604 sent it as a numeric (floating point) value if that is possible
605 without loss of precision. Otherwise it will preserve the number as
606 a string value.
607 Numbers containing a fractional or exponential part will always be
609 represented as numeric (floating point) values, possibly at a loss
610 of precision.
611 This might create round-tripping problems as numbers might become
613 strings, but as Perl is typeless there is no other way to do it.
614 true, false
616 These JSON atoms become "JSON::XS::true" and "JSON::XS::false",
617 respectively. They are overloaded to act almost exactly like the
618 numbers 1 and 0. You can check wether a scalar is a JSON boolean by
619 using the "JSON::XS::is_bool" function.
620 null
622 A JSON null atom becomes "undef" in Perl.
623 PERL -> JSON
625 The mapping from Perl to JSON is slightly more difficult, as Perl is a
627 truly typeless language, so we can only guess which JSON type is meant
628 by a Perl value.
629 hash references
631 Perl hash references become JSON objects. As there is no inherent
632 ordering in hash keys (or JSON objects), they will usually be
633 encoded in a pseudo-random order that can change between runs of
634 the same program but stays generally the same within a single run
635 of a program. JSON::XS can optionally sort the hash keys (deter‐
636 mined by the canonical flag), so the same datastructure will seri‐
637 alise to the same JSON text (given same settings and version of
638 JSON::XS), but this incurs a runtime overhead and is only rarely
639 useful, e.g. when you want to compare some JSON text against
640 another for equality.
641 array references
643 Perl array references become JSON arrays.
644 other references
646 Other unblessed references are generally not allowed and will cause
647 an exception to be thrown, except for references to the integers 0
648 and 1, which get turned into "false" and "true" atoms in JSON. You
649 can also use "JSON::XS::false" and "JSON::XS::true" to improve
650 readability.
651 to_json [\0,JSON::XS::true] # yields [false,true]
653 JSON::XS::true, JSON::XS::false
655 These special values become JSON true and JSON false values,
656 respectively. You can also use "\1" and "\0" directly if you want.
657 blessed objects
659 Blessed objects are not allowed. JSON::XS currently tries to encode
660 their underlying representation (hash- or arrayref), but this be‐
661 haviour might change in future versions.
662 simple scalars
664 Simple Perl scalars (any scalar that is not a reference) are the
665 most difficult objects to encode: JSON::XS will encode undefined
666 scalars as JSON null value, scalars that have last been used in a
667 string context before encoding as JSON strings and anything else as
668 number value:
669 # dump as number
671 to_json [2] # yields [2]
672 to_json [-3.0e17] # yields [-3e+17]
673 my $value = 5; to_json [$value] # yields [5]
674 # used as string, so dump as string
676 print $value;
677 to_json [$value] # yields ["5"]
678 # undef becomes null
680 to_json [undef] # yields [null]
681 You can force the type to be a string by stringifying it:
683 my $x = 3.1; # some variable containing a number
685 "$x"; # stringified
686 $x .= ""; # another, more awkward way to stringify
687 print $x; # perl does it for you, too, quite often
688 You can force the type to be a number by numifying it:
690 my $x = "3"; # some variable containing a string
692 $x += 0; # numify it, ensuring it will be dumped as a number
693 $x *= 1; # same thing, the choise is yours.
694 You can not currently output JSON booleans or force the type in
696 other, less obscure, ways. Tell me if you need this capability.
697
699 As already mentioned, this module was created because none of the
700 existing JSON modules could be made to work correctly. First I will
701 describe the problems (or pleasures) I encountered with various exist‐
702 ing JSON modules, followed by some benchmark values. JSON::XS was
703 designed not to suffer from any of these problems or limitations.
704 JSON 1.07
706 Slow (but very portable, as it is written in pure Perl).
707 Undocumented/buggy Unicode handling (how JSON handles unicode val‐
709 ues is undocumented. One can get far by feeding it unicode strings
710 and doing en-/decoding oneself, but unicode escapes are not working
711 properly).
712 No roundtripping (strings get clobbered if they look like numbers,
714 e.g. the string 2.0 will encode to 2.0 instead of "2.0", and that
715 will decode into the number 2.
716 JSON::PC 0.01
718 Very fast.
719 Undocumented/buggy Unicode handling.
721 No roundtripping.
723 Has problems handling many Perl values (e.g. regex results and
725 other magic values will make it croak).
726 Does not even generate valid JSON ("{1,2}" gets converted to
728 "{1:2}" which is not a valid JSON text.
729 Unmaintained (maintainer unresponsive for many months, bugs are not
731 getting fixed).
732 JSON::Syck 0.21
734 Very buggy (often crashes).
735 Very inflexible (no human-readable format supported, format pretty
737 much undocumented. I need at least a format for easy reading by
738 humans and a single-line compact format for use in a protocol, and
739 preferably a way to generate ASCII-only JSON texts).
740 Completely broken (and confusingly documented) Unicode handling
742 (unicode escapes are not working properly, you need to set Implici‐
743 tUnicode to different values on en- and decoding to get symmetric
744 behaviour).
745 No roundtripping (simple cases work, but this depends on wether the
747 scalar value was used in a numeric context or not).
748 Dumping hashes may skip hash values depending on iterator state.
750 Unmaintained (maintainer unresponsive for many months, bugs are not
752 getting fixed).
753 Does not check input for validity (i.e. will accept non-JSON input
755 and return "something" instead of raising an exception. This is a
756 security issue: imagine two banks transfering money between each
757 other using JSON. One bank might parse a given non-JSON request and
758 deduct money, while the other might reject the transaction with a
759 syntax error. While a good protocol will at least recover, that is
760 extra unnecessary work and the transaction will still not succeed).
761 JSON::DWIW 0.04
763 Very fast. Very natural. Very nice.
764 Undocumented unicode handling (but the best of the pack. Unicode
766 escapes still don't get parsed properly).
767 Very inflexible.
769 No roundtripping.
771 Does not generate valid JSON texts (key strings are often unquoted,
773 empty keys result in nothing being output)
774 Does not check input for validity.
776 JSON and YAML
778 You often hear that JSON is a subset (or a close subset) of YAML. This
780 is, however, a mass hysteria and very far from the truth. In general,
781 there is no way to configure JSON::XS to output a data structure as
782 valid YAML.
783 If you really must use JSON::XS to generate YAML, you should use this
785 algorithm (subject to change in future versions):
786 my $to_yaml = JSON::XS->new->utf8->space_after (1);
788 my $yaml = $to_yaml->encode ($ref) . "\n";
789 This will usually generate JSON texts that also parse as valid YAML.
791 Please note that YAML has hardcoded limits on (simple) object key
792 lengths that JSON doesn't have, so you should make sure that your hash
793 keys are noticably shorter than the 1024 characters YAML allows.
794 There might be other incompatibilities that I am not aware of. In gen‐
796 eral you should not try to generate YAML with a JSON generator or vice
797 versa, or try to parse JSON with a YAML parser or vice versa: chances
798 are high that you will run into severe interoperability problems.
799 SPEED
801 It seems that JSON::XS is surprisingly fast, as shown in the following
803 tables. They have been generated with the help of the "eg/bench" pro‐
804 gram in the JSON::XS distribution, to make it easy to compare on your
805 own system.
806 First comes a comparison between various modules using a very short
808 single-line JSON string:
809 {"method": "handleMessage", "params": ["user1", "we were just talking"], \
811 "id": null, "array":[1,11,234,-5,1e5,1e7, true, false]}
812 It shows the number of encodes/decodes per second (JSON::XS uses the
814 functional interface, while JSON::XS/2 uses the OO interface with
815 pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
816 shrink). Higher is better:
817 Storable ⎪ 15779.925 ⎪ 14169.946 ⎪
819 -----------+------------+------------+
820 module ⎪ encode ⎪ decode ⎪
821 -----------⎪------------⎪------------⎪
822 JSON ⎪ 4990.842 ⎪ 4088.813 ⎪
823 JSON::DWIW ⎪ 51653.990 ⎪ 71575.154 ⎪
824 JSON::PC ⎪ 65948.176 ⎪ 74631.744 ⎪
825 JSON::PP ⎪ 8931.652 ⎪ 3817.168 ⎪
826 JSON::Syck ⎪ 24877.248 ⎪ 27776.848 ⎪
827 JSON::XS ⎪ 388361.481 ⎪ 227951.304 ⎪
828 JSON::XS/2 ⎪ 227951.304 ⎪ 218453.333 ⎪
829 JSON::XS/3 ⎪ 338250.323 ⎪ 218453.333 ⎪
830 Storable ⎪ 16500.016 ⎪ 135300.129 ⎪
831 -----------+------------+------------+
832 That is, JSON::XS is about five times faster than JSON::DWIW on encod‐
834 ing, about three times faster on decoding, and over fourty times faster
835 than JSON, even with pretty-printing and key sorting. It also compares
836 favourably to Storable for small amounts of data.
837 Using a longer test string (roughly 18KB, generated from Yahoo! Locals
839 search API (http://nanoref.com/yahooapis/mgPdGg):
840 module ⎪ encode ⎪ decode ⎪
842 -----------⎪------------⎪------------⎪
843 JSON ⎪ 55.260 ⎪ 34.971 ⎪
844 JSON::DWIW ⎪ 825.228 ⎪ 1082.513 ⎪
845 JSON::PC ⎪ 3571.444 ⎪ 2394.829 ⎪
846 JSON::PP ⎪ 210.987 ⎪ 32.574 ⎪
847 JSON::Syck ⎪ 552.551 ⎪ 787.544 ⎪
848 JSON::XS ⎪ 5780.463 ⎪ 4854.519 ⎪
849 JSON::XS/2 ⎪ 3869.998 ⎪ 4798.975 ⎪
850 JSON::XS/3 ⎪ 5862.880 ⎪ 4798.975 ⎪
851 Storable ⎪ 4445.002 ⎪ 5235.027 ⎪
852 -----------+------------+------------+
853 Again, JSON::XS leads by far (except for Storable which non-surpris‐
855 ingly decodes faster).
856 On large strings containing lots of high unicode characters, some mod‐
858 ules (such as JSON::PC) seem to decode faster than JSON::XS, but the
859 result will be broken due to missing (or wrong) unicode handling. Oth‐
860 ers refuse to decode or encode properly, so it was impossible to pre‐
861 pare a fair comparison table for that case.
862
864 When you are using JSON in a protocol, talking to untrusted potentially
865 hostile creatures requires relatively few measures.
866 First of all, your JSON decoder should be secure, that is, should not
868 have any buffer overflows. Obviously, this module should ensure that
869 and I am trying hard on making that true, but you never know.
870 Second, you need to avoid resource-starving attacks. That means you
872 should limit the size of JSON texts you accept, or make sure then when
873 your resources run out, thats just fine (e.g. by using a separate
874 process that can crash safely). The size of a JSON text in octets or
875 characters is usually a good indication of the size of the resources
876 required to decode it into a Perl structure. While JSON::XS can check
877 the size of the JSON text, it might be too late when you already have
878 it in memory, so you might want to check the size before you accept the
879 string.
880 Third, JSON::XS recurses using the C stack when decoding objects and
882 arrays. The C stack is a limited resource: for instance, on my amd64
883 machine with 8MB of stack size I can decode around 180k nested arrays
884 but only 14k nested JSON objects (due to perl itself recursing deeply
885 on croak to free the temporary). If that is exceeded, the program
886 crashes. to be conservative, the default nesting limit is set to 512.
887 If your process has a smaller stack, you should adjust this setting
888 accordingly with the "max_depth" method.
889 And last but least, something else could bomb you that I forgot to
891 think of. In that case, you get to keep the pieces. I am always open
892 for hints, though...
893 If you are using JSON::XS to return packets to consumption by
895 javascript scripts in a browser you should have a look at
896 <http://jpsykes.com/47/practical-csrf-and-json-security> to see wether
897 you are vulnerable to some common attack vectors (which really are
898 browser design bugs, but it is still you who will have to deal with it,
899 as major browser developers care only for features, not about doing
900 security right).
901
903 This module is not guarenteed to be thread safe and there are no plans
904 to change this until Perl gets thread support (as opposed to the horri‐
905 bly slow so-called "threads" which are simply slow and bloated process
906 simulations - use fork, its much faster, cheaper, better).
907 (It might actually work, but you ahve ben warned).
909
911 While the goal of this module is to be correct, that unfortunately does
912 not mean its bug-free, only that I think its design is bug-free. It is
913 still relatively early in its development. If you keep reporting bugs
914 they will be fixed swiftly, though.
915 Please refrain from using rt.cpan.org or any other bug reporting ser‐
917 vice. I put the contact address into my modules for a reason.
918
920 Marc Lehmann <schmorp@schmorp.de>
921 http://home.schmorp.de/
922perl v5.8.8 2007-07-03 XS(3)