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

Comparing JSON-XS/XS.pm (file contents):
Revision 1.59 by root, Mon Aug 27 01:49:01 2007 UTC vs.
Revision 1.63 by root, Thu Oct 11 23:07:43 2007 UTC

1=encoding utf-8
2
1=head1 NAME 3=head1 NAME
2 4
3JSON::XS - JSON serialising/deserialising, done correctly and fast 5JSON::XS - JSON serialising/deserialising, done correctly and fast
6
7JSON::XS - 正しくて高速な JSON シリアライザ/デシリアライザ
8 (http://fleur.hio.jp/perldoc/mix/lib/JSON/XS.html)
4 9
5=head1 SYNOPSIS 10=head1 SYNOPSIS
6 11
7 use JSON::XS; 12 use JSON::XS;
8 13
… …
98 103
99=over 4 104=over 4
100 105
101=item $json_text = to_json $perl_scalar 106=item $json_text = to_json $perl_scalar
102 107
103Converts the given Perl data structure (a simple scalar or a reference to 108Converts the given Perl data structure to a UTF-8 encoded, binary string
104a hash or array) to a UTF-8 encoded, binary string (that is, the string contains 109(that is, the string contains octets only). Croaks on error.
105octets only). Croaks on error.
106 110
107This function call is functionally identical to: 111This function call is functionally identical to:
108 112
109 $json_text = JSON::XS->new->utf8->encode ($perl_scalar) 113 $json_text = JSON::XS->new->utf8->encode ($perl_scalar)
110 114
111except being faster. 115except being faster.
112 116
113=item $perl_scalar = from_json $json_text 117=item $perl_scalar = from_json $json_text
114 118
115The opposite of C<to_json>: expects an UTF-8 (binary) string and tries to 119The opposite of C<to_json>: expects an UTF-8 (binary) string and tries
116parse that as an UTF-8 encoded JSON text, returning the resulting simple 120to parse that as an UTF-8 encoded JSON text, returning the resulting
117scalar or reference. Croaks on error. 121reference. Croaks on error.
118 122
119This function call is functionally identical to: 123This function call is functionally identical to:
120 124
121 $perl_scalar = JSON::XS->new->utf8->decode ($json_text) 125 $perl_scalar = JSON::XS->new->utf8->decode ($json_text)
122 126
… …
130 134
131See MAPPING, below, for more information on how JSON values are mapped to 135See MAPPING, below, for more information on how JSON values are mapped to
132Perl. 136Perl.
133 137
134=back 138=back
139
140
141=head1 A FEW NOTES ON UNICODE AND PERL
142
143Since this often leads to confusion, here are a few very clear words on
144how Unicode works in Perl, modulo bugs.
145
146=over 4
147
148=item 1. Perl strings can store characters with ordinal values > 255.
149
150This enables you to store unicode characters as single characters in a
151Perl string - very natural.
152
153=item 2. Perl does I<not> associate an encoding with your strings.
154
155Unless you force it to, e.g. when matching it against a regex, or printing
156the scalar to a file, in which case Perl either interprets your string as
157locale-encoded text, octets/binary, or as Unicode, depending on various
158settings. In no case is an encoding stored together with your data, it is
159I<use> that decides encoding, not any magical metadata.
160
161=item 3. The internal utf-8 flag has no meaning with regards to the
162encoding of your string.
163
164Just ignore that flag unless you debug a Perl bug, a module written in
165XS or want to dive into the internals of perl. Otherwise it will only
166confuse you, as, despite the name, it says nothing about how your string
167is encoded. You can have unicode strings with that flag set, with that
168flag clear, and you can have binary data with that flag set and that flag
169clear. Other possibilities exist, too.
170
171If you didn't know about that flag, just the better, pretend it doesn't
172exist.
173
174=item 4. A "Unicode String" is simply a string where each character can be
175validly interpreted as a Unicode codepoint.
176
177If you have UTF-8 encoded data, it is no longer a Unicode string, but a
178Unicode string encoded in UTF-8, giving you a binary string.
179
180=item 5. A string containing "high" (> 255) character values is I<not> a UTF-8 string.
181
182Its a fact. Learn to live with it.
183
184=back
185
186I hope this helps :)
135 187
136 188
137=head1 OBJECT-ORIENTED INTERFACE 189=head1 OBJECT-ORIENTED INTERFACE
138 190
139The object oriented interface lets you configure your own encoding or 191The object oriented interface lets you configure your own encoding or
… …
309 ] 361 ]
310 { 362 {
311 "k1": "v1", 363 "k1": "v1",
312 "k2": "v2", <- this comma not normally allowed 364 "k2": "v2", <- this comma not normally allowed
313 } 365 }
366
367=item * shell-style '#'-comments
368
369Whenever JSON allows whitespace, shell-style comments are additionally
370allowed. They are terminated by the first carriage-return or line-feed
371character, after which more white-space and comments are allowed.
372
373 [
374 1, # this comment not allowed in JSON
375 # neither this one...
376 ]
314 377
315=back 378=back
316 379
317=item $json = $json->canonical ([$enable]) 380=item $json = $json->canonical ([$enable])
318 381
… …
655 to_json [\0,JSON::XS::true] # yields [false,true] 718 to_json [\0,JSON::XS::true] # yields [false,true]
656 719
657=item JSON::XS::true, JSON::XS::false 720=item JSON::XS::true, JSON::XS::false
658 721
659These special values become JSON true and JSON false values, 722These special values become JSON true and JSON false values,
660respectively. You cna alos use C<\1> and C<\0> directly if you want. 723respectively. You can also use C<\1> and C<\0> directly if you want.
661 724
662=item blessed objects 725=item blessed objects
663 726
664Blessed objects are not allowed. JSON::XS currently tries to encode their 727Blessed objects are not allowed. JSON::XS currently tries to encode their
665underlying representation (hash- or arrayref), but this behaviour might 728underlying representation (hash- or arrayref), but this behaviour might

Diff Legend

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