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

Comparing JSON-XS/README (file contents):
Revision 1.15 by root, Mon Jul 2 08:06:48 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.
… …
502 A JSON string becomes a string scalar in Perl - Unicode codepoints 583 A JSON string becomes a string scalar in Perl - Unicode codepoints
503 in JSON are represented by the same codepoints in the Perl string, 584 in JSON are represented by the same codepoints in the Perl string,
504 so no manual decoding is necessary. 585 so no manual decoding is necessary.
505 586
506 number 587 number
507 A JSON number becomes either an integer or numeric (floating point) 588 A JSON number becomes either an integer, numeric (floating point) or
508 scalar in perl, depending on its range and any fractional parts. On 589 string scalar in perl, depending on its range and any fractional
509 the Perl level, there is no difference between those as Perl handles 590 parts. On the Perl level, there is no difference between those as
510 all the conversion details, but an integer may take slightly less 591 Perl handles all the conversion details, but an integer may take
511 memory and might represent more values exactly than (floating point) 592 slightly less memory and might represent more values exactly than
512 numbers. 593 (floating point) numbers.
594
595 If the number consists of digits only, JSON::XS will try to
596 represent it as an integer value. If that fails, it will try to
597 represent it as a numeric (floating point) value if that is possible
598 without loss of precision. Otherwise it will preserve the number as
599 a string value.
600
601 Numbers containing a fractional or exponential part will always be
602 represented as numeric (floating point) values, possibly at a loss
603 of precision.
604
605 This might create round-tripping problems as numbers might become
606 strings, but as Perl is typeless there is no other way to do it.
513 607
514 true, false 608 true, false
515 These JSON atoms become "JSON::XS::true" and "JSON::XS::false", 609 These JSON atoms become "JSON::XS::true" and "JSON::XS::false",
516 respectively. They are overloaded to act almost exactly like the 610 respectively. They are overloaded to act almost exactly like the
517 numbers 1 and 0. You can check wether a scalar is a JSON boolean by 611 numbers 1 and 0. You can check wether a scalar is a JSON boolean by
… …
549 643
550 to_json [\0,JSON::XS::true] # yields [false,true] 644 to_json [\0,JSON::XS::true] # yields [false,true]
551 645
552 JSON::XS::true, JSON::XS::false 646 JSON::XS::true, JSON::XS::false
553 These special values become JSON true and JSON false values, 647 These special values become JSON true and JSON false values,
554 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.
555 649
556 blessed objects 650 blessed objects
557 Blessed objects are not allowed. JSON::XS currently tries to encode 651 Blessed objects are not allowed. JSON::XS currently tries to encode
558 their underlying representation (hash- or arrayref), but this 652 their underlying representation (hash- or arrayref), but this
559 behaviour might change in future versions. 653 behaviour might change in future versions.
… …
794 you are vulnerable to some common attack vectors (which really are 888 you are vulnerable to some common attack vectors (which really are
795 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,
796 as major browser developers care only for features, not about doing 890 as major browser developers care only for features, not about doing
797 security right). 891 security right).
798 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
799BUGS 901BUGS
800 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
801 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
802 still relatively early in its development. If you keep reporting bugs 904 still relatively early in its development. If you keep reporting bugs
803 they will be fixed swiftly, though. 905 they will be fixed swiftly, though.
804 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
805AUTHOR 910AUTHOR
806 Marc Lehmann <schmorp@schmorp.de> 911 Marc Lehmann <schmorp@schmorp.de>
807 http://home.schmorp.de/ 912 http://home.schmorp.de/
808 913

Diff Legend

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