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

Comparing JSON-XS/README (file contents):
Revision 1.28 by root, Mon Sep 29 03:09:27 2008 UTC vs.
Revision 1.29 by root, Thu Feb 19 01:13:46 2009 UTC

… …
684 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
685 non-JSON text (such as commas). 685 non-JSON text (such as commas).
686 686
687 $json->incr_skip 687 $json->incr_skip
688 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
689 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
690 "incr_parse" died, in which case the input buffer and incremental 690 "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 691 parser state is left unchanged, to skip the text parsed so far and
692 to reset the parse state. 692 to reset the parse state.
693 693
694 The difference to "incr_reset" is that only text until the parse
695 error occured is removed.
696
694 $json->incr_reset 697 $json->incr_reset
695 This completely resets the incremental parser, that is, after this 698 This completely resets the incremental parser, that is, after this
696 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.
697 700
698 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
699 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
700 parser after each successful decode. 703 parser after each successful decode.
701 704
702 LIMITATIONS 705 LIMITATIONS
703 All options that affect decoding are supported, except "allow_nonref". 706 All options that affect decoding are supported, except "allow_nonref".
… …
1068 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
1069 structure back. This is useful when your channel for JSON transfer 1072 structure back. This is useful when your channel for JSON transfer
1070 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.
1071 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
1072 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.
1073 1139
1074 JSON and YAML 1140 JSON and YAML
1075 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
1076 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
1077 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