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

Comparing JSON-XS/README (file contents):
Revision 1.34 by root, Thu Mar 11 17:36:09 2010 UTC vs.
Revision 1.36 by root, Wed Jul 27 15:53:40 2011 UTC

… …
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
… …
635 calls). 636 calls).
636 637
637 JSON::XS will only attempt to parse the JSON text once it is sure it has 638 JSON::XS will only attempt to parse the JSON text once it is sure it has
638 enough text to get a decisive result, using a very simple but truly 639 enough text to get a decisive result, using a very simple but truly
639 incremental parser. This means that it sometimes won't stop as early as 640 incremental parser. This means that it sometimes won't stop as early as
640 the full parser, for example, it doesn't detect parenthese mismatches. 641 the full parser, for example, it doesn't detect mismatched parentheses.
641 The only thing it guarantees is that it starts decoding as soon as a 642 The only thing it guarantees is that it starts decoding as soon as a
642 syntactically valid JSON text has been seen. This means you need to set 643 syntactically valid JSON text has been seen. This means you need to set
643 resource limits (e.g. "max_size") to ensure the parser will stop parsing 644 resource limits (e.g. "max_size") to ensure the parser will stop parsing
644 in the presence if syntax errors. 645 in the presence if syntax errors.
645 646
… …
669 otherwise. For this to work, there must be no separators between the 670 otherwise. For this to work, there must be no separators between the
670 JSON objects or arrays, instead they must be concatenated 671 JSON objects or arrays, instead they must be concatenated
671 back-to-back. If an error occurs, an exception will be raised as in 672 back-to-back. If an error occurs, an exception will be raised as in
672 the scalar context case. Note that in this case, any 673 the scalar context case. Note that in this case, any
673 previously-parsed JSON texts will be lost. 674 previously-parsed JSON texts will be lost.
675
676 Example: Parse some JSON arrays/objects in a given string and return
677 them.
678
679 my @objs = JSON::XS->new->incr_parse ("[5][7][1,2]");
674 680
675 $lvalue_string = $json->incr_text 681 $lvalue_string = $json->incr_text
676 This method returns the currently stored JSON fragment as an lvalue, 682 This method returns the currently stored JSON fragment as an lvalue,
677 that is, you can manipulate it. This *only* works when a preceding 683 that is, you can manipulate it. This *only* works when a preceding
678 call to "incr_parse" in *scalar context* successfully returned an 684 call to "incr_parse" in *scalar context* successfully returned an
… …
893 Numbers containing a fractional or exponential part will always be 899 Numbers containing a fractional or exponential part will always be
894 represented as numeric (floating point) values, possibly at a loss 900 represented as numeric (floating point) values, possibly at a loss
895 of precision (in which case you might lose perfect roundtripping 901 of precision (in which case you might lose perfect roundtripping
896 ability, but the JSON number will still be re-encoded as a JSON 902 ability, but the JSON number will still be re-encoded as a JSON
897 number). 903 number).
904
905 Note that precision is not accuracy - binary floating point values
906 cannot represent most decimal fractions exactly, and when converting
907 from and to floating point, JSON::XS only guarantees precision up to
908 but not including the leats significant bit.
898 909
899 true, false 910 true, false
900 These JSON atoms become "JSON::XS::true" and "JSON::XS::false", 911 These JSON atoms become "JSON::XS::true" and "JSON::XS::false",
901 respectively. They are overloaded to act almost exactly like the 912 respectively. They are overloaded to act almost exactly like the
902 numbers 1 and 0. You can check whether a scalar is a JSON boolean by 913 numbers 1 and 0. You can check whether a scalar is a JSON boolean by
… …
979 990
980 You can not currently force the type in other, less obscure, ways. 991 You can not currently force the type in other, less obscure, ways.
981 Tell me if you need this capability (but don't forget to explain why 992 Tell me if you need this capability (but don't forget to explain why
982 it's needed :). 993 it's needed :).
983 994
995 Note that numerical precision has the same meaning as under Perl (so
996 binary to decimal conversion follows the same rules as in Perl,
997 which can differ to other languages). Also, your perl interpreter
998 might expose extensions to the floating point numbers of your
999 platform, such as infinities or NaN's - these cannot be represented
1000 in JSON, and it is an error to pass those in.
1001
984ENCODING/CODESET FLAG NOTES 1002ENCODING/CODESET FLAG NOTES
985 The interested reader might have seen a number of flags that signify 1003 The interested reader might have seen a number of flags that signify
986 encodings or codesets - "utf8", "latin1" and "ascii". There seems to be 1004 encodings or codesets - "utf8", "latin1" and "ascii". There seems to be
987 some confusion on what these do, so here is a short comparison: 1005 some confusion on what these do, so here is a short comparison:
988 1006
… …
1125 characters as well - using "eval" naively simply *will* cause problems. 1143 characters as well - using "eval" naively simply *will* cause problems.
1126 1144
1127 Another problem is that some javascript implementations reserve some 1145 Another problem is that some javascript implementations reserve some
1128 property names for their own purposes (which probably makes them 1146 property names for their own purposes (which probably makes them
1129 non-ECMAscript-compliant). For example, Iceweasel reserves the 1147 non-ECMAscript-compliant). For example, Iceweasel reserves the
1130 "__proto__" property name for it's own purposes. 1148 "__proto__" property name for its own purposes.
1131 1149
1132 If that is a problem, you could parse try to filter the resulting JSON 1150 If that is a problem, you could parse try to filter the resulting JSON
1133 output for these property strings, e.g.: 1151 output for these property strings, e.g.:
1134 1152
1135 $json =~ s/"__proto__"\s*:/"__proto__renamed":/g; 1153 $json =~ s/"__proto__"\s*:/"__proto__renamed":/g;
… …
1183 (which is not that difficult or long) and finally make YAML 1201 (which is not that difficult or long) and finally make YAML
1184 compatible to it, and educating users about the changes, instead of 1202 compatible to it, and educating users about the changes, instead of
1185 spreading lies about the real compatibility for many *years* and 1203 spreading lies about the real compatibility for many *years* and
1186 trying to silence people who point out that it isn't true. 1204 trying to silence people who point out that it isn't true.
1187 1205
1188 Addendum/2009: the YAML 1.2 spec is still incomaptible with JSON, 1206 Addendum/2009: the YAML 1.2 spec is still incompatible with JSON,
1189 even though the incompatibilities have been documented (and are 1207 even though the incompatibilities have been documented (and are
1190 known to Brian) for many years and the spec makes explicit claims 1208 known to Brian) for many years and the spec makes explicit claims
1191 that YAML is a superset of JSON. It would be so easy to fix, but 1209 that YAML is a superset of JSON. It would be so easy to fix, but
1192 apparently, bullying and corrupting userdata is so much easier. 1210 apparently, bullying people and corrupting userdata is so much
1211 easier.
1193 1212
1194 SPEED 1213 SPEED
1195 It seems that JSON::XS is surprisingly fast, as shown in the following 1214 It seems that JSON::XS is surprisingly fast, as shown in the following
1196 tables. They have been generated with the help of the "eg/bench" program 1215 tables. They have been generated with the help of the "eg/bench" program
1197 in the JSON::XS distribution, to make it easy to compare on your own 1216 in the JSON::XS distribution, to make it easy to compare on your own

Diff Legend

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