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

Comparing JSON-XS/README (file contents):
Revision 1.10 by root, Wed Apr 4 00:01:44 2007 UTC vs.
Revision 1.11 by root, Wed May 9 16:35:21 2007 UTC

… …
112 $json = $json->ascii ([$enable]) 112 $json = $json->ascii ([$enable])
113 If $enable is true (or missing), then the "encode" method will not 113 If $enable is true (or missing), then the "encode" method will not
114 generate characters outside the code range 0..127 (which is ASCII). 114 generate characters outside the code range 0..127 (which is ASCII).
115 Any unicode characters outside that range will be escaped using 115 Any unicode characters outside that range will be escaped using
116 either a single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL 116 either a single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL
117 escape sequence, as per RFC4627. 117 escape sequence, as per RFC4627. The resulting encoded JSON text can
118 be treated as a native unicode string, an ascii-encoded,
119 latin1-encoded or UTF-8 encoded string, or any other superset of
120 ASCII.
118 121
119 If $enable is false, then the "encode" method will not escape 122 If $enable is false, then the "encode" method will not escape
120 Unicode characters unless required by the JSON syntax. This results 123 Unicode characters unless required by the JSON syntax or other
121 in a faster and more compact format. 124 flags. This results in a faster and more compact format.
125
126 The main use for this flag is to produce JSON texts that can be
127 transmitted over a 7-bit channel, as the encoded JSON texts will not
128 contain any 8 bit characters.
122 129
123 JSON::XS->new->ascii (1)->encode ([chr 0x10401]) 130 JSON::XS->new->ascii (1)->encode ([chr 0x10401])
124 => ["\ud801\udc01"] 131 => ["\ud801\udc01"]
132
133 $json = $json->latin1 ([$enable])
134 If $enable is true (or missing), then the "encode" method will
135 encode the resulting JSON text as latin1 (or iso-8859-1), escaping
136 any characters outside the code range 0..255. The resulting string
137 can be treated as a latin1-encoded JSON text or a native unicode
138 string. The "decode" method will not be affected in any way by this
139 flag, as "decode" by default expects unicode, which is a strict
140 superset of latin1.
141
142 If $enable is false, then the "encode" method will not escape
143 Unicode characters unless required by the JSON syntax or other
144 flags.
145
146 The main use for this flag is efficiently encoding binary data as
147 JSON text, as most octets will not be escaped, resulting in a
148 smaller encoded size. The disadvantage is that the resulting JSON
149 text is encoded in latin1 (and must correctly be treated as such
150 when storing and transfering), a rare encoding for JSON. It is
151 therefore most useful when you want to store data structures known
152 to contain binary data efficiently in files or databases, not when
153 talking to other JSON encoders/decoders.
154
155 JSON::XS->new->latin1->encode (["\x{89}\x{abc}"]
156 => ["\x{89}\\u0abc"] # (perl syntax, U+abc escaped, U+89 not)
125 157
126 $json = $json->utf8 ([$enable]) 158 $json = $json->utf8 ([$enable])
127 If $enable is true (or missing), then the "encode" method will 159 If $enable is true (or missing), then the "encode" method will
128 encode the JSON result into UTF-8, as required by many protocols, 160 encode the JSON result into UTF-8, as required by many protocols,
129 while the "decode" method expects to be handled an UTF-8-encoded 161 while the "decode" method expects to be handled an UTF-8-encoded
… …
300 returning the resulting simple scalar or reference. Croaks on error. 332 returning the resulting simple scalar or reference. Croaks on error.
301 333
302 JSON numbers and strings become simple Perl scalars. JSON arrays 334 JSON numbers and strings become simple Perl scalars. JSON arrays
303 become Perl arrayrefs and JSON objects become Perl hashrefs. "true" 335 become Perl arrayrefs and JSON objects become Perl hashrefs. "true"
304 becomes 1, "false" becomes 0 and "null" becomes "undef". 336 becomes 1, "false" becomes 0 and "null" becomes "undef".
337
338 ($perl_scalar, $characters) = $json->decode_prefix ($json_text)
339 This works like the "decode" method, but instead of raising an
340 exception when there is trailing garbage after the first JSON
341 object, it will silently stop parsing there and return the number of
342 characters consumed so far.
343
344 This is useful if your JSON texts are not delimited by an outer
345 protocol (which is not the brightest thing to do in the first place)
346 and you need to know where the JSON text ends.
347
348 JSON::XS->new->decode_prefix ("[1] the tail")
349 => ([], 3)
305 350
306MAPPING 351MAPPING
307 This section describes how JSON::XS maps Perl values to JSON values and 352 This section describes how JSON::XS maps Perl values to JSON values and
308 vice versa. These mappings are designed to "do the right thing" in most 353 vice versa. These mappings are designed to "do the right thing" in most
309 circumstances automatically, preserving round-tripping characteristics 354 circumstances automatically, preserving round-tripping characteristics
… …
565 to be conservative, the default nesting limit is set to 512. If your 610 to be conservative, the default nesting limit is set to 512. If your
566 process has a smaller stack, you should adjust this setting accordingly 611 process has a smaller stack, you should adjust this setting accordingly
567 with the "max_depth" method. 612 with the "max_depth" method.
568 613
569 And last but least, something else could bomb you that I forgot to think 614 And last but least, something else could bomb you that I forgot to think
570 of. In that case, you get to keep the pieces. I am alway sopen for 615 of. In that case, you get to keep the pieces. I am always open for
571 hints, though... 616 hints, though...
572 617
573BUGS 618BUGS
574 While the goal of this module is to be correct, that unfortunately does 619 While the goal of this module is to be correct, that unfortunately does
575 not mean its bug-free, only that I think its design is bug-free. It is 620 not mean its bug-free, only that I think its design is bug-free. It is

Diff Legend

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