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

Comparing JSON-XS/README (file contents):
Revision 1.16 by root, Thu Jul 26 11:33:35 2007 UTC vs.
Revision 1.19 by root, Sat Oct 13 01:57:46 2007 UTC

1NAME 1NAME
2 JSON::XS - JSON serialising/deserialising, done correctly and fast 2 JSON::XS - JSON serialising/deserialising, done correctly and fast
3
4 JSON::XS - 正しくて高速な JSON
5 シリアライザ/デシリアライザ
6 (http://fleur.hio.jp/perldoc/mix/lib/JSON/XS.html)
3 7
4SYNOPSIS 8SYNOPSIS
5 use JSON::XS; 9 use JSON::XS;
6 10
7 # exported functions, they croak on error 11 # exported functions, they croak on error
… …
67FUNCTIONAL INTERFACE 71FUNCTIONAL INTERFACE
68 The following convinience methods are provided by this module. They are 72 The following convinience methods are provided by this module. They are
69 exported by default: 73 exported by default:
70 74
71 $json_text = to_json $perl_scalar 75 $json_text = to_json $perl_scalar
72 Converts the given Perl data structure (a simple scalar or a 76 Converts the given Perl data structure to a UTF-8 encoded, binary
73 reference to a hash or array) to a UTF-8 encoded, binary string
74 (that is, the string contains octets only). Croaks on error. 77 string (that is, the string contains octets only). Croaks on error.
75 78
76 This function call is functionally identical to: 79 This function call is functionally identical to:
77 80
78 $json_text = JSON::XS->new->utf8->encode ($perl_scalar) 81 $json_text = JSON::XS->new->utf8->encode ($perl_scalar)
79 82
80 except being faster. 83 except being faster.
81 84
82 $perl_scalar = from_json $json_text 85 $perl_scalar = from_json $json_text
83 The opposite of "to_json": expects an UTF-8 (binary) string and 86 The opposite of "to_json": expects an UTF-8 (binary) string and
84 tries to parse that as an UTF-8 encoded JSON text, returning the 87 tries to parse that as an UTF-8 encoded JSON text, returning the
85 resulting simple scalar or reference. Croaks on error. 88 resulting reference. Croaks on error.
86 89
87 This function call is functionally identical to: 90 This function call is functionally identical to:
88 91
89 $perl_scalar = JSON::XS->new->utf8->decode ($json_text) 92 $perl_scalar = JSON::XS->new->utf8->decode ($json_text)
90 93
… …
96 respectively and are used to represent JSON "true" and "false" 99 respectively and are used to represent JSON "true" and "false"
97 values in Perl. 100 values in Perl.
98 101
99 See MAPPING, below, for more information on how JSON values are 102 See MAPPING, below, for more information on how JSON values are
100 mapped to Perl. 103 mapped to Perl.
104
105A FEW NOTES ON UNICODE AND PERL
106 Since this often leads to confusion, here are a few very clear words on
107 how Unicode works in Perl, modulo bugs.
108
109 1. Perl strings can store characters with ordinal values > 255.
110 This enables you to store unicode characters as single characters in
111 a Perl string - very natural.
112
113 2. Perl does *not* associate an encoding with your strings.
114 Unless you force it to, e.g. when matching it against a regex, or
115 printing the scalar to a file, in which case Perl either interprets
116 your string as locale-encoded text, octets/binary, or as Unicode,
117 depending on various settings. In no case is an encoding stored
118 together with your data, it is *use* that decides encoding, not any
119 magical metadata.
120
121 3. The internal utf-8 flag has no meaning with regards to the encoding
122 of your string.
123 Just ignore that flag unless you debug a Perl bug, a module written
124 in XS or want to dive into the internals of perl. Otherwise it will
125 only confuse you, as, despite the name, it says nothing about how
126 your string is encoded. You can have unicode strings with that flag
127 set, with that flag clear, and you can have binary data with that
128 flag set and that flag clear. Other possibilities exist, too.
129
130 If you didn't know about that flag, just the better, pretend it
131 doesn't exist.
132
133 4. A "Unicode String" is simply a string where each character can be
134 validly interpreted as a Unicode codepoint.
135 If you have UTF-8 encoded data, it is no longer a Unicode string,
136 but a Unicode string encoded in UTF-8, giving you a binary string.
137
138 5. A string containing "high" (> 255) character values is *not* a UTF-8
139 string.
140 Its a fact. Learn to live with it.
141
142 I hope this helps :)
101 143
102OBJECT-ORIENTED INTERFACE 144OBJECT-ORIENTED INTERFACE
103 The object oriented interface lets you configure your own encoding or 145 The object oriented interface lets you configure your own encoding or
104 decoding style, within the limits of supported formats. 146 decoding style, within the limits of supported formats.
105 147
… …
239 This setting has no effect when decoding JSON texts. 281 This setting has no effect when decoding JSON texts.
240 282
241 Example, space_before and indent disabled, space_after enabled: 283 Example, space_before and indent disabled, space_after enabled:
242 284
243 {"key": "value"} 285 {"key": "value"}
286
287 $json = $json->relaxed ([$enable])
288 If $enable is true (or missing), then "decode" will accept some
289 extensions to normal JSON syntax (see below). "encode" will not be
290 affected in anyway. *Be aware that this option makes you accept
291 invalid JSON texts as if they were valid!*. I suggest only to use
292 this option to parse application-specific files written by humans
293 (configuration files, resource files etc.)
294
295 If $enable is false (the default), then "decode" will only accept
296 valid JSON texts.
297
298 Currently accepted extensions are:
299
300 * list items can have an end-comma
301 JSON *separates* array elements and key-value pairs with commas.
302 This can be annoying if you write JSON texts manually and want
303 to be able to quickly append elements, so this extension accepts
304 comma at the end of such items not just between them:
305
306 [
307 1,
308 2, <- this comma not normally allowed
309 ]
310 {
311 "k1": "v1",
312 "k2": "v2", <- this comma not normally allowed
313 }
314
315 * shell-style '#'-comments
316 Whenever JSON allows whitespace, shell-style comments are
317 additionally allowed. They are terminated by the first
318 carriage-return or line-feed character, after which more
319 white-space and comments are allowed.
320
321 [
322 1, # this comment not allowed in JSON
323 # neither this one...
324 ]
244 325
245 $json = $json->canonical ([$enable]) 326 $json = $json->canonical ([$enable])
246 If $enable is true (or missing), then the "encode" method will 327 If $enable is true (or missing), then the "encode" method will
247 output JSON objects by sorting their keys. This is adding a 328 output JSON objects by sorting their keys. This is adding a
248 comparatively high overhead. 329 comparatively high overhead.
… …
562 643
563 to_json [\0,JSON::XS::true] # yields [false,true] 644 to_json [\0,JSON::XS::true] # yields [false,true]
564 645
565 JSON::XS::true, JSON::XS::false 646 JSON::XS::true, JSON::XS::false
566 These special values become JSON true and JSON false values, 647 These special values become JSON true and JSON false values,
567 respectively. You cna alos use "\1" and "\0" directly if you want. 648 respectively. You can also use "\1" and "\0" directly if you want.
568 649
569 blessed objects 650 blessed objects
570 Blessed objects are not allowed. JSON::XS currently tries to encode 651 Blessed objects are not allowed. JSON::XS currently tries to encode
571 their underlying representation (hash- or arrayref), but this 652 their underlying representation (hash- or arrayref), but this
572 behaviour might change in future versions. 653 behaviour might change in future versions.
… …
807 you are vulnerable to some common attack vectors (which really are 888 you are vulnerable to some common attack vectors (which really are
808 browser design bugs, but it is still you who will have to deal with it, 889 browser design bugs, but it is still you who will have to deal with it,
809 as major browser developers care only for features, not about doing 890 as major browser developers care only for features, not about doing
810 security right). 891 security right).
811 892
893THREADS
894 This module is *not* guarenteed to be thread safe and there are no plans
895 to change this until Perl gets thread support (as opposed to the
896 horribly slow so-called "threads" which are simply slow and bloated
897 process simulations - use fork, its *much* faster, cheaper, better).
898
899 (It might actually work, but you ahve ben warned).
900
812BUGS 901BUGS
813 While the goal of this module is to be correct, that unfortunately does 902 While the goal of this module is to be correct, that unfortunately does
814 not mean its bug-free, only that I think its design is bug-free. It is 903 not mean its bug-free, only that I think its design is bug-free. It is
815 still relatively early in its development. If you keep reporting bugs 904 still relatively early in its development. If you keep reporting bugs
816 they will be fixed swiftly, though. 905 they will be fixed swiftly, though.
817 906
907 Please refrain from using rt.cpan.org or any other bug reporting
908 service. I put the contact address into my modules for a reason.
909
818AUTHOR 910AUTHOR
819 Marc Lehmann <schmorp@schmorp.de> 911 Marc Lehmann <schmorp@schmorp.de>
820 http://home.schmorp.de/ 912 http://home.schmorp.de/
821 913

Diff Legend

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