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.31 by root, Sat Aug 8 10:06:02 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
… …
377 it is disabled, the same hash might be encoded differently even if 377 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 378 contains the same data, as key-value pairs have no inherent ordering
379 in Perl. 379 in Perl.
380 380
381 This setting has no effect when decoding JSON texts. 381 This setting has no effect when decoding JSON texts.
382
383 This setting has currently no effect on tied hashes.
382 384
383 $json = $json->allow_nonref ([$enable]) 385 $json = $json->allow_nonref ([$enable])
384 $enabled = $json->get_allow_nonref 386 $enabled = $json->get_allow_nonref
385 If $enable is true (or missing), then the "encode" method can 387 If $enable is true (or missing), then the "encode" method can
386 convert a non-reference into its corresponding string, number or 388 convert a non-reference into its corresponding string, number or
… …
684 after a JSON object or b) parsing multiple JSON objects separated by 686 after a JSON object or b) parsing multiple JSON objects separated by
685 non-JSON text (such as commas). 687 non-JSON text (such as commas).
686 688
687 $json->incr_skip 689 $json->incr_skip
688 This will reset the state of the incremental parser and will remove 690 This will reset the state of the incremental parser and will remove
689 the parsed text from the input buffer. This is useful after 691 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 692 "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 693 parser state is left unchanged, to skip the text parsed so far and
692 to reset the parse state. 694 to reset the parse state.
693 695
696 The difference to "incr_reset" is that only text until the parse
697 error occured is removed.
698
694 $json->incr_reset 699 $json->incr_reset
695 This completely resets the incremental parser, that is, after this 700 This completely resets the incremental parser, that is, after this
696 call, it will be as if the parser had never parsed anything. 701 call, it will be as if the parser had never parsed anything.
697 702
698 This is useful if you want ot repeatedly parse JSON objects and want 703 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 704 to ignore any trailing data, which means you have to reset the
700 parser after each successful decode. 705 parser after each successful decode.
701 706
702 LIMITATIONS 707 LIMITATIONS
703 All options that affect decoding are supported, except "allow_nonref". 708 All options that affect decoding are supported, except "allow_nonref".
… …
1068 any character set and 8-bit-encoding, and still get the same data 1073 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 1074 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. 1075 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 1076 in mail), and works because ASCII is a proper subset of most 8-bit
1072 and multibyte encodings in use in the world. 1077 and multibyte encodings in use in the world.
1078
1079 JSON and ECMAscript
1080 JSON syntax is based on how literals are represented in javascript (the
1081 not-standardised predecessor of ECMAscript) which is presumably why it
1082 is called "JavaScript Object Notation".
1083
1084 However, JSON is not a subset (and also not a superset of course) of
1085 ECMAscript (the standard) or javascript (whatever browsers actually
1086 implement).
1087
1088 If you want to use javascript's "eval" function to "parse" JSON, you
1089 might run into parse errors for valid JSON texts, or the resulting data
1090 structure might not be queryable:
1091
1092 One of the problems is that U+2028 and U+2029 are valid characters
1093 inside JSON strings, but are not allowed in ECMAscript string literals,
1094 so the following Perl fragment will not output something that can be
1095 guaranteed to be parsable by javascript's "eval":
1096
1097 use JSON::XS;
1098
1099 print encode_json [chr 0x2028];
1100
1101 The right fix for this is to use a proper JSON parser in your javascript
1102 programs, and not rely on "eval" (see for example Douglas Crockford's
1103 json2.js parser).
1104
1105 If this is not an option, you can, as a stop-gap measure, simply encode
1106 to ASCII-only JSON:
1107
1108 use JSON::XS;
1109
1110 print JSON::XS->new->ascii->encode ([chr 0x2028]);
1111
1112 Note that this will enlarge the resulting JSON text quite a bit if you
1113 have many non-ASCII characters. You might be tempted to run some regexes
1114 to only escape U+2028 and U+2029, e.g.:
1115
1116 # DO NOT USE THIS!
1117 my $json = JSON::XS->new->utf8->encode ([chr 0x2028]);
1118 $json =~ s/\xe2\x80\xa8/\\u2028/g; # escape U+2028
1119 $json =~ s/\xe2\x80\xa9/\\u2029/g; # escape U+2029
1120 print $json;
1121
1122 Note that *this is a bad idea*: the above only works for U+2028 and
1123 U+2029 and thus only for fully ECMAscript-compliant parsers. Many
1124 existing javascript implementations, however, have issues with other
1125 characters as well - using "eval" naively simply *will* cause problems.
1126
1127 Another problem is that some javascript implementations reserve some
1128 property names for their own purposes (which probably makes them
1129 non-ECMAscript-compliant). For example, Iceweasel reserves the
1130 "__proto__" property name for it's own purposes.
1131
1132 If that is a problem, you could parse try to filter the resulting JSON
1133 output for these property strings, e.g.:
1134
1135 $json =~ s/"__proto__"\s*:/"__proto__renamed":/g;
1136
1137 This works because "__proto__" is not valid outside of strings, so every
1138 occurence of ""__proto__"\s*:" must be a string used as property name.
1139
1140 If you know of other incompatibilities, please let me know.
1073 1141
1074 JSON and YAML 1142 JSON and YAML
1075 You often hear that JSON is a subset of YAML. This is, however, a mass 1143 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 1144 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 1145 writing), so let me state it clearly: *in general, there is no way to

Diff Legend

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