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

Comparing JSON-XS/README (file contents):
Revision 1.26 by root, Tue Jun 3 06:43:45 2008 UTC vs.
Revision 1.30 by root, Mon Jul 13 22:13:17 2009 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
… …
43 As this is the n-th-something JSON module on CPAN, what was the reason 43 As this is the n-th-something JSON module on CPAN, what was the reason
44 to write yet another JSON module? While it seems there are many JSON 44 to write yet another JSON module? While it seems there are many JSON
45 modules, none of them correctly handle all corner cases, and in most 45 modules, none of them correctly handle all corner cases, and in most
46 cases their maintainers are unresponsive, gone missing, or not listening 46 cases their maintainers are unresponsive, gone missing, or not listening
47 to bug reports for other reasons. 47 to bug reports for other reasons.
48
49 See COMPARISON, below, for a comparison to some other JSON modules.
50 48
51 See MAPPING, below, on how JSON::XS maps perl values to JSON values and 49 See MAPPING, below, on how JSON::XS maps perl values to JSON values and
52 vice versa. 50 vice versa.
53 51
54 FEATURES 52 FEATURES
… …
629 While this module always has to keep both JSON text and resulting Perl 627 While this module always has to keep both JSON text and resulting Perl
630 data structure in memory at one time, it does allow you to parse a JSON 628 data structure in memory at one time, it does allow you to parse a JSON
631 stream incrementally. It does so by accumulating text until it has a 629 stream incrementally. It does so by accumulating text until it has a
632 full JSON object, which it then can decode. This process is similar to 630 full JSON object, which it then can decode. This process is similar to
633 using "decode_prefix" to see if a full JSON object is available, but is 631 using "decode_prefix" to see if a full JSON object is available, but is
634 much more efficient (JSON::XS will only attempt to parse the JSON text 632 much more efficient (and can be implemented with a minimum of method
635 once it is sure it has enough text to get a decisive result, using a 633 calls).
636 very simple but truly incremental parser).
637 634
638 The following two methods deal with this. 635 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
637 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.
639 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
641 resource limits (e.g. "max_size") to ensure the parser will stop parsing
642 in the presence if syntax errors.
643
644 The following methods implement this incremental parser.
639 645
640 [void, scalar or list context] = $json->incr_parse ([$string]) 646 [void, scalar or list context] = $json->incr_parse ([$string])
641 This is the central parsing function. It can both append new text 647 This is the central parsing function. It can both append new text
642 and extract objects from the stream accumulated so far (both of 648 and extract objects from the stream accumulated so far (both of
643 these functions are optional). 649 these functions are optional).
… …
678 after a JSON object or b) parsing multiple JSON objects separated by 684 after a JSON object or b) parsing multiple JSON objects separated by
679 non-JSON text (such as commas). 685 non-JSON text (such as commas).
680 686
681 $json->incr_skip 687 $json->incr_skip
682 This will reset the state of the incremental parser and will remove 688 This will reset the state of the incremental parser and will remove
683 the parsed text from the input buffer. This is useful after 689 the parsed text from the input buffer so far. This is useful after
684 "incr_parse" died, in which case the input buffer and incremental 690 "incr_parse" died, in which case the input buffer and incremental
685 parser state is left unchanged, to skip the text parsed so far and 691 parser state is left unchanged, to skip the text parsed so far and
686 to reset the parse state. 692 to reset the parse state.
687 693
694 The difference to "incr_reset" is that only text until the parse
695 error occured is removed.
696
688 $json->incr_reset 697 $json->incr_reset
689 This completely resets the incremental parser, that is, after this 698 This completely resets the incremental parser, that is, after this
690 call, it will be as if the parser had never parsed anything. 699 call, it will be as if the parser had never parsed anything.
691 700
692 This is useful if you want ot repeatedly parse JSON objects and want 701 This is useful if you want to repeatedly parse JSON objects and want
693 to ignore any trailing data, which means you have to reset the 702 to ignore any trailing data, which means you have to reset the
694 parser after each successful decode. 703 parser after each successful decode.
695 704
696 LIMITATIONS 705 LIMITATIONS
697 All options that affect decoding are supported, except "allow_nonref". 706 All options that affect decoding are supported, except "allow_nonref".
… …
1062 any character set and 8-bit-encoding, and still get the same data 1071 any character set and 8-bit-encoding, and still get the same data
1063 structure back. This is useful when your channel for JSON transfer 1072 structure back. This is useful when your channel for JSON transfer
1064 is not 8-bit clean or the encoding might be mangled in between (e.g. 1073 is not 8-bit clean or the encoding might be mangled in between (e.g.
1065 in mail), and works because ASCII is a proper subset of most 8-bit 1074 in mail), and works because ASCII is a proper subset of most 8-bit
1066 and multibyte encodings in use in the world. 1075 and multibyte encodings in use in the world.
1076
1077 JSON and ECMAscript
1078 JSON syntax is based on how literals are represented in javascript (the
1079 not-standardised predecessor of ECMAscript) which is presumably why it
1080 is called "JavaScript Object Notation".
1081
1082 However, JSON is not a subset (and also not a superset of course) of
1083 ECMAscript (the standard) or javascript (whatever browsers actually
1084 implement).
1085
1086 If you want to use javascript's "eval" function to "parse" JSON, you
1087 might run into parse errors for valid JSON texts, or the resulting data
1088 structure might not be queryable:
1089
1090 One of the problems is that U+2028 and U+2029 are valid characters
1091 inside JSON strings, but are not allowed in ECMAscript string literals,
1092 so the following Perl fragment will not output something that can be
1093 guaranteed to be parsable by javascript's "eval":
1094
1095 use JSON::XS;
1096
1097 print encode_json [chr 0x2028];
1098
1099 The right fix for this is to use a proper JSON parser in your javascript
1100 programs, and not rely on "eval" (see for example Douglas Crockford's
1101 json2.js parser).
1102
1103 If this is not an option, you can, as a stop-gap measure, simply encode
1104 to ASCII-only JSON:
1105
1106 use JSON::XS;
1107
1108 print JSON::XS->new->ascii->encode ([chr 0x2028]);
1109
1110 Note that this will enlarge the resulting JSON text quite a bit if you
1111 have many non-ASCII characters. You might be tempted to run some regexes
1112 to only escape U+2028 and U+2029, e.g.:
1113
1114 # DO NOT USE THIS!
1115 my $json = JSON::XS->new->utf8->encode ([chr 0x2028]);
1116 $json =~ s/\xe2\x80\xa8/\\u2028/g; # escape U+2028
1117 $json =~ s/\xe2\x80\xa9/\\u2029/g; # escape U+2029
1118 print $json;
1119
1120 Note that *this is a bad idea*: the above only works for U+2028 and
1121 U+2029 and thus only for fully ECMAscript-compliant parsers. Many
1122 existing javascript implementations, however, have issues with other
1123 characters as well - using "eval" naively simply *will* cause problems.
1124
1125 Another problem is that some javascript implementations reserve some
1126 property names for their own purposes (which probably makes them
1127 non-ECMAscript-compliant). For example, Iceweasel reserves the
1128 "__proto__" property name for it's own purposes.
1129
1130 If that is a problem, you could parse try to filter the resulting JSON
1131 output for these property strings, e.g.:
1132
1133 $json =~ s/"__proto__"\s*:/"__proto__renamed":/g;
1134
1135 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.
1137
1138 If you know of other incompatibilities, please let me know.
1067 1139
1068 JSON and YAML 1140 JSON and YAML
1069 You often hear that JSON is a subset of YAML. This is, however, a mass 1141 You often hear that JSON is a subset of YAML. This is, however, a mass
1070 hysteria(*) and very far from the truth (as of the time of this 1142 hysteria(*) and very far from the truth (as of the time of this
1071 writing), so let me state it clearly: *in general, there is no way to 1143 writing), so let me state it clearly: *in general, there is no way to

Diff Legend

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