ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/JSON-XS/README
(Generate patch)

Comparing JSON-XS/README (file contents):
Revision 1.29 by root, Thu Feb 19 01:13:46 2009 UTC vs.
Revision 1.39 by root, Tue Oct 29 15:55:49 2013 UTC

… …
20 $perl_scalar = $coder->decode ($unicode_json_text); 20 $perl_scalar = $coder->decode ($unicode_json_text);
21 21
22 # Note that JSON version 2.0 and above will automatically use JSON::XS 22 # Note that JSON version 2.0 and above will automatically use JSON::XS
23 # if available, at virtually no speed overhead either, so you should 23 # if available, at virtually no speed overhead either, so you should
24 # be able to just: 24 # be able to just:
25 25
26 use JSON; 26 use JSON;
27 27
28 # and do the same things, except that you have a pure-perl fallback now. 28 # and do the same things, except that you have a pure-perl fallback now.
29 29
30DESCRIPTION 30DESCRIPTION
31 This module converts Perl data structures to JSON and vice versa. Its 31 This module converts Perl data structures to JSON and vice versa. Its
… …
56 does so, and even documents what "correct" means. 56 does so, and even documents what "correct" means.
57 57
58 * round-trip integrity 58 * round-trip integrity
59 59
60 When you serialise a perl data structure using only data types 60 When you serialise a perl data structure using only data types
61 supported by JSON, the deserialised data structure is identical on 61 supported by JSON and Perl, the deserialised data structure is
62 the Perl level. (e.g. the string "2.0" doesn't suddenly become "2" 62 identical on the Perl level. (e.g. the string "2.0" doesn't suddenly
63 just because it looks like a number). There minor *are* exceptions 63 become "2" just because it looks like a number). There *are* minor
64 to this, read the MAPPING section below to learn about those. 64 exceptions to this, read the MAPPING section below to learn about
65 those.
65 66
66 * strict checking of JSON correctness 67 * strict checking of JSON correctness
67 68
68 There is no guessing, no generating of illegal JSON texts by 69 There is no guessing, no generating of illegal JSON texts by
69 default, and only JSON is accepted as input by default (the latter 70 default, and only JSON is accepted as input by default (the latter
… …
76 too. 77 too.
77 78
78 * simple to use 79 * simple to use
79 80
80 This module has both a simple functional interface as well as an 81 This module has both a simple functional interface as well as an
81 object oriented interface interface. 82 object oriented interface.
82 83
83 * reasonably versatile output formats 84 * reasonably versatile output formats
84 85
85 You can choose between the most compact guaranteed-single-line 86 You can choose between the most compact guaranteed-single-line
86 format possible (nice for simple line-based protocols), a pure-ASCII 87 format possible (nice for simple line-based protocols), a pure-ASCII
… …
111 This function call is functionally identical to: 112 This function call is functionally identical to:
112 113
113 $perl_scalar = JSON::XS->new->utf8->decode ($json_text) 114 $perl_scalar = JSON::XS->new->utf8->decode ($json_text)
114 115
115 Except being faster. 116 Except being faster.
116
117 $is_boolean = JSON::XS::is_bool $scalar
118 Returns true if the passed scalar represents either JSON::XS::true
119 or JSON::XS::false, two constants that act like 1 and 0,
120 respectively and are used to represent JSON "true" and "false"
121 values in Perl.
122
123 See MAPPING, below, for more information on how JSON values are
124 mapped to Perl.
125 117
126A FEW NOTES ON UNICODE AND PERL 118A FEW NOTES ON UNICODE AND PERL
127 Since this often leads to confusion, here are a few very clear words on 119 Since this often leads to confusion, here are a few very clear words on
128 how Unicode works in Perl, modulo bugs. 120 how Unicode works in Perl, modulo bugs.
129 121
… …
368 output JSON objects by sorting their keys. This is adding a 360 output JSON objects by sorting their keys. This is adding a
369 comparatively high overhead. 361 comparatively high overhead.
370 362
371 If $enable is false, then the "encode" method will output key-value 363 If $enable is false, then the "encode" method will output key-value
372 pairs in the order Perl stores them (which will likely change 364 pairs in the order Perl stores them (which will likely change
373 between runs of the same script). 365 between runs of the same script, and can change even within the same
366 run from 5.18 onwards).
374 367
375 This option is useful if you want the same data structure to be 368 This option is useful if you want the same data structure to be
376 encoded as the same JSON text (given the same overall settings). If 369 encoded as the same JSON text (given the same overall settings). If
377 it is disabled, the same hash might be encoded differently even if 370 it is disabled, the same hash might be encoded differently even if
378 contains the same data, as key-value pairs have no inherent ordering 371 contains the same data, as key-value pairs have no inherent ordering
379 in Perl. 372 in Perl.
380 373
381 This setting has no effect when decoding JSON texts. 374 This setting has no effect when decoding JSON texts.
375
376 This setting has currently no effect on tied hashes.
382 377
383 $json = $json->allow_nonref ([$enable]) 378 $json = $json->allow_nonref ([$enable])
384 $enabled = $json->get_allow_nonref 379 $enabled = $json->get_allow_nonref
385 If $enable is true (or missing), then the "encode" method can 380 If $enable is true (or missing), then the "encode" method can
386 convert a non-reference into its corresponding string, number or 381 convert a non-reference into its corresponding string, number or
… …
413 recommended to leave it off unless you know your communications 408 recommended to leave it off unless you know your communications
414 partner. 409 partner.
415 410
416 $json = $json->allow_blessed ([$enable]) 411 $json = $json->allow_blessed ([$enable])
417 $enabled = $json->get_allow_blessed 412 $enabled = $json->get_allow_blessed
413 See "OBJECT SERIALISATION" for details.
414
418 If $enable is true (or missing), then the "encode" method will not 415 If $enable is true (or missing), then the "encode" method will not
419 barf when it encounters a blessed reference. Instead, the value of 416 barf when it encounters a blessed reference that it cannot convert
420 the convert_blessed option will decide whether "null" 417 otherwise. Instead, a JSON "null" value is encoded instead of the
421 ("convert_blessed" disabled or no "TO_JSON" method found) or a 418 object.
422 representation of the object ("convert_blessed" enabled and
423 "TO_JSON" method found) is being encoded. Has no effect on "decode".
424 419
425 If $enable is false (the default), then "encode" will throw an 420 If $enable is false (the default), then "encode" will throw an
426 exception when it encounters a blessed object. 421 exception when it encounters a blessed object that it cannot convert
422 otherwise.
423
424 This setting has no effect on "decode".
427 425
428 $json = $json->convert_blessed ([$enable]) 426 $json = $json->convert_blessed ([$enable])
429 $enabled = $json->get_convert_blessed 427 $enabled = $json->get_convert_blessed
428 See "OBJECT SERIALISATION" for details.
429
430 If $enable is true (or missing), then "encode", upon encountering a 430 If $enable is true (or missing), then "encode", upon encountering a
431 blessed object, will check for the availability of the "TO_JSON" 431 blessed object, will check for the availability of the "TO_JSON"
432 method on the object's class. If found, it will be called in scalar 432 method on the object's class. If found, it will be called in scalar
433 context and the resulting scalar will be encoded instead of the 433 context and the resulting scalar will be encoded instead of the
434 object. If no "TO_JSON" method is found, the value of 434 object.
435 "allow_blessed" will decide what to do.
436 435
437 The "TO_JSON" method may safely call die if it wants. If "TO_JSON" 436 The "TO_JSON" method may safely call die if it wants. If "TO_JSON"
438 returns other blessed objects, those will be handled in the same 437 returns other blessed objects, those will be handled in the same
439 way. "TO_JSON" must take care of not causing an endless recursion 438 way. "TO_JSON" must take care of not causing an endless recursion
440 cycle (== crash) in this case. The name of "TO_JSON" was chosen 439 cycle (== crash) in this case. The name of "TO_JSON" was chosen
441 because other methods called by the Perl core (== not by the user of 440 because other methods called by the Perl core (== not by the user of
442 the object) are usually in upper case letters and to avoid 441 the object) are usually in upper case letters and to avoid
443 collisions with any "to_json" function or method. 442 collisions with any "to_json" function or method.
444 443
445 This setting does not yet influence "decode" in any way, but in the 444 If $enable is false (the default), then "encode" will not consider
446 future, global hooks might get installed that influence "decode" and 445 this type of conversion.
447 are enabled by this setting.
448 446
449 If $enable is false, then the "allow_blessed" setting will decide 447 This setting has no effect on "decode".
450 what to do when a blessed object is found. 448
449 $json = $json->allow_tags ([$enable])
450 $enabled = $json->allow_tags
451 See "OBJECT SERIALISATION" for details.
452
453 If $enable is true (or missing), then "encode", upon encountering a
454 blessed object, will check for the availability of the "FREEZE"
455 method on the object's class. If found, it will be used to serialise
456 the object into a nonstandard tagged JSON value (that JSON decoders
457 cannot decode).
458
459 It also causes "decode" to parse such tagged JSON values and
460 deserialise them via a call to the "THAW" method.
461
462 If $enable is false (the default), then "encode" will not consider
463 this type of conversion, and tagged JSON values will cause a parse
464 error in "decode", as if tags were not part of the grammar.
451 465
452 $json = $json->filter_json_object ([$coderef->($hashref)]) 466 $json = $json->filter_json_object ([$coderef->($hashref)])
453 When $coderef is specified, it will be called from "decode" each 467 When $coderef is specified, it will be called from "decode" each
454 time it decodes a JSON object. The only argument is a reference to 468 time it decodes a JSON object. The only argument is a reference to
455 the newly-created hash. If the code references returns a single 469 the newly-created hash. If the code references returns a single
… …
591 605
592 See SECURITY CONSIDERATIONS, below, for more info on why this is 606 See SECURITY CONSIDERATIONS, below, for more info on why this is
593 useful. 607 useful.
594 608
595 $json_text = $json->encode ($perl_scalar) 609 $json_text = $json->encode ($perl_scalar)
596 Converts the given Perl data structure (a simple scalar or a 610 Converts the given Perl value or data structure to its JSON
597 reference to a hash or array) to its JSON representation. Simple 611 representation. Croaks on error.
598 scalars will be converted into JSON string or number sequences,
599 while references to arrays become JSON arrays and references to
600 hashes become JSON objects. Undefined Perl values (e.g. "undef")
601 become JSON "null" values. Neither "true" nor "false" values will be
602 generated.
603 612
604 $perl_scalar = $json->decode ($json_text) 613 $perl_scalar = $json->decode ($json_text)
605 The opposite of "encode": expects a JSON text and tries to parse it, 614 The opposite of "encode": expects a JSON text and tries to parse it,
606 returning the resulting simple scalar or reference. Croaks on error. 615 returning the resulting simple scalar or reference. Croaks on error.
607
608 JSON numbers and strings become simple Perl scalars. JSON arrays
609 become Perl arrayrefs and JSON objects become Perl hashrefs. "true"
610 becomes 1, "false" becomes 0 and "null" becomes "undef".
611 616
612 ($perl_scalar, $characters) = $json->decode_prefix ($json_text) 617 ($perl_scalar, $characters) = $json->decode_prefix ($json_text)
613 This works like the "decode" method, but instead of raising an 618 This works like the "decode" method, but instead of raising an
614 exception when there is trailing garbage after the first JSON 619 exception when there is trailing garbage after the first JSON
615 object, it will silently stop parsing there and return the number of 620 object, it will silently stop parsing there and return the number of
616 characters consumed so far. 621 characters consumed so far.
617 622
618 This is useful if your JSON texts are not delimited by an outer 623 This is useful if your JSON texts are not delimited by an outer
619 protocol (which is not the brightest thing to do in the first place)
620 and you need to know where the JSON text ends. 624 protocol and you need to know where the JSON text ends.
621 625
622 JSON::XS->new->decode_prefix ("[1] the tail") 626 JSON::XS->new->decode_prefix ("[1] the tail")
623 => ([], 3) 627 => ([], 3)
624 628
625INCREMENTAL PARSING 629INCREMENTAL PARSING
… …
633 calls). 637 calls).
634 638
635 JSON::XS will only attempt to parse the JSON text once it is sure it has 639 JSON::XS will only attempt to parse the JSON text once it is sure it has
636 enough text to get a decisive result, using a very simple but truly 640 enough text to get a decisive result, using a very simple but truly
637 incremental parser. This means that it sometimes won't stop as early as 641 incremental parser. This means that it sometimes won't stop as early as
638 the full parser, for example, it doesn't detect parenthese mismatches. 642 the full parser, for example, it doesn't detect mismatched parentheses.
639 The only thing it guarantees is that it starts decoding as soon as a 643 The only thing it guarantees is that it starts decoding as soon as a
640 syntactically valid JSON text has been seen. This means you need to set 644 syntactically valid JSON text has been seen. This means you need to set
641 resource limits (e.g. "max_size") to ensure the parser will stop parsing 645 resource limits (e.g. "max_size") to ensure the parser will stop parsing
642 in the presence if syntax errors. 646 in the presence if syntax errors.
643 647
… …
657 661
658 If the method is called in scalar context, then it will try to 662 If the method is called in scalar context, then it will try to
659 extract exactly *one* JSON object. If that is successful, it will 663 extract exactly *one* JSON object. If that is successful, it will
660 return this object, otherwise it will return "undef". If there is a 664 return this object, otherwise it will return "undef". If there is a
661 parse error, this method will croak just as "decode" would do (one 665 parse error, this method will croak just as "decode" would do (one
662 can then use "incr_skip" to skip the errornous part). This is the 666 can then use "incr_skip" to skip the erroneous part). This is the
663 most common way of using the method. 667 most common way of using the method.
664 668
665 And finally, in list context, it will try to extract as many objects 669 And finally, in list context, it will try to extract as many objects
666 from the stream as it can find and return them, or the empty list 670 from the stream as it can find and return them, or the empty list
667 otherwise. For this to work, there must be no separators between the 671 otherwise. For this to work, there must be no separators between the
668 JSON objects or arrays, instead they must be concatenated 672 JSON objects or arrays, instead they must be concatenated
669 back-to-back. If an error occurs, an exception will be raised as in 673 back-to-back. If an error occurs, an exception will be raised as in
670 the scalar context case. Note that in this case, any 674 the scalar context case. Note that in this case, any
671 previously-parsed JSON texts will be lost. 675 previously-parsed JSON texts will be lost.
676
677 Example: Parse some JSON arrays/objects in a given string and return
678 them.
679
680 my @objs = JSON::XS->new->incr_parse ("[5][7][1,2]");
672 681
673 $lvalue_string = $json->incr_text 682 $lvalue_string = $json->incr_text
674 This method returns the currently stored JSON fragment as an lvalue, 683 This method returns the currently stored JSON fragment as an lvalue,
675 that is, you can manipulate it. This *only* works when a preceding 684 that is, you can manipulate it. This *only* works when a preceding
676 call to "incr_parse" in *scalar context* successfully returned an 685 call to "incr_parse" in *scalar context* successfully returned an
… …
690 "incr_parse" died, in which case the input buffer and incremental 699 "incr_parse" died, in which case the input buffer and incremental
691 parser state is left unchanged, to skip the text parsed so far and 700 parser state is left unchanged, to skip the text parsed so far and
692 to reset the parse state. 701 to reset the parse state.
693 702
694 The difference to "incr_reset" is that only text until the parse 703 The difference to "incr_reset" is that only text until the parse
695 error occured is removed. 704 error occurred is removed.
696 705
697 $json->incr_reset 706 $json->incr_reset
698 This completely resets the incremental parser, that is, after this 707 This completely resets the incremental parser, that is, after this
699 call, it will be as if the parser had never parsed anything. 708 call, it will be as if the parser had never parsed anything.
700 709
… …
884 If the number consists of digits only, JSON::XS will try to 893 If the number consists of digits only, JSON::XS will try to
885 represent it as an integer value. If that fails, it will try to 894 represent it as an integer value. If that fails, it will try to
886 represent it as a numeric (floating point) value if that is possible 895 represent it as a numeric (floating point) value if that is possible
887 without loss of precision. Otherwise it will preserve the number as 896 without loss of precision. Otherwise it will preserve the number as
888 a string value (in which case you lose roundtripping ability, as the 897 a string value (in which case you lose roundtripping ability, as the
889 JSON number will be re-encoded toa JSON string). 898 JSON number will be re-encoded to a JSON string).
890 899
891 Numbers containing a fractional or exponential part will always be 900 Numbers containing a fractional or exponential part will always be
892 represented as numeric (floating point) values, possibly at a loss 901 represented as numeric (floating point) values, possibly at a loss
893 of precision (in which case you might lose perfect roundtripping 902 of precision (in which case you might lose perfect roundtripping
894 ability, but the JSON number will still be re-encoded as a JSON 903 ability, but the JSON number will still be re-encoded as a JSON
895 number). 904 number).
896 905
906 Note that precision is not accuracy - binary floating point values
907 cannot represent most decimal fractions exactly, and when converting
908 from and to floating point, JSON::XS only guarantees precision up to
909 but not including the least significant bit.
910
897 true, false 911 true, false
898 These JSON atoms become "JSON::XS::true" and "JSON::XS::false", 912 These JSON atoms become "Types::Serialiser::true" and
899 respectively. They are overloaded to act almost exactly like the 913 "Types::Serialiser::false", respectively. They are overloaded to act
900 numbers 1 and 0. You can check whether a scalar is a JSON boolean by 914 almost exactly like the numbers 1 and 0. You can check whether a
901 using the "JSON::XS::is_bool" function. 915 scalar is a JSON boolean by using the "Types::Serialiser::is_bool"
916 function (after "use Types::Serialier", of course).
902 917
903 null 918 null
904 A JSON null atom becomes "undef" in Perl. 919 A JSON null atom becomes "undef" in Perl.
920
921 shell-style comments ("# *text*")
922 As a nonstandard extension to the JSON syntax that is enabled by the
923 "relaxed" setting, shell-style comments are allowed. They can start
924 anywhere outside strings and go till the end of the line.
925
926 tagged values ("(*tag*)*value*").
927 Another nonstandard extension to the JSON syntax, enabled with the
928 "allow_tags" setting, are tagged values. In this implementation, the
929 *tag* must be a perl package/class name encoded as a JSON string,
930 and the *value* must be a JSON array encoding optional constructor
931 arguments.
932
933 See "OBJECT SERIALISATION", below, for details.
905 934
906 PERL -> JSON 935 PERL -> JSON
907 The mapping from Perl to JSON is slightly more difficult, as Perl is a 936 The mapping from Perl to JSON is slightly more difficult, as Perl is a
908 truly typeless language, so we can only guess which JSON type is meant 937 truly typeless language, so we can only guess which JSON type is meant
909 by a Perl value. 938 by a Perl value.
910 939
911 hash references 940 hash references
912 Perl hash references become JSON objects. As there is no inherent 941 Perl hash references become JSON objects. As there is no inherent
913 ordering in hash keys (or JSON objects), they will usually be 942 ordering in hash keys (or JSON objects), they will usually be
914 encoded in a pseudo-random order that can change between runs of the 943 encoded in a pseudo-random order. JSON::XS can optionally sort the
915 same program but stays generally the same within a single run of a 944 hash keys (determined by the *canonical* flag), so the same
916 program. JSON::XS can optionally sort the hash keys (determined by 945 datastructure will serialise to the same JSON text (given same
917 the *canonical* flag), so the same datastructure will serialise to 946 settings and version of JSON::XS), but this incurs a runtime
918 the same JSON text (given same settings and version of JSON::XS), 947 overhead and is only rarely useful, e.g. when you want to compare
919 but this incurs a runtime overhead and is only rarely useful, e.g. 948 some JSON text against another for equality.
920 when you want to compare some JSON text against another for
921 equality.
922 949
923 array references 950 array references
924 Perl array references become JSON arrays. 951 Perl array references become JSON arrays.
925 952
926 other references 953 other references
927 Other unblessed references are generally not allowed and will cause 954 Other unblessed references are generally not allowed and will cause
928 an exception to be thrown, except for references to the integers 0 955 an exception to be thrown, except for references to the integers 0
929 and 1, which get turned into "false" and "true" atoms in JSON. You 956 and 1, which get turned into "false" and "true" atoms in JSON.
930 can also use "JSON::XS::false" and "JSON::XS::true" to improve 957
958 Since "JSON::XS" uses the boolean model from Types::Serialiser, you
959 can also "use Types::Serialiser" and then use
960 "Types::Serialiser::false" and "Types::Serialiser::true" to improve
931 readability. 961 readability.
932 962
963 use Types::Serialiser;
933 encode_json [\0, JSON::XS::true] # yields [false,true] 964 encode_json [\0, Types::Serialiser::true] # yields [false,true]
934 965
935 JSON::XS::true, JSON::XS::false 966 Types::Serialiser::true, Types::Serialiser::false
936 These special values become JSON true and JSON false values, 967 These special values from the Types::Serialiser module become JSON
937 respectively. You can also use "\1" and "\0" directly if you want. 968 true and JSON false values, respectively. You can also use "\1" and
969 "\0" directly if you want.
938 970
939 blessed objects 971 blessed objects
940 Blessed objects are not directly representable in JSON. See the 972 Blessed objects are not directly representable in JSON, but
941 "allow_blessed" and "convert_blessed" methods on various options on 973 "JSON::XS" allows various ways of handling objects. See "OBJECT
942 how to deal with this: basically, you can choose between throwing an 974 SERIALISATION", below, for details.
943 exception, encoding the reference as if it weren't blessed, or
944 provide your own serialiser method.
945 975
946 simple scalars 976 simple scalars
947 Simple Perl scalars (any scalar that is not a reference) are the 977 Simple Perl scalars (any scalar that is not a reference) are the
948 most difficult objects to encode: JSON::XS will encode undefined 978 most difficult objects to encode: JSON::XS will encode undefined
949 scalars as JSON "null" values, scalars that have last been used in a 979 scalars as JSON "null" values, scalars that have last been used in a
… …
977 1007
978 You can not currently force the type in other, less obscure, ways. 1008 You can not currently force the type in other, less obscure, ways.
979 Tell me if you need this capability (but don't forget to explain why 1009 Tell me if you need this capability (but don't forget to explain why
980 it's needed :). 1010 it's needed :).
981 1011
1012 Note that numerical precision has the same meaning as under Perl (so
1013 binary to decimal conversion follows the same rules as in Perl,
1014 which can differ to other languages). Also, your perl interpreter
1015 might expose extensions to the floating point numbers of your
1016 platform, such as infinities or NaN's - these cannot be represented
1017 in JSON, and it is an error to pass those in.
1018
1019 OBJECT SERIALISATION
1020 As JSON cannot directly represent Perl objects, you have to choose
1021 between a pure JSON representation (without the ability to deserialise
1022 the object automatically again), and a nonstandard extension to the JSON
1023 syntax, tagged values.
1024
1025 SERIALISATION
1026 What happens when "JSON::XS" encounters a Perl object depends on the
1027 "allow_blessed", "convert_blessed" and "allow_tags" settings, which are
1028 used in this order:
1029
1030 1. "allow_tags" is enabled and the object has a "FREEZE" method.
1031 In this case, "JSON::XS" uses the Types::Serialiser object
1032 serialisation protocol to create a tagged JSON value, using a
1033 nonstandard extension to the JSON syntax.
1034
1035 This works by invoking the "FREEZE" method on the object, with the
1036 first argument being the object to serialise, and the second
1037 argument being the constant string "JSON" to distinguish it from
1038 other serialisers.
1039
1040 The "FREEZE" method can return any number of values (i.e. zero or
1041 more). These values and the paclkage/classname of the object will
1042 then be encoded as a tagged JSON value in the following format:
1043
1044 ("classname")[FREEZE return values...]
1045
1046 e.g.:
1047
1048 ("URI")["http://www.google.com/"]
1049 ("MyDate")[2013,10,29]
1050 ("ImageData::JPEG")["Z3...VlCg=="]
1051
1052 For example, the hypothetical "My::Object" "FREEZE" method might use
1053 the objects "type" and "id" members to encode the object:
1054
1055 sub My::Object::FREEZE {
1056 my ($self, $serialiser) = @_;
1057
1058 ($self->{type}, $self->{id})
1059 }
1060
1061 2. "convert_blessed" is enabled and the object has a "TO_JSON" method.
1062 In this case, the "TO_JSON" method of the object is invoked in
1063 scalar context. It must return a single scalar that can be directly
1064 encoded into JSON. This scalar replaces the object in the JSON text.
1065
1066 For example, the following "TO_JSON" method will convert all URI
1067 objects to JSON strings when serialised. The fatc that these values
1068 originally were URI objects is lost.
1069
1070 sub URI::TO_JSON {
1071 my ($uri) = @_;
1072 $uri->as_string
1073 }
1074
1075 3. "allow_blessed" is enabled.
1076 The object will be serialised as a JSON null value.
1077
1078 4. none of the above
1079 If none of the settings are enabled or the respective methods are
1080 missing, "JSON::XS" throws an exception.
1081
1082 DESERIALISATION
1083 For deserialisation there are only two cases to consider: either
1084 nonstandard tagging was used, in which case "allow_tags" decides, or
1085 objects cannot be automatically be deserialised, in which case you can
1086 use postprocessing or the "filter_json_object" or
1087 "filter_json_single_key_object" callbacks to get some real objects our
1088 of your JSON.
1089
1090 This section only considers the tagged value case: I a tagged JSON
1091 object is encountered during decoding and "allow_tags" is disabled, a
1092 parse error will result (as if tagged values were not part of the
1093 grammar).
1094
1095 If "allow_tags" is enabled, "JSON::XS" will look up the "THAW" method of
1096 the package/classname used during serialisation (it will not attempt to
1097 load the package as a Perl module). If there is no such method, the
1098 decoding will fail with an error.
1099
1100 Otherwise, the "THAW" method is invoked with the classname as first
1101 argument, the constant string "JSON" as second argument, and all the
1102 values from the JSON array (the values originally returned by the
1103 "FREEZE" method) as remaining arguments.
1104
1105 The method must then return the object. While technically you can return
1106 any Perl scalar, you might have to enable the "enable_nonref" setting to
1107 make that work in all cases, so better return an actual blessed
1108 reference.
1109
1110 As an example, let's implement a "THAW" function that regenerates the
1111 "My::Object" from the "FREEZE" example earlier:
1112
1113 sub My::Object::THAW {
1114 my ($class, $serialiser, $type, $id) = @_;
1115
1116 $class->new (type => $type, id => $id)
1117 }
1118
982ENCODING/CODESET FLAG NOTES 1119ENCODING/CODESET FLAG NOTES
983 The interested reader might have seen a number of flags that signify 1120 The interested reader might have seen a number of flags that signify
984 encodings or codesets - "utf8", "latin1" and "ascii". There seems to be 1121 encodings or codesets - "utf8", "latin1" and "ascii". There seems to be
985 some confusion on what these do, so here is a short comparison: 1122 some confusion on what these do, so here is a short comparison:
986 1123
… …
1005 1142
1006 "utf8" flag disabled 1143 "utf8" flag disabled
1007 When "utf8" is disabled (the default), then "encode"/"decode" 1144 When "utf8" is disabled (the default), then "encode"/"decode"
1008 generate and expect Unicode strings, that is, characters with high 1145 generate and expect Unicode strings, that is, characters with high
1009 ordinal Unicode values (> 255) will be encoded as such characters, 1146 ordinal Unicode values (> 255) will be encoded as such characters,
1010 and likewise such characters are decoded as-is, no canges to them 1147 and likewise such characters are decoded as-is, no changes to them
1011 will be done, except "(re-)interpreting" them as Unicode codepoints 1148 will be done, except "(re-)interpreting" them as Unicode codepoints
1012 or Unicode characters, respectively (to Perl, these are the same 1149 or Unicode characters, respectively (to Perl, these are the same
1013 thing in strings unless you do funny/weird/dumb stuff). 1150 thing in strings unless you do funny/weird/dumb stuff).
1014 1151
1015 This is useful when you want to do the encoding yourself (e.g. when 1152 This is useful when you want to do the encoding yourself (e.g. when
… …
1123 characters as well - using "eval" naively simply *will* cause problems. 1260 characters as well - using "eval" naively simply *will* cause problems.
1124 1261
1125 Another problem is that some javascript implementations reserve some 1262 Another problem is that some javascript implementations reserve some
1126 property names for their own purposes (which probably makes them 1263 property names for their own purposes (which probably makes them
1127 non-ECMAscript-compliant). For example, Iceweasel reserves the 1264 non-ECMAscript-compliant). For example, Iceweasel reserves the
1128 "__proto__" property name for it's own purposes. 1265 "__proto__" property name for its own purposes.
1129 1266
1130 If that is a problem, you could parse try to filter the resulting JSON 1267 If that is a problem, you could parse try to filter the resulting JSON
1131 output for these property strings, e.g.: 1268 output for these property strings, e.g.:
1132 1269
1133 $json =~ s/"__proto__"\s*:/"__proto__renamed":/g; 1270 $json =~ s/"__proto__"\s*:/"__proto__renamed":/g;
1134 1271
1135 This works because "__proto__" is not valid outside of strings, so every 1272 This works because "__proto__" is not valid outside of strings, so every
1136 occurence of ""__proto__"\s*:" must be a string used as property name. 1273 occurrence of ""__proto__"\s*:" must be a string used as property name.
1137 1274
1138 If you know of other incompatibilities, please let me know. 1275 If you know of other incompatibilities, please let me know.
1139 1276
1140 JSON and YAML 1277 JSON and YAML
1141 You often hear that JSON is a subset of YAML. This is, however, a mass 1278 You often hear that JSON is a subset of YAML. This is, however, a mass
… …
1151 my $yaml = $to_yaml->encode ($ref) . "\n"; 1288 my $yaml = $to_yaml->encode ($ref) . "\n";
1152 1289
1153 This will *usually* generate JSON texts that also parse as valid YAML. 1290 This will *usually* generate JSON texts that also parse as valid YAML.
1154 Please note that YAML has hardcoded limits on (simple) object key 1291 Please note that YAML has hardcoded limits on (simple) object key
1155 lengths that JSON doesn't have and also has different and incompatible 1292 lengths that JSON doesn't have and also has different and incompatible
1156 unicode handling, so you should make sure that your hash keys are 1293 unicode character escape syntax, so you should make sure that your hash
1157 noticeably shorter than the 1024 "stream characters" YAML allows and 1294 keys are noticeably shorter than the 1024 "stream characters" YAML
1158 that you do not have characters with codepoint values outside the 1295 allows and that you do not have characters with codepoint values outside
1159 Unicode BMP (basic multilingual page). YAML also does not allow "\/" 1296 the Unicode BMP (basic multilingual page). YAML also does not allow "\/"
1160 sequences in strings (which JSON::XS does not *currently* generate, but 1297 sequences in strings (which JSON::XS does not *currently* generate, but
1161 other JSON generators might). 1298 other JSON generators might).
1162 1299
1163 There might be other incompatibilities that I am not aware of (or the 1300 There might be other incompatibilities that I am not aware of (or the
1164 YAML specification has been changed yet again - it does so quite often). 1301 YAML specification has been changed yet again - it does so quite often).
… …
1181 (which is not that difficult or long) and finally make YAML 1318 (which is not that difficult or long) and finally make YAML
1182 compatible to it, and educating users about the changes, instead of 1319 compatible to it, and educating users about the changes, instead of
1183 spreading lies about the real compatibility for many *years* and 1320 spreading lies about the real compatibility for many *years* and
1184 trying to silence people who point out that it isn't true. 1321 trying to silence people who point out that it isn't true.
1185 1322
1323 Addendum/2009: the YAML 1.2 spec is still incompatible with JSON,
1324 even though the incompatibilities have been documented (and are
1325 known to Brian) for many years and the spec makes explicit claims
1326 that YAML is a superset of JSON. It would be so easy to fix, but
1327 apparently, bullying people and corrupting userdata is so much
1328 easier.
1329
1186 SPEED 1330 SPEED
1187 It seems that JSON::XS is surprisingly fast, as shown in the following 1331 It seems that JSON::XS is surprisingly fast, as shown in the following
1188 tables. They have been generated with the help of the "eg/bench" program 1332 tables. They have been generated with the help of the "eg/bench" program
1189 in the JSON::XS distribution, to make it easy to compare on your own 1333 in the JSON::XS distribution, to make it easy to compare on your own
1190 system. 1334 system.
… …
1193 single-line JSON string (also available at 1337 single-line JSON string (also available at
1194 <http://dist.schmorp.de/misc/json/short.json>). 1338 <http://dist.schmorp.de/misc/json/short.json>).
1195 1339
1196 {"method": "handleMessage", "params": ["user1", 1340 {"method": "handleMessage", "params": ["user1",
1197 "we were just talking"], "id": null, "array":[1,11,234,-5,1e5,1e7, 1341 "we were just talking"], "id": null, "array":[1,11,234,-5,1e5,1e7,
1198 true, false]} 1342 1, 0]}
1199 1343
1200 It shows the number of encodes/decodes per second (JSON::XS uses the 1344 It shows the number of encodes/decodes per second (JSON::XS uses the
1201 functional interface, while JSON::XS/2 uses the OO interface with 1345 functional interface, while JSON::XS/2 uses the OO interface with
1202 pretty-printing and hashkey sorting enabled, JSON::XS/3 enables shrink). 1346 pretty-printing and hashkey sorting enabled, JSON::XS/3 enables shrink.
1203 Higher is better: 1347 JSON::DWIW/DS uses the deserialise function, while JSON::DWIW::FJ uses
1348 the from_json method). Higher is better:
1204 1349
1205 module | encode | decode | 1350 module | encode | decode |
1206 -----------|------------|------------| 1351 --------------|------------|------------|
1207 JSON 1.x | 4990.842 | 4088.813 | 1352 JSON::DWIW/DS | 86302.551 | 102300.098 |
1208 JSON::DWIW | 51653.990 | 71575.154 | 1353 JSON::DWIW/FJ | 86302.551 | 75983.768 |
1209 JSON::PC | 65948.176 | 74631.744 | 1354 JSON::PP | 15827.562 | 6638.658 |
1210 JSON::PP | 8931.652 | 3817.168 | 1355 JSON::Syck | 63358.066 | 47662.545 |
1211 JSON::Syck | 24877.248 | 27776.848 | 1356 JSON::XS | 511500.488 | 511500.488 |
1212 JSON::XS | 388361.481 | 227951.304 | 1357 JSON::XS/2 | 291271.111 | 388361.481 |
1213 JSON::XS/2 | 227951.304 | 218453.333 | 1358 JSON::XS/3 | 361577.931 | 361577.931 |
1214 JSON::XS/3 | 338250.323 | 218453.333 | 1359 Storable | 66788.280 | 265462.278 |
1215 Storable | 16500.016 | 135300.129 |
1216 -----------+------------+------------+ 1360 --------------+------------+------------+
1217 1361
1218 That is, JSON::XS is about five times faster than JSON::DWIW on 1362 That is, JSON::XS is almost six times faster than JSON::DWIW on
1219 encoding, about three times faster on decoding, and over forty times 1363 encoding, about five times faster on decoding, and over thirty to
1220 faster than JSON, even with pretty-printing and key sorting. It also 1364 seventy times faster than JSON's pure perl implementation. It also
1221 compares favourably to Storable for small amounts of data. 1365 compares favourably to Storable for small amounts of data.
1222 1366
1223 Using a longer test string (roughly 18KB, generated from Yahoo! Locals 1367 Using a longer test string (roughly 18KB, generated from Yahoo! Locals
1224 search API (<http://dist.schmorp.de/misc/json/long.json>). 1368 search API (<http://dist.schmorp.de/misc/json/long.json>).
1225 1369
1226 module | encode | decode | 1370 module | encode | decode |
1227 -----------|------------|------------| 1371 --------------|------------|------------|
1228 JSON 1.x | 55.260 | 34.971 | 1372 JSON::DWIW/DS | 1647.927 | 2673.916 |
1229 JSON::DWIW | 825.228 | 1082.513 | 1373 JSON::DWIW/FJ | 1630.249 | 2596.128 |
1230 JSON::PC | 3571.444 | 2394.829 |
1231 JSON::PP | 210.987 | 32.574 | 1374 JSON::PP | 400.640 | 62.311 |
1232 JSON::Syck | 552.551 | 787.544 | 1375 JSON::Syck | 1481.040 | 1524.869 |
1233 JSON::XS | 5780.463 | 4854.519 | 1376 JSON::XS | 20661.596 | 9541.183 |
1234 JSON::XS/2 | 3869.998 | 4798.975 | 1377 JSON::XS/2 | 10683.403 | 9416.938 |
1235 JSON::XS/3 | 5862.880 | 4798.975 | 1378 JSON::XS/3 | 20661.596 | 9400.054 |
1236 Storable | 4445.002 | 5235.027 | 1379 Storable | 19765.806 | 10000.725 |
1237 -----------+------------+------------+ 1380 --------------+------------+------------+
1238 1381
1239 Again, JSON::XS leads by far (except for Storable which non-surprisingly 1382 Again, JSON::XS leads by far (except for Storable which non-surprisingly
1240 decodes faster). 1383 decodes a bit faster).
1241 1384
1242 On large strings containing lots of high Unicode characters, some 1385 On large strings containing lots of high Unicode characters, some
1243 modules (such as JSON::PC) seem to decode faster than JSON::XS, but the 1386 modules (such as JSON::PC) seem to decode faster than JSON::XS, but the
1244 result will be broken due to missing (or wrong) Unicode handling. Others 1387 result will be broken due to missing (or wrong) Unicode handling. Others
1245 refuse to decode or encode properly, so it was impossible to prepare a 1388 refuse to decode or encode properly, so it was impossible to prepare a
… …
1280 information you might want to make sure that exceptions thrown by 1423 information you might want to make sure that exceptions thrown by
1281 JSON::XS will not end up in front of untrusted eyes. 1424 JSON::XS will not end up in front of untrusted eyes.
1282 1425
1283 If you are using JSON::XS to return packets to consumption by JavaScript 1426 If you are using JSON::XS to return packets to consumption by JavaScript
1284 scripts in a browser you should have a look at 1427 scripts in a browser you should have a look at
1285 <http://jpsykes.com/47/practical-csrf-and-json-security> to see whether 1428 <http://blog.archive.jpsykes.com/47/practical-csrf-and-json-security/>
1286 you are vulnerable to some common attack vectors (which really are 1429 to see whether you are vulnerable to some common attack vectors (which
1287 browser design bugs, but it is still you who will have to deal with it, 1430 really are browser design bugs, but it is still you who will have to
1288 as major browser developers care only for features, not about getting 1431 deal with it, as major browser developers care only for features, not
1289 security right). 1432 about getting security right).
1433
1434INTEROPERABILITY WITH OTHER MODULES
1435 "JSON::XS" uses the Types::Serialiser module to provide boolean
1436 constants. That means that the JSON true and false values will be
1437 comaptible to true and false values of iother modules that do the same,
1438 such as JSON::PP and CBOR::XS.
1290 1439
1291THREADS 1440THREADS
1292 This module is *not* guaranteed to be thread safe and there are no plans 1441 This module is *not* guaranteed to be thread safe and there are no plans
1293 to change this until Perl gets thread support (as opposed to the 1442 to change this until Perl gets thread support (as opposed to the
1294 horribly slow so-called "threads" which are simply slow and bloated 1443 horribly slow so-called "threads" which are simply slow and bloated
1295 process simulations - use fork, it's *much* faster, cheaper, better). 1444 process simulations - use fork, it's *much* faster, cheaper, better).
1296 1445
1297 (It might actually work, but you have been warned). 1446 (It might actually work, but you have been warned).
1298 1447
1448THE PERILS OF SETLOCALE
1449 Sometimes people avoid the Perl locale support and directly call the
1450 system's setlocale function with "LC_ALL".
1451
1452 This breaks both perl and modules such as JSON::XS, as stringification
1453 of numbers no longer works correctly (e.g. "$x = 0.1; print "$x"+1"
1454 might print 1, and JSON::XS might output illegal JSON as JSON::XS relies
1455 on perl to stringify numbers).
1456
1457 The solution is simple: don't call "setlocale", or use it for only those
1458 categories you need, such as "LC_MESSAGES" or "LC_CTYPE".
1459
1460 If you need "LC_NUMERIC", you should enable it only around the code that
1461 actually needs it (avoiding stringification of numbers), and restore it
1462 afterwards.
1463
1299BUGS 1464BUGS
1300 While the goal of this module is to be correct, that unfortunately does 1465 While the goal of this module is to be correct, that unfortunately does
1301 not mean it's bug-free, only that I think its design is bug-free. If you 1466 not mean it's bug-free, only that I think its design is bug-free. If you
1302 keep reporting bugs they will be fixed swiftly, though. 1467 keep reporting bugs they will be fixed swiftly, though.
1303 1468

Diff Legend

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