1=head1 NAME 2 3JSON::XS - JSON serialising/deserialising, done correctly and fast 4 5=encoding utf-8 6 7JSON::XS - 正しくて高速な JSON シリアライザ/デシリアライザ 8 (http://fleur.hio.jp/perldoc/mix/lib/JSON/XS.html) 9 10=head1 SYNOPSIS 11 12 use JSON::XS; 13 14 # exported functions, they croak on error 15 # and expect/generate UTF-8 16 17 $utf8_encoded_json_text = encode_json $perl_hash_or_arrayref; 18 $perl_hash_or_arrayref = decode_json $utf8_encoded_json_text; 19 20 # OO-interface 21 22 $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 26 # Note that JSON version 2.0 and above will automatically use JSON::XS 27 # if available, at virtually no speed overhead either, so you should 28 # be able to just: 29 30 use JSON; 31 32 # and do the same things, except that you have a pure-perl fallback now. 33 34=head1 DESCRIPTION 35 36This module converts Perl data structures to JSON and vice versa. Its 37primary goal is to be I<correct> and its secondary goal is to be 38I<fast>. To reach the latter goal it was written in C. 39 40Beginning with version 2.0 of the JSON module, when both JSON and 41JSON::XS are installed, then JSON will fall back on JSON::XS (this can be 42overridden) with no overhead due to emulation (by inheriting constructor 43and methods). If JSON::XS is not available, it will fall back to the 44compatible JSON::PP module as backend, so using JSON instead of JSON::XS 45gives you a portable JSON API that can be fast when you need and doesn't 46require a C compiler when that is a problem. 47 48As this is the n-th-something JSON module on CPAN, what was the reason 49to write yet another JSON module? While it seems there are many JSON 50modules, none of them correctly handle all corner cases, and in most cases 51their maintainers are unresponsive, gone missing, or not listening to bug 52reports for other reasons. 53 54See MAPPING, below, on how JSON::XS maps perl values to JSON values and 55vice versa. 56 57=head2 FEATURES 58 59=over 4 60 61=item * correct Unicode handling 62 63This module knows how to handle Unicode, documents how and when it does 64so, and even documents what "correct" means. 65 66=item * round-trip integrity 67 68When you serialise a perl data structure using only data types supported 69by JSON and Perl, the deserialised data structure is identical on the Perl 70level. (e.g. the string "2.0" doesn't suddenly become "2" just because 71it looks like a number). There I<are> minor exceptions to this, read the 72MAPPING section below to learn about those. 73 74=item * strict checking of JSON correctness 75 76There is no guessing, no generating of illegal JSON texts by default, 77and only JSON is accepted as input by default (the latter is a security 78feature). 79 80=item * fast 81 82Compared to other JSON modules and other serialisers such as Storable, 83this module usually compares favourably in terms of speed, too. 84 85=item * simple to use 86 87This module has both a simple functional interface as well as an object 88oriented interface. 89 90=item * reasonably versatile output formats 91 92You can choose between the most compact guaranteed-single-line format 93possible (nice for simple line-based protocols), a pure-ASCII format 94(for when your transport is not 8-bit clean, still supports the whole 95Unicode range), or a pretty-printed format (for when you want to read that 96stuff). Or you can combine those features in whatever way you like. 97 98=back 99 100=cut 101 102package JSON::XS; 103 104use common::sense; 105 106our $VERSION = 3.01; 107our @ISA = qw(Exporter); 108 109our @EXPORT = qw(encode_json decode_json); 110 111use Exporter; 112use XSLoader; 113 114use Types::Serialiser (); 115 116=head1 FUNCTIONAL INTERFACE 117 118The following convenience methods are provided by this module. They are 119exported by default: 120 121=over 4 122 123=item $json_text = encode_json $perl_scalar 124 125Converts the given Perl data structure to a UTF-8 encoded, binary string 126(that is, the string contains octets only). Croaks on error. 127 128This function call is functionally identical to: 129 130 $json_text = JSON::XS->new->utf8->encode ($perl_scalar) 131 132Except being faster. 133 134=item $perl_scalar = decode_json $json_text 135 136The opposite of C<encode_json>: expects an UTF-8 (binary) string and tries 137to parse that as an UTF-8 encoded JSON text, returning the resulting 138reference. Croaks on error. 139 140This function call is functionally identical to: 141 142 $perl_scalar = JSON::XS->new->utf8->decode ($json_text) 143 144Except being faster. 145 146=back 147 148 149=head1 A FEW NOTES ON UNICODE AND PERL 150 151Since this often leads to confusion, here are a few very clear words on 152how Unicode works in Perl, modulo bugs. 153 154=over 4 155 156=item 1. Perl strings can store characters with ordinal values > 255. 157 158This enables you to store Unicode characters as single characters in a 159Perl string - very natural. 160 161=item 2. Perl does I<not> associate an encoding with your strings. 162 163... until you force it to, e.g. when matching it against a regex, or 164printing the scalar to a file, in which case Perl either interprets your 165string as locale-encoded text, octets/binary, or as Unicode, depending 166on various settings. In no case is an encoding stored together with your 167data, it is I<use> that decides encoding, not any magical meta data. 168 169=item 3. The internal utf-8 flag has no meaning with regards to the 170encoding of your string. 171 172Just ignore that flag unless you debug a Perl bug, a module written in 173XS or want to dive into the internals of perl. Otherwise it will only 174confuse you, as, despite the name, it says nothing about how your string 175is encoded. You can have Unicode strings with that flag set, with that 176flag clear, and you can have binary data with that flag set and that flag 177clear. Other possibilities exist, too. 178 179If you didn't know about that flag, just the better, pretend it doesn't 180exist. 181 182=item 4. A "Unicode String" is simply a string where each character can be 183validly interpreted as a Unicode code point. 184 185If you have UTF-8 encoded data, it is no longer a Unicode string, but a 186Unicode string encoded in UTF-8, giving you a binary string. 187 188=item 5. A string containing "high" (> 255) character values is I<not> a UTF-8 string. 189 190It's a fact. Learn to live with it. 191 192=back 193 194I hope this helps :) 195 196 197=head1 OBJECT-ORIENTED INTERFACE 198 199The object oriented interface lets you configure your own encoding or 200decoding style, within the limits of supported formats. 201 202=over 4 203 204=item $json = new JSON::XS 205 206Creates a new JSON::XS object that can be used to de/encode JSON 207strings. All boolean flags described below are by default I<disabled>. 208 209The mutators for flags all return the JSON object again and thus calls can 210be chained: 211 212 my $json = JSON::XS->new->utf8->space_after->encode ({a => [1,2]}) 213 => {"a": [1, 2]} 214 215=item $json = $json->ascii ([$enable]) 216 217=item $enabled = $json->get_ascii 218 219If C<$enable> is true (or missing), then the C<encode> method will not 220generate characters outside the code range C<0..127> (which is ASCII). Any 221Unicode characters outside that range will be escaped using either a 222single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence, 223as per RFC4627. The resulting encoded JSON text can be treated as a native 224Unicode string, an ascii-encoded, latin1-encoded or UTF-8 encoded string, 225or any other superset of ASCII. 226 227If C<$enable> is false, then the C<encode> method will not escape Unicode 228characters unless required by the JSON syntax or other flags. This results 229in a faster and more compact format. 230 231See also the section I<ENCODING/CODESET FLAG NOTES> later in this 232document. 233 234The main use for this flag is to produce JSON texts that can be 235transmitted over a 7-bit channel, as the encoded JSON texts will not 236contain any 8 bit characters. 237 238 JSON::XS->new->ascii (1)->encode ([chr 0x10401]) 239 => ["\ud801\udc01"] 240 241=item $json = $json->latin1 ([$enable]) 242 243=item $enabled = $json->get_latin1 244 245If C<$enable> is true (or missing), then the C<encode> method will encode 246the resulting JSON text as latin1 (or iso-8859-1), escaping any characters 247outside the code range C<0..255>. The resulting string can be treated as a 248latin1-encoded JSON text or a native Unicode string. The C<decode> method 249will not be affected in any way by this flag, as C<decode> by default 250expects Unicode, which is a strict superset of latin1. 251 252If C<$enable> is false, then the C<encode> method will not escape Unicode 253characters unless required by the JSON syntax or other flags. 254 255See also the section I<ENCODING/CODESET FLAG NOTES> later in this 256document. 257 258The main use for this flag is efficiently encoding binary data as JSON 259text, as most octets will not be escaped, resulting in a smaller encoded 260size. The disadvantage is that the resulting JSON text is encoded 261in latin1 (and must correctly be treated as such when storing and 262transferring), a rare encoding for JSON. It is therefore most useful when 263you want to store data structures known to contain binary data efficiently 264in files or databases, not when talking to other JSON encoders/decoders. 265 266 JSON::XS->new->latin1->encode (["\x{89}\x{abc}"] 267 => ["\x{89}\\u0abc"] # (perl syntax, U+abc escaped, U+89 not) 268 269=item $json = $json->utf8 ([$enable]) 270 271=item $enabled = $json->get_utf8 272 273If C<$enable> is true (or missing), then the C<encode> method will encode 274the JSON result into UTF-8, as required by many protocols, while the 275C<decode> method expects to be handled an UTF-8-encoded string. Please 276note that UTF-8-encoded strings do not contain any characters outside the 277range C<0..255>, they are thus useful for bytewise/binary I/O. In future 278versions, enabling this option might enable autodetection of the UTF-16 279and UTF-32 encoding families, as described in RFC4627. 280 281If C<$enable> is false, then the C<encode> method will return the JSON 282string as a (non-encoded) Unicode string, while C<decode> expects thus a 283Unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs 284to be done yourself, e.g. using the Encode module. 285 286See also the section I<ENCODING/CODESET FLAG NOTES> later in this 287document. 288 289Example, output UTF-16BE-encoded JSON: 290 291 use Encode; 292 $jsontext = encode "UTF-16BE", JSON::XS->new->encode ($object); 293 294Example, decode UTF-32LE-encoded JSON: 295 296 use Encode; 297 $object = JSON::XS->new->decode (decode "UTF-32LE", $jsontext); 298 299=item $json = $json->pretty ([$enable]) 300 301This enables (or disables) all of the C<indent>, C<space_before> and 302C<space_after> (and in the future possibly more) flags in one call to 303generate the most readable (or most compact) form possible. 304 305Example, pretty-print some simple structure: 306 307 my $json = JSON::XS->new->pretty(1)->encode ({a => [1,2]}) 308 => 309 { 310 "a" : [ 311 1, 312 2 313 ] 314 } 315 316=item $json = $json->indent ([$enable]) 317 318=item $enabled = $json->get_indent 319 320If C<$enable> is true (or missing), then the C<encode> method will use a multiline 321format as output, putting every array member or object/hash key-value pair 322into its own line, indenting them properly. 323 324If C<$enable> is false, no newlines or indenting will be produced, and the 325resulting JSON text is guaranteed not to contain any C<newlines>. 326 327This setting has no effect when decoding JSON texts. 328 329=item $json = $json->space_before ([$enable]) 330 331=item $enabled = $json->get_space_before 332 333If C<$enable> is true (or missing), then the C<encode> method will add an extra 334optional space before the C<:> separating keys from values in JSON objects. 335 336If C<$enable> is false, then the C<encode> method will not add any extra 337space at those places. 338 339This setting has no effect when decoding JSON texts. You will also 340most likely combine this setting with C<space_after>. 341 342Example, space_before enabled, space_after and indent disabled: 343 344 {"key" :"value"} 345 346=item $json = $json->space_after ([$enable]) 347 348=item $enabled = $json->get_space_after 349 350If C<$enable> is true (or missing), then the C<encode> method will add an extra 351optional space after the C<:> separating keys from values in JSON objects 352and extra whitespace after the C<,> separating key-value pairs and array 353members. 354 355If C<$enable> is false, then the C<encode> method will not add any extra 356space at those places. 357 358This setting has no effect when decoding JSON texts. 359 360Example, space_before and indent disabled, space_after enabled: 361 362 {"key": "value"} 363 364=item $json = $json->relaxed ([$enable]) 365 366=item $enabled = $json->get_relaxed 367 368If C<$enable> is true (or missing), then C<decode> will accept some 369extensions to normal JSON syntax (see below). C<encode> will not be 370affected in anyway. I<Be aware that this option makes you accept invalid 371JSON texts as if they were valid!>. I suggest only to use this option to 372parse application-specific files written by humans (configuration files, 373resource files etc.) 374 375If C<$enable> is false (the default), then C<decode> will only accept 376valid JSON texts. 377 378Currently accepted extensions are: 379 380=over 4 381 382=item * list items can have an end-comma 383 384JSON I<separates> array elements and key-value pairs with commas. This 385can be annoying if you write JSON texts manually and want to be able to 386quickly append elements, so this extension accepts comma at the end of 387such items not just between them: 388 389 [ 390 1, 391 2, <- this comma not normally allowed 392 ] 393 { 394 "k1": "v1", 395 "k2": "v2", <- this comma not normally allowed 396 } 397 398=item * shell-style '#'-comments 399 400Whenever JSON allows whitespace, shell-style comments are additionally 401allowed. They are terminated by the first carriage-return or line-feed 402character, after which more white-space and comments are allowed. 403 404 [ 405 1, # this comment not allowed in JSON 406 # neither this one... 407 ] 408 409=back 410 411=item $json = $json->canonical ([$enable]) 412 413=item $enabled = $json->get_canonical 414 415If C<$enable> is true (or missing), then the C<encode> method will output JSON objects 416by sorting their keys. This is adding a comparatively high overhead. 417 418If C<$enable> is false, then the C<encode> method will output key-value 419pairs in the order Perl stores them (which will likely change between runs 420of the same script, and can change even within the same run from 5.18 421onwards). 422 423This option is useful if you want the same data structure to be encoded as 424the same JSON text (given the same overall settings). If it is disabled, 425the same hash might be encoded differently even if contains the same data, 426as key-value pairs have no inherent ordering in Perl. 427 428This setting has no effect when decoding JSON texts. 429 430This setting has currently no effect on tied hashes. 431 432=item $json = $json->allow_nonref ([$enable]) 433 434=item $enabled = $json->get_allow_nonref 435 436If C<$enable> is true (or missing), then the C<encode> method can convert a 437non-reference into its corresponding string, number or null JSON value, 438which is an extension to RFC4627. Likewise, C<decode> will accept those JSON 439values instead of croaking. 440 441If C<$enable> is false, then the C<encode> method will croak if it isn't 442passed an arrayref or hashref, as JSON texts must either be an object 443or array. Likewise, C<decode> will croak if given something that is not a 444JSON object or array. 445 446Example, encode a Perl scalar as JSON value with enabled C<allow_nonref>, 447resulting in an invalid JSON text: 448 449 JSON::XS->new->allow_nonref->encode ("Hello, World!") 450 => "Hello, World!" 451 452=item $json = $json->allow_unknown ([$enable]) 453 454=item $enabled = $json->get_allow_unknown 455 456If C<$enable> is true (or missing), then C<encode> will I<not> throw an 457exception when it encounters values it cannot represent in JSON (for 458example, filehandles) but instead will encode a JSON C<null> value. Note 459that blessed objects are not included here and are handled separately by 460c<allow_nonref>. 461 462If C<$enable> is false (the default), then C<encode> will throw an 463exception when it encounters anything it cannot encode as JSON. 464 465This option does not affect C<decode> in any way, and it is recommended to 466leave it off unless you know your communications partner. 467 468=item $json = $json->allow_blessed ([$enable]) 469 470=item $enabled = $json->get_allow_blessed 471 472See L<OBJECT SERIALISATION> for details. 473 474If C<$enable> is true (or missing), then the C<encode> method will not 475barf when it encounters a blessed reference that it cannot convert 476otherwise. Instead, a JSON C<null> value is encoded instead of the object. 477 478If C<$enable> is false (the default), then C<encode> will throw an 479exception when it encounters a blessed object that it cannot convert 480otherwise. 481 482This setting has no effect on C<decode>. 483 484=item $json = $json->convert_blessed ([$enable]) 485 486=item $enabled = $json->get_convert_blessed 487 488See L<OBJECT SERIALISATION> for details. 489 490If C<$enable> is true (or missing), then C<encode>, upon encountering a 491blessed object, will check for the availability of the C<TO_JSON> method 492on the object's class. If found, it will be called in scalar context and 493the resulting scalar will be encoded instead of the object. 494 495The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON> 496returns other blessed objects, those will be handled in the same 497way. C<TO_JSON> must take care of not causing an endless recursion cycle 498(== crash) in this case. The name of C<TO_JSON> was chosen because other 499methods called by the Perl core (== not by the user of the object) are 500usually in upper case letters and to avoid collisions with any C<to_json> 501function or method. 502 503If C<$enable> is false (the default), then C<encode> will not consider 504this type of conversion. 505 506This setting has no effect on C<decode>. 507 508=item $json = $json->allow_tags ([$enable]) 509 510=item $enabled = $json->allow_tags 511 512See L<OBJECT SERIALISATION> for details. 513 514If C<$enable> is true (or missing), then C<encode>, upon encountering a 515blessed object, will check for the availability of the C<FREEZE> method on 516the object's class. If found, it will be used to serialise the object into 517a nonstandard tagged JSON value (that JSON decoders cannot decode). 518 519It also causes C<decode> to parse such tagged JSON values and deserialise 520them via a call to the C<THAW> method. 521 522If C<$enable> is false (the default), then C<encode> will not consider 523this type of conversion, and tagged JSON values will cause a parse error 524in C<decode>, as if tags were not part of the grammar. 525 526=item $json = $json->filter_json_object ([$coderef->($hashref)]) 527 528When C<$coderef> is specified, it will be called from C<decode> each 529time it decodes a JSON object. The only argument is a reference to the 530newly-created hash. If the code references returns a single scalar (which 531need not be a reference), this value (i.e. a copy of that scalar to avoid 532aliasing) is inserted into the deserialised data structure. If it returns 533an empty list (NOTE: I<not> C<undef>, which is a valid scalar), the 534original deserialised hash will be inserted. This setting can slow down 535decoding considerably. 536 537When C<$coderef> is omitted or undefined, any existing callback will 538be removed and C<decode> will not change the deserialised hash in any 539way. 540 541Example, convert all JSON objects into the integer 5: 542 543 my $js = JSON::XS->new->filter_json_object (sub { 5 }); 544 # returns [5] 545 $js->decode ('[{}]') 546 # throw an exception because allow_nonref is not enabled 547 # so a lone 5 is not allowed. 548 $js->decode ('{"a":1, "b":2}'); 549 550=item $json = $json->filter_json_single_key_object ($key [=> $coderef->($value)]) 551 552Works remotely similar to C<filter_json_object>, but is only called for 553JSON objects having a single key named C<$key>. 554 555This C<$coderef> is called before the one specified via 556C<filter_json_object>, if any. It gets passed the single value in the JSON 557object. If it returns a single value, it will be inserted into the data 558structure. If it returns nothing (not even C<undef> but the empty list), 559the callback from C<filter_json_object> will be called next, as if no 560single-key callback were specified. 561 562If C<$coderef> is omitted or undefined, the corresponding callback will be 563disabled. There can only ever be one callback for a given key. 564 565As this callback gets called less often then the C<filter_json_object> 566one, decoding speed will not usually suffer as much. Therefore, single-key 567objects make excellent targets to serialise Perl objects into, especially 568as single-key JSON objects are as close to the type-tagged value concept 569as JSON gets (it's basically an ID/VALUE tuple). Of course, JSON does not 570support this in any way, so you need to make sure your data never looks 571like a serialised Perl hash. 572 573Typical names for the single object key are C<__class_whatever__>, or 574C<$__dollars_are_rarely_used__$> or C<}ugly_brace_placement>, or even 575things like C<__class_md5sum(classname)__>, to reduce the risk of clashing 576with real hashes. 577 578Example, decode JSON objects of the form C<< { "__widget__" => <id> } >> 579into the corresponding C<< $WIDGET{<id>} >> object: 580 581 # return whatever is in $WIDGET{5}: 582 JSON::XS 583 ->new 584 ->filter_json_single_key_object (__widget__ => sub { 585 $WIDGET{ $_[0] } 586 }) 587 ->decode ('{"__widget__": 5') 588 589 # this can be used with a TO_JSON method in some "widget" class 590 # for serialisation to json: 591 sub WidgetBase::TO_JSON { 592 my ($self) = @_; 593 594 unless ($self->{id}) { 595 $self->{id} = ..get..some..id..; 596 $WIDGET{$self->{id}} = $self; 597 } 598 599 { __widget__ => $self->{id} } 600 } 601 602=item $json = $json->shrink ([$enable]) 603 604=item $enabled = $json->get_shrink 605 606Perl usually over-allocates memory a bit when allocating space for 607strings. This flag optionally resizes strings generated by either 608C<encode> or C<decode> to their minimum size possible. This can save 609memory when your JSON texts are either very very long or you have many 610short strings. It will also try to downgrade any strings to octet-form 611if possible: perl stores strings internally either in an encoding called 612UTF-X or in octet-form. The latter cannot store everything but uses less 613space in general (and some buggy Perl or C code might even rely on that 614internal representation being used). 615 616The actual definition of what shrink does might change in future versions, 617but it will always try to save space at the expense of time. 618 619If C<$enable> is true (or missing), the string returned by C<encode> will 620be shrunk-to-fit, while all strings generated by C<decode> will also be 621shrunk-to-fit. 622 623If C<$enable> is false, then the normal perl allocation algorithms are used. 624If you work with your data, then this is likely to be faster. 625 626In the future, this setting might control other things, such as converting 627strings that look like integers or floats into integers or floats 628internally (there is no difference on the Perl level), saving space. 629 630=item $json = $json->max_depth ([$maximum_nesting_depth]) 631 632=item $max_depth = $json->get_max_depth 633 634Sets the maximum nesting level (default C<512>) accepted while encoding 635or decoding. If a higher nesting level is detected in JSON text or a Perl 636data structure, then the encoder and decoder will stop and croak at that 637point. 638 639Nesting level is defined by number of hash- or arrayrefs that the encoder 640needs to traverse to reach a given point or the number of C<{> or C<[> 641characters without their matching closing parenthesis crossed to reach a 642given character in a string. 643 644Setting the maximum depth to one disallows any nesting, so that ensures 645that the object is only a single hash/object or array. 646 647If no argument is given, the highest possible setting will be used, which 648is rarely useful. 649 650Note that nesting is implemented by recursion in C. The default value has 651been chosen to be as large as typical operating systems allow without 652crashing. 653 654See SECURITY CONSIDERATIONS, below, for more info on why this is useful. 655 656=item $json = $json->max_size ([$maximum_string_size]) 657 658=item $max_size = $json->get_max_size 659 660Set the maximum length a JSON text may have (in bytes) where decoding is 661being attempted. The default is C<0>, meaning no limit. When C<decode> 662is called on a string that is longer then this many bytes, it will not 663attempt to decode the string but throw an exception. This setting has no 664effect on C<encode> (yet). 665 666If no argument is given, the limit check will be deactivated (same as when 667C<0> is specified). 668 669See SECURITY CONSIDERATIONS, below, for more info on why this is useful. 670 671=item $json_text = $json->encode ($perl_scalar) 672 673Converts the given Perl value or data structure to its JSON 674representation. Croaks on error. 675 676=item $perl_scalar = $json->decode ($json_text) 677 678The opposite of C<encode>: expects a JSON text and tries to parse it, 679returning the resulting simple scalar or reference. Croaks on error. 680 681=item ($perl_scalar, $characters) = $json->decode_prefix ($json_text) 682 683This works like the C<decode> method, but instead of raising an exception 684when there is trailing garbage after the first JSON object, it will 685silently stop parsing there and return the number of characters consumed 686so far. 687 688This is useful if your JSON texts are not delimited by an outer protocol 689and you need to know where the JSON text ends. 690 691 JSON::XS->new->decode_prefix ("[1] the tail") 692 => ([], 3) 693 694=back 695 696 697=head1 INCREMENTAL PARSING 698 699In some cases, there is the need for incremental parsing of JSON 700texts. While this module always has to keep both JSON text and resulting 701Perl data structure in memory at one time, it does allow you to parse a 702JSON stream incrementally. It does so by accumulating text until it has 703a full JSON object, which it then can decode. This process is similar to 704using C<decode_prefix> to see if a full JSON object is available, but 705is much more efficient (and can be implemented with a minimum of method 706calls). 707 708JSON::XS will only attempt to parse the JSON text once it is sure it 709has enough text to get a decisive result, using a very simple but 710truly incremental parser. This means that it sometimes won't stop as 711early as the full parser, for example, it doesn't detect mismatched 712parentheses. The only thing it guarantees is that it starts decoding as 713soon as a syntactically valid JSON text has been seen. This means you need 714to set resource limits (e.g. C<max_size>) to ensure the parser will stop 715parsing in the presence if syntax errors. 716 717The following methods implement this incremental parser. 718 719=over 4 720 721=item [void, scalar or list context] = $json->incr_parse ([$string]) 722 723This is the central parsing function. It can both append new text and 724extract objects from the stream accumulated so far (both of these 725functions are optional). 726 727If C<$string> is given, then this string is appended to the already 728existing JSON fragment stored in the C<$json> object. 729 730After that, if the function is called in void context, it will simply 731return without doing anything further. This can be used to add more text 732in as many chunks as you want. 733 734If the method is called in scalar context, then it will try to extract 735exactly I<one> JSON object. If that is successful, it will return this 736object, otherwise it will return C<undef>. If there is a parse error, 737this method will croak just as C<decode> would do (one can then use 738C<incr_skip> to skip the erroneous part). This is the most common way of 739using the method. 740 741And finally, in list context, it will try to extract as many objects 742from the stream as it can find and return them, or the empty list 743otherwise. For this to work, there must be no separators between the JSON 744objects or arrays, instead they must be concatenated back-to-back. If 745an error occurs, an exception will be raised as in the scalar context 746case. Note that in this case, any previously-parsed JSON texts will be 747lost. 748 749Example: Parse some JSON arrays/objects in a given string and return 750them. 751 752 my @objs = JSON::XS->new->incr_parse ("[5][7][1,2]"); 753 754=item $lvalue_string = $json->incr_text 755 756This method returns the currently stored JSON fragment as an lvalue, that 757is, you can manipulate it. This I<only> works when a preceding call to 758C<incr_parse> in I<scalar context> successfully returned an object. Under 759all other circumstances you must not call this function (I mean it. 760although in simple tests it might actually work, it I<will> fail under 761real world conditions). As a special exception, you can also call this 762method before having parsed anything. 763 764This function is useful in two cases: a) finding the trailing text after a 765JSON object or b) parsing multiple JSON objects separated by non-JSON text 766(such as commas). 767 768=item $json->incr_skip 769 770This will reset the state of the incremental parser and will remove 771the parsed text from the input buffer so far. This is useful after 772C<incr_parse> died, in which case the input buffer and incremental parser 773state is left unchanged, to skip the text parsed so far and to reset the 774parse state. 775 776The difference to C<incr_reset> is that only text until the parse error 777occurred is removed. 778 779=item $json->incr_reset 780 781This completely resets the incremental parser, that is, after this call, 782it will be as if the parser had never parsed anything. 783 784This is useful if you want to repeatedly parse JSON objects and want to 785ignore any trailing data, which means you have to reset the parser after 786each successful decode. 787 788=back 789 790=head2 LIMITATIONS 791 792All options that affect decoding are supported, except 793C<allow_nonref>. The reason for this is that it cannot be made to work 794sensibly: JSON objects and arrays are self-delimited, i.e. you can 795concatenate them back to back and still decode them perfectly. This does 796not hold true for JSON numbers, however. 797 798For example, is the string C<1> a single JSON number, or is it simply the 799start of C<12>? Or is C<12> a single JSON number, or the concatenation 800of C<1> and C<2>? In neither case you can tell, and this is why JSON::XS 801takes the conservative route and disallows this case. 802 803=head2 EXAMPLES 804 805Some examples will make all this clearer. First, a simple example that 806works similarly to C<decode_prefix>: We want to decode the JSON object at 807the start of a string and identify the portion after the JSON object: 808 809 my $text = "[1,2,3] hello"; 810 811 my $json = new JSON::XS; 812 813 my $obj = $json->incr_parse ($text) 814 or die "expected JSON object or array at beginning of string"; 815 816 my $tail = $json->incr_text; 817 # $tail now contains " hello" 818 819Easy, isn't it? 820 821Now for a more complicated example: Imagine a hypothetical protocol where 822you read some requests from a TCP stream, and each request is a JSON 823array, without any separation between them (in fact, it is often useful to 824use newlines as "separators", as these get interpreted as whitespace at 825the start of the JSON text, which makes it possible to test said protocol 826with C<telnet>...). 827 828Here is how you'd do it (it is trivial to write this in an event-based 829manner): 830 831 my $json = new JSON::XS; 832 833 # read some data from the socket 834 while (sysread $socket, my $buf, 4096) { 835 836 # split and decode as many requests as possible 837 for my $request ($json->incr_parse ($buf)) { 838 # act on the $request 839 } 840 } 841 842Another complicated example: Assume you have a string with JSON objects 843or arrays, all separated by (optional) comma characters (e.g. C<[1],[2], 844[3]>). To parse them, we have to skip the commas between the JSON texts, 845and here is where the lvalue-ness of C<incr_text> comes in useful: 846 847 my $text = "[1],[2], [3]"; 848 my $json = new JSON::XS; 849 850 # void context, so no parsing done 851 $json->incr_parse ($text); 852 853 # now extract as many objects as possible. note the 854 # use of scalar context so incr_text can be called. 855 while (my $obj = $json->incr_parse) { 856 # do something with $obj 857 858 # now skip the optional comma 859 $json->incr_text =~ s/^ \s* , //x; 860 } 861 862Now lets go for a very complex example: Assume that you have a gigantic 863JSON array-of-objects, many gigabytes in size, and you want to parse it, 864but you cannot load it into memory fully (this has actually happened in 865the real world :). 866 867Well, you lost, you have to implement your own JSON parser. But JSON::XS 868can still help you: You implement a (very simple) array parser and let 869JSON decode the array elements, which are all full JSON objects on their 870own (this wouldn't work if the array elements could be JSON numbers, for 871example): 872 873 my $json = new JSON::XS; 874 875 # open the monster 876 open my $fh, "<bigfile.json" 877 or die "bigfile: $!"; 878 879 # first parse the initial "[" 880 for (;;) { 881 sysread $fh, my $buf, 65536 882 or die "read error: $!"; 883 $json->incr_parse ($buf); # void context, so no parsing 884 885 # Exit the loop once we found and removed(!) the initial "[". 886 # In essence, we are (ab-)using the $json object as a simple scalar 887 # we append data to. 888 last if $json->incr_text =~ s/^ \s* \[ //x; 889 } 890 891 # now we have the skipped the initial "[", so continue 892 # parsing all the elements. 893 for (;;) { 894 # in this loop we read data until we got a single JSON object 895 for (;;) { 896 if (my $obj = $json->incr_parse) { 897 # do something with $obj 898 last; 899 } 900 901 # add more data 902 sysread $fh, my $buf, 65536 903 or die "read error: $!"; 904 $json->incr_parse ($buf); # void context, so no parsing 905 } 906 907 # in this loop we read data until we either found and parsed the 908 # separating "," between elements, or the final "]" 909 for (;;) { 910 # first skip whitespace 911 $json->incr_text =~ s/^\s*//; 912 913 # if we find "]", we are done 914 if ($json->incr_text =~ s/^\]//) { 915 print "finished.\n"; 916 exit; 917 } 918 919 # if we find ",", we can continue with the next element 920 if ($json->incr_text =~ s/^,//) { 921 last; 922 } 923 924 # if we find anything else, we have a parse error! 925 if (length $json->incr_text) { 926 die "parse error near ", $json->incr_text; 927 } 928 929 # else add more data 930 sysread $fh, my $buf, 65536 931 or die "read error: $!"; 932 $json->incr_parse ($buf); # void context, so no parsing 933 } 934 935This is a complex example, but most of the complexity comes from the fact 936that we are trying to be correct (bear with me if I am wrong, I never ran 937the above example :). 938 939 940 941=head1 MAPPING 942 943This section describes how JSON::XS maps Perl values to JSON values and 944vice versa. These mappings are designed to "do the right thing" in most 945circumstances automatically, preserving round-tripping characteristics 946(what you put in comes out as something equivalent). 947 948For the more enlightened: note that in the following descriptions, 949lowercase I<perl> refers to the Perl interpreter, while uppercase I<Perl> 950refers to the abstract Perl language itself. 951 952 953=head2 JSON -> PERL 954 955=over 4 956 957=item object 958 959A JSON object becomes a reference to a hash in Perl. No ordering of object 960keys is preserved (JSON does not preserve object key ordering itself). 961 962=item array 963 964A JSON array becomes a reference to an array in Perl. 965 966=item string 967 968A JSON string becomes a string scalar in Perl - Unicode codepoints in JSON 969are represented by the same codepoints in the Perl string, so no manual 970decoding is necessary. 971 972=item number 973 974A JSON number becomes either an integer, numeric (floating point) or 975string scalar in perl, depending on its range and any fractional parts. On 976the Perl level, there is no difference between those as Perl handles all 977the conversion details, but an integer may take slightly less memory and 978might represent more values exactly than floating point numbers. 979 980If the number consists of digits only, JSON::XS will try to represent 981it as an integer value. If that fails, it will try to represent it as 982a numeric (floating point) value if that is possible without loss of 983precision. Otherwise it will preserve the number as a string value (in 984which case you lose roundtripping ability, as the JSON number will be 985re-encoded to a JSON string). 986 987Numbers containing a fractional or exponential part will always be 988represented as numeric (floating point) values, possibly at a loss of 989precision (in which case you might lose perfect roundtripping ability, but 990the JSON number will still be re-encoded as a JSON number). 991 992Note that precision is not accuracy - binary floating point values cannot 993represent most decimal fractions exactly, and when converting from and to 994floating point, JSON::XS only guarantees precision up to but not including 995the least significant bit. 996 997=item true, false 998 999These JSON atoms become C<Types::Serialiser::true> and 1000C<Types::Serialiser::false>, respectively. They are overloaded to act 1001almost exactly like the numbers C<1> and C<0>. You can check whether 1002a scalar is a JSON boolean by using the C<Types::Serialiser::is_bool> 1003function (after C<use Types::Serialier>, of course). 1004 1005=item null 1006 1007A JSON null atom becomes C<undef> in Perl. 1008 1009=item shell-style comments (C<< # I<text> >>) 1010 1011As a nonstandard extension to the JSON syntax that is enabled by the 1012C<relaxed> setting, shell-style comments are allowed. They can start 1013anywhere outside strings and go till the end of the line. 1014 1015=item tagged values (C<< (I<tag>)I<value> >>). 1016 1017Another nonstandard extension to the JSON syntax, enabled with the 1018C<allow_tags> setting, are tagged values. In this implementation, the 1019I<tag> must be a perl package/class name encoded as a JSON string, and the 1020I<value> must be a JSON array encoding optional constructor arguments. 1021 1022See L<OBJECT SERIALISATION>, below, for details. 1023 1024=back 1025 1026 1027=head2 PERL -> JSON 1028 1029The mapping from Perl to JSON is slightly more difficult, as Perl is a 1030truly typeless language, so we can only guess which JSON type is meant by 1031a Perl value. 1032 1033=over 4 1034 1035=item hash references 1036 1037Perl hash references become JSON objects. As there is no inherent 1038ordering in hash keys (or JSON objects), they will usually be encoded 1039in a pseudo-random order. JSON::XS can optionally sort the hash keys 1040(determined by the I<canonical> flag), so the same datastructure will 1041serialise to the same JSON text (given same settings and version of 1042JSON::XS), but this incurs a runtime overhead and is only rarely useful, 1043e.g. when you want to compare some JSON text against another for equality. 1044 1045=item array references 1046 1047Perl array references become JSON arrays. 1048 1049=item other references 1050 1051Other unblessed references are generally not allowed and will cause an 1052exception to be thrown, except for references to the integers C<0> and 1053C<1>, which get turned into C<false> and C<true> atoms in JSON. 1054 1055Since C<JSON::XS> uses the boolean model from L<Types::Serialiser>, you 1056can also C<use Types::Serialiser> and then use C<Types::Serialiser::false> 1057and C<Types::Serialiser::true> to improve readability. 1058 1059 use Types::Serialiser; 1060 encode_json [\0, Types::Serialiser::true] # yields [false,true] 1061 1062=item Types::Serialiser::true, Types::Serialiser::false 1063 1064These special values from the L<Types::Serialiser> module become JSON true 1065and JSON false values, respectively. You can also use C<\1> and C<\0> 1066directly if you want. 1067 1068=item blessed objects 1069 1070Blessed objects are not directly representable in JSON, but C<JSON::XS> 1071allows various ways of handling objects. See L<OBJECT SERIALISATION>, 1072below, for details. 1073 1074=item simple scalars 1075 1076Simple Perl scalars (any scalar that is not a reference) are the most 1077difficult objects to encode: JSON::XS will encode undefined scalars as 1078JSON C<null> values, scalars that have last been used in a string context 1079before encoding as JSON strings, and anything else as number value: 1080 1081 # dump as number 1082 encode_json [2] # yields [2] 1083 encode_json [-3.0e17] # yields [-3e+17] 1084 my $value = 5; encode_json [$value] # yields [5] 1085 1086 # used as string, so dump as string 1087 print $value; 1088 encode_json [$value] # yields ["5"] 1089 1090 # undef becomes null 1091 encode_json [undef] # yields [null] 1092 1093You can force the type to be a JSON string by stringifying it: 1094 1095 my $x = 3.1; # some variable containing a number 1096 "$x"; # stringified 1097 $x .= ""; # another, more awkward way to stringify 1098 print $x; # perl does it for you, too, quite often 1099 1100You can force the type to be a JSON number by numifying it: 1101 1102 my $x = "3"; # some variable containing a string 1103 $x += 0; # numify it, ensuring it will be dumped as a number 1104 $x *= 1; # same thing, the choice is yours. 1105 1106You can not currently force the type in other, less obscure, ways. Tell me 1107if you need this capability (but don't forget to explain why it's needed 1108:). 1109 1110Note that numerical precision has the same meaning as under Perl (so 1111binary to decimal conversion follows the same rules as in Perl, which 1112can differ to other languages). Also, your perl interpreter might expose 1113extensions to the floating point numbers of your platform, such as 1114infinities or NaN's - these cannot be represented in JSON, and it is an 1115error to pass those in. 1116 1117=back 1118 1119=head2 OBJECT SERIALISATION 1120 1121As JSON cannot directly represent Perl objects, you have to choose between 1122a pure JSON representation (without the ability to deserialise the object 1123automatically again), and a nonstandard extension to the JSON syntax, 1124tagged values. 1125 1126=head3 SERIALISATION 1127 1128What happens when C<JSON::XS> encounters a Perl object depends on the 1129C<allow_blessed>, C<convert_blessed> and C<allow_tags> settings, which are 1130used in this order: 1131 1132=over 4 1133 1134=item 1. C<allow_tags> is enabled and the object has a C<FREEZE> method. 1135 1136In this case, C<JSON::XS> uses the L<Types::Serialiser> object 1137serialisation protocol to create a tagged JSON value, using a nonstandard 1138extension to the JSON syntax. 1139 1140This works by invoking the C<FREEZE> method on the object, with the first 1141argument being the object to serialise, and the second argument being the 1142constant string C<JSON> to distinguish it from other serialisers. 1143 1144The C<FREEZE> method can return any number of values (i.e. zero or 1145more). These values and the paclkage/classname of the object will then be 1146encoded as a tagged JSON value in the following format: 1147 1148 ("classname")[FREEZE return values...] 1149 1150e.g.: 1151 1152 ("URI")["http://www.google.com/"] 1153 ("MyDate")[2013,10,29] 1154 ("ImageData::JPEG")["Z3...VlCg=="] 1155 1156For example, the hypothetical C<My::Object> C<FREEZE> method might use the 1157objects C<type> and C<id> members to encode the object: 1158 1159 sub My::Object::FREEZE { 1160 my ($self, $serialiser) = @_; 1161 1162 ($self->{type}, $self->{id}) 1163 } 1164 1165=item 2. C<convert_blessed> is enabled and the object has a C<TO_JSON> method. 1166 1167In this case, the C<TO_JSON> method of the object is invoked in scalar 1168context. It must return a single scalar that can be directly encoded into 1169JSON. This scalar replaces the object in the JSON text. 1170 1171For example, the following C<TO_JSON> method will convert all L<URI> 1172objects to JSON strings when serialised. The fatc that these values 1173originally were L<URI> objects is lost. 1174 1175 sub URI::TO_JSON { 1176 my ($uri) = @_; 1177 $uri->as_string 1178 } 1179 1180=item 3. C<allow_blessed> is enabled. 1181 1182The object will be serialised as a JSON null value. 1183 1184=item 4. none of the above 1185 1186If none of the settings are enabled or the respective methods are missing, 1187C<JSON::XS> throws an exception. 1188 1189=back 1190 1191=head3 DESERIALISATION 1192 1193For deserialisation there are only two cases to consider: either 1194nonstandard tagging was used, in which case C<allow_tags> decides, 1195or objects cannot be automatically be deserialised, in which 1196case you can use postprocessing or the C<filter_json_object> or 1197C<filter_json_single_key_object> callbacks to get some real objects our of 1198your JSON. 1199 1200This section only considers the tagged value case: I a tagged JSON object 1201is encountered during decoding and C<allow_tags> is disabled, a parse 1202error will result (as if tagged values were not part of the grammar). 1203 1204If C<allow_tags> is enabled, C<JSON::XS> will look up the C<THAW> method 1205of the package/classname used during serialisation (it will not attempt 1206to load the package as a Perl module). If there is no such method, the 1207decoding will fail with an error. 1208 1209Otherwise, the C<THAW> method is invoked with the classname as first 1210argument, the constant string C<JSON> as second argument, and all the 1211values from the JSON array (the values originally returned by the 1212C<FREEZE> method) as remaining arguments. 1213 1214The method must then return the object. While technically you can return 1215any Perl scalar, you might have to enable the C<enable_nonref> setting to 1216make that work in all cases, so better return an actual blessed reference. 1217 1218As an example, let's implement a C<THAW> function that regenerates the 1219C<My::Object> from the C<FREEZE> example earlier: 1220 1221 sub My::Object::THAW { 1222 my ($class, $serialiser, $type, $id) = @_; 1223 1224 $class->new (type => $type, id => $id) 1225 } 1226 1227 1228=head1 ENCODING/CODESET FLAG NOTES 1229 1230The interested reader might have seen a number of flags that signify 1231encodings or codesets - C<utf8>, C<latin1> and C<ascii>. There seems to be 1232some confusion on what these do, so here is a short comparison: 1233 1234C<utf8> controls whether the JSON text created by C<encode> (and expected 1235by C<decode>) is UTF-8 encoded or not, while C<latin1> and C<ascii> only 1236control whether C<encode> escapes character values outside their respective 1237codeset range. Neither of these flags conflict with each other, although 1238some combinations make less sense than others. 1239 1240Care has been taken to make all flags symmetrical with respect to 1241C<encode> and C<decode>, that is, texts encoded with any combination of 1242these flag values will be correctly decoded when the same flags are used 1243- in general, if you use different flag settings while encoding vs. when 1244decoding you likely have a bug somewhere. 1245 1246Below comes a verbose discussion of these flags. Note that a "codeset" is 1247simply an abstract set of character-codepoint pairs, while an encoding 1248takes those codepoint numbers and I<encodes> them, in our case into 1249octets. Unicode is (among other things) a codeset, UTF-8 is an encoding, 1250and ISO-8859-1 (= latin 1) and ASCII are both codesets I<and> encodings at 1251the same time, which can be confusing. 1252 1253=over 4 1254 1255=item C<utf8> flag disabled 1256 1257When C<utf8> is disabled (the default), then C<encode>/C<decode> generate 1258and expect Unicode strings, that is, characters with high ordinal Unicode 1259values (> 255) will be encoded as such characters, and likewise such 1260characters are decoded as-is, no changes to them will be done, except 1261"(re-)interpreting" them as Unicode codepoints or Unicode characters, 1262respectively (to Perl, these are the same thing in strings unless you do 1263funny/weird/dumb stuff). 1264 1265This is useful when you want to do the encoding yourself (e.g. when you 1266want to have UTF-16 encoded JSON texts) or when some other layer does 1267the encoding for you (for example, when printing to a terminal using a 1268filehandle that transparently encodes to UTF-8 you certainly do NOT want 1269to UTF-8 encode your data first and have Perl encode it another time). 1270 1271=item C<utf8> flag enabled 1272 1273If the C<utf8>-flag is enabled, C<encode>/C<decode> will encode all 1274characters using the corresponding UTF-8 multi-byte sequence, and will 1275expect your input strings to be encoded as UTF-8, that is, no "character" 1276of the input string must have any value > 255, as UTF-8 does not allow 1277that. 1278 1279The C<utf8> flag therefore switches between two modes: disabled means you 1280will get a Unicode string in Perl, enabled means you get an UTF-8 encoded 1281octet/binary string in Perl. 1282 1283=item C<latin1> or C<ascii> flags enabled 1284 1285With C<latin1> (or C<ascii>) enabled, C<encode> will escape characters 1286with ordinal values > 255 (> 127 with C<ascii>) and encode the remaining 1287characters as specified by the C<utf8> flag. 1288 1289If C<utf8> is disabled, then the result is also correctly encoded in those 1290character sets (as both are proper subsets of Unicode, meaning that a 1291Unicode string with all character values < 256 is the same thing as a 1292ISO-8859-1 string, and a Unicode string with all character values < 128 is 1293the same thing as an ASCII string in Perl). 1294 1295If C<utf8> is enabled, you still get a correct UTF-8-encoded string, 1296regardless of these flags, just some more characters will be escaped using 1297C<\uXXXX> then before. 1298 1299Note that ISO-8859-1-I<encoded> strings are not compatible with UTF-8 1300encoding, while ASCII-encoded strings are. That is because the ISO-8859-1 1301encoding is NOT a subset of UTF-8 (despite the ISO-8859-1 I<codeset> being 1302a subset of Unicode), while ASCII is. 1303 1304Surprisingly, C<decode> will ignore these flags and so treat all input 1305values as governed by the C<utf8> flag. If it is disabled, this allows you 1306to decode ISO-8859-1- and ASCII-encoded strings, as both strict subsets of 1307Unicode. If it is enabled, you can correctly decode UTF-8 encoded strings. 1308 1309So neither C<latin1> nor C<ascii> are incompatible with the C<utf8> flag - 1310they only govern when the JSON output engine escapes a character or not. 1311 1312The main use for C<latin1> is to relatively efficiently store binary data 1313as JSON, at the expense of breaking compatibility with most JSON decoders. 1314 1315The main use for C<ascii> is to force the output to not contain characters 1316with values > 127, which means you can interpret the resulting string 1317as UTF-8, ISO-8859-1, ASCII, KOI8-R or most about any character set and 13188-bit-encoding, and still get the same data structure back. This is useful 1319when your channel for JSON transfer is not 8-bit clean or the encoding 1320might be mangled in between (e.g. in mail), and works because ASCII is a 1321proper subset of most 8-bit and multibyte encodings in use in the world. 1322 1323=back 1324 1325 1326=head2 JSON and ECMAscript 1327 1328JSON syntax is based on how literals are represented in javascript (the 1329not-standardised predecessor of ECMAscript) which is presumably why it is 1330called "JavaScript Object Notation". 1331 1332However, JSON is not a subset (and also not a superset of course) of 1333ECMAscript (the standard) or javascript (whatever browsers actually 1334implement). 1335 1336If you want to use javascript's C<eval> function to "parse" JSON, you 1337might run into parse errors for valid JSON texts, or the resulting data 1338structure might not be queryable: 1339 1340One of the problems is that U+2028 and U+2029 are valid characters inside 1341JSON strings, but are not allowed in ECMAscript string literals, so the 1342following Perl fragment will not output something that can be guaranteed 1343to be parsable by javascript's C<eval>: 1344 1345 use JSON::XS; 1346 1347 print encode_json [chr 0x2028]; 1348 1349The right fix for this is to use a proper JSON parser in your javascript 1350programs, and not rely on C<eval> (see for example Douglas Crockford's 1351F<json2.js> parser). 1352 1353If this is not an option, you can, as a stop-gap measure, simply encode to 1354ASCII-only JSON: 1355 1356 use JSON::XS; 1357 1358 print JSON::XS->new->ascii->encode ([chr 0x2028]); 1359 1360Note that this will enlarge the resulting JSON text quite a bit if you 1361have many non-ASCII characters. You might be tempted to run some regexes 1362to only escape U+2028 and U+2029, e.g.: 1363 1364 # DO NOT USE THIS! 1365 my $json = JSON::XS->new->utf8->encode ([chr 0x2028]); 1366 $json =~ s/\xe2\x80\xa8/\\u2028/g; # escape U+2028 1367 $json =~ s/\xe2\x80\xa9/\\u2029/g; # escape U+2029 1368 print $json; 1369 1370Note that I<this is a bad idea>: the above only works for U+2028 and 1371U+2029 and thus only for fully ECMAscript-compliant parsers. Many existing 1372javascript implementations, however, have issues with other characters as 1373well - using C<eval> naively simply I<will> cause problems. 1374 1375Another problem is that some javascript implementations reserve 1376some property names for their own purposes (which probably makes 1377them non-ECMAscript-compliant). For example, Iceweasel reserves the 1378C<__proto__> property name for its own purposes. 1379 1380If that is a problem, you could parse try to filter the resulting JSON 1381output for these property strings, e.g.: 1382 1383 $json =~ s/"__proto__"\s*:/"__proto__renamed":/g; 1384 1385This works because C<__proto__> is not valid outside of strings, so every 1386occurrence of C<"__proto__"\s*:> must be a string used as property name. 1387 1388If you know of other incompatibilities, please let me know. 1389 1390 1391=head2 JSON and YAML 1392 1393You often hear that JSON is a subset of YAML. This is, however, a mass 1394hysteria(*) and very far from the truth (as of the time of this writing), 1395so let me state it clearly: I<in general, there is no way to configure 1396JSON::XS to output a data structure as valid YAML> that works in all 1397cases. 1398 1399If you really must use JSON::XS to generate YAML, you should use this 1400algorithm (subject to change in future versions): 1401 1402 my $to_yaml = JSON::XS->new->utf8->space_after (1); 1403 my $yaml = $to_yaml->encode ($ref) . "\n"; 1404 1405This will I<usually> generate JSON texts that also parse as valid 1406YAML. Please note that YAML has hardcoded limits on (simple) object key 1407lengths that JSON doesn't have and also has different and incompatible 1408unicode character escape syntax, so you should make sure that your hash 1409keys are noticeably shorter than the 1024 "stream characters" YAML allows 1410and that you do not have characters with codepoint values outside the 1411Unicode BMP (basic multilingual page). YAML also does not allow C<\/> 1412sequences in strings (which JSON::XS does not I<currently> generate, but 1413other JSON generators might). 1414 1415There might be other incompatibilities that I am not aware of (or the YAML 1416specification has been changed yet again - it does so quite often). In 1417general you should not try to generate YAML with a JSON generator or vice 1418versa, or try to parse JSON with a YAML parser or vice versa: chances are 1419high that you will run into severe interoperability problems when you 1420least expect it. 1421 1422=over 4 1423 1424=item (*) 1425 1426I have been pressured multiple times by Brian Ingerson (one of the 1427authors of the YAML specification) to remove this paragraph, despite him 1428acknowledging that the actual incompatibilities exist. As I was personally 1429bitten by this "JSON is YAML" lie, I refused and said I will continue to 1430educate people about these issues, so others do not run into the same 1431problem again and again. After this, Brian called me a (quote)I<complete 1432and worthless idiot>(unquote). 1433 1434In my opinion, instead of pressuring and insulting people who actually 1435clarify issues with YAML and the wrong statements of some of its 1436proponents, I would kindly suggest reading the JSON spec (which is not 1437that difficult or long) and finally make YAML compatible to it, and 1438educating users about the changes, instead of spreading lies about the 1439real compatibility for many I<years> and trying to silence people who 1440point out that it isn't true. 1441 1442Addendum/2009: the YAML 1.2 spec is still incompatible with JSON, even 1443though the incompatibilities have been documented (and are known to Brian) 1444for many years and the spec makes explicit claims that YAML is a superset 1445of JSON. It would be so easy to fix, but apparently, bullying people and 1446corrupting userdata is so much easier. 1447 1448=back 1449 1450 1451=head2 SPEED 1452 1453It seems that JSON::XS is surprisingly fast, as shown in the following 1454tables. They have been generated with the help of the C<eg/bench> program 1455in the JSON::XS distribution, to make it easy to compare on your own 1456system. 1457 1458First comes a comparison between various modules using 1459a very short single-line JSON string (also available at 1460L<http://dist.schmorp.de/misc/json/short.json>). 1461 1462 {"method": "handleMessage", "params": ["user1", 1463 "we were just talking"], "id": null, "array":[1,11,234,-5,1e5,1e7, 1464 1, 0]} 1465 1466It shows the number of encodes/decodes per second (JSON::XS uses 1467the functional interface, while JSON::XS/2 uses the OO interface 1468with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables 1469shrink. JSON::DWIW/DS uses the deserialise function, while JSON::DWIW::FJ 1470uses the from_json method). Higher is better: 1471 1472 module | encode | decode | 1473 --------------|------------|------------| 1474 JSON::DWIW/DS | 86302.551 | 102300.098 | 1475 JSON::DWIW/FJ | 86302.551 | 75983.768 | 1476 JSON::PP | 15827.562 | 6638.658 | 1477 JSON::Syck | 63358.066 | 47662.545 | 1478 JSON::XS | 511500.488 | 511500.488 | 1479 JSON::XS/2 | 291271.111 | 388361.481 | 1480 JSON::XS/3 | 361577.931 | 361577.931 | 1481 Storable | 66788.280 | 265462.278 | 1482 --------------+------------+------------+ 1483 1484That is, JSON::XS is almost six times faster than JSON::DWIW on encoding, 1485about five times faster on decoding, and over thirty to seventy times 1486faster than JSON's pure perl implementation. It also compares favourably 1487to Storable for small amounts of data. 1488 1489Using a longer test string (roughly 18KB, generated from Yahoo! Locals 1490search API (L<http://dist.schmorp.de/misc/json/long.json>). 1491 1492 module | encode | decode | 1493 --------------|------------|------------| 1494 JSON::DWIW/DS | 1647.927 | 2673.916 | 1495 JSON::DWIW/FJ | 1630.249 | 2596.128 | 1496 JSON::PP | 400.640 | 62.311 | 1497 JSON::Syck | 1481.040 | 1524.869 | 1498 JSON::XS | 20661.596 | 9541.183 | 1499 JSON::XS/2 | 10683.403 | 9416.938 | 1500 JSON::XS/3 | 20661.596 | 9400.054 | 1501 Storable | 19765.806 | 10000.725 | 1502 --------------+------------+------------+ 1503 1504Again, JSON::XS leads by far (except for Storable which non-surprisingly 1505decodes a bit faster). 1506 1507On large strings containing lots of high Unicode characters, some modules 1508(such as JSON::PC) seem to decode faster than JSON::XS, but the result 1509will be broken due to missing (or wrong) Unicode handling. Others refuse 1510to decode or encode properly, so it was impossible to prepare a fair 1511comparison table for that case. 1512 1513 1514=head1 SECURITY CONSIDERATIONS 1515 1516When you are using JSON in a protocol, talking to untrusted potentially 1517hostile creatures requires relatively few measures. 1518 1519First of all, your JSON decoder should be secure, that is, should not have 1520any buffer overflows. Obviously, this module should ensure that and I am 1521trying hard on making that true, but you never know. 1522 1523Second, you need to avoid resource-starving attacks. That means you should 1524limit the size of JSON texts you accept, or make sure then when your 1525resources run out, that's just fine (e.g. by using a separate process that 1526can crash safely). The size of a JSON text in octets or characters is 1527usually a good indication of the size of the resources required to decode 1528it into a Perl structure. While JSON::XS can check the size of the JSON 1529text, it might be too late when you already have it in memory, so you 1530might want to check the size before you accept the string. 1531 1532Third, JSON::XS recurses using the C stack when decoding objects and 1533arrays. The C stack is a limited resource: for instance, on my amd64 1534machine with 8MB of stack size I can decode around 180k nested arrays but 1535only 14k nested JSON objects (due to perl itself recursing deeply on croak 1536to free the temporary). If that is exceeded, the program crashes. To be 1537conservative, the default nesting limit is set to 512. If your process 1538has a smaller stack, you should adjust this setting accordingly with the 1539C<max_depth> method. 1540 1541Something else could bomb you, too, that I forgot to think of. In that 1542case, you get to keep the pieces. I am always open for hints, though... 1543 1544Also keep in mind that JSON::XS might leak contents of your Perl data 1545structures in its error messages, so when you serialise sensitive 1546information you might want to make sure that exceptions thrown by JSON::XS 1547will not end up in front of untrusted eyes. 1548 1549If you are using JSON::XS to return packets to consumption 1550by JavaScript scripts in a browser you should have a look at 1551L<http://blog.archive.jpsykes.com/47/practical-csrf-and-json-security/> to 1552see whether you are vulnerable to some common attack vectors (which really 1553are browser design bugs, but it is still you who will have to deal with 1554it, as major browser developers care only for features, not about getting 1555security right). 1556 1557 1558=head1 INTEROPERABILITY WITH OTHER MODULES 1559 1560C<JSON::XS> uses the L<Types::Serialiser> module to provide boolean 1561constants. That means that the JSON true and false values will be 1562comaptible to true and false values of iother modules that do the same, 1563such as L<JSON::PP> and L<CBOR::XS>. 1564 1565 1566=head1 THREADS 1567 1568This module is I<not> guaranteed to be thread safe and there are no 1569plans to change this until Perl gets thread support (as opposed to the 1570horribly slow so-called "threads" which are simply slow and bloated 1571process simulations - use fork, it's I<much> faster, cheaper, better). 1572 1573(It might actually work, but you have been warned). 1574 1575 1576=head1 THE PERILS OF SETLOCALE 1577 1578Sometimes people avoid the Perl locale support and directly call the 1579system's setlocale function with C<LC_ALL>. 1580 1581This breaks both perl and modules such as JSON::XS, as stringification of 1582numbers no longer works correctly (e.g. C<$x = 0.1; print "$x"+1> might 1583print C<1>, and JSON::XS might output illegal JSON as JSON::XS relies on 1584perl to stringify numbers). 1585 1586The solution is simple: don't call C<setlocale>, or use it for only those 1587categories you need, such as C<LC_MESSAGES> or C<LC_CTYPE>. 1588 1589If you need C<LC_NUMERIC>, you should enable it only around the code that 1590actually needs it (avoiding stringification of numbers), and restore it 1591afterwards. 1592 1593 1594=head1 BUGS 1595 1596While the goal of this module is to be correct, that unfortunately does 1597not mean it's bug-free, only that I think its design is bug-free. If you 1598keep reporting bugs they will be fixed swiftly, though. 1599 1600Please refrain from using rt.cpan.org or any other bug reporting 1601service. I put the contact address into my modules for a reason. 1602 1603=cut 1604 1605BEGIN { 1606 *true = \$Types::Serialiser::true; 1607 *true = \&Types::Serialiser::true; 1608 *false = \$Types::Serialiser::false; 1609 *false = \&Types::Serialiser::false; 1610 *is_bool = \&Types::Serialiser::is_bool; 1611 1612 *JSON::XS::Boolean:: = *Types::Serialiser::Boolean::; 1613} 1614 1615XSLoader::load "JSON::XS", $VERSION; 1616 1617=head1 SEE ALSO 1618 1619The F<json_xs> command line utility for quick experiments. 1620 1621=head1 AUTHOR 1622 1623 Marc Lehmann <schmorp@schmorp.de> 1624 http://home.schmorp.de/ 1625 1626=cut 1627 16281 1629 1630