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.56 by root, Thu Jul 26 11:33:35 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
… …
81 86
82package JSON::XS; 87package JSON::XS;
83 88
84use strict; 89use strict;
85 90
86our $VERSION = '1.43'; 91our $VERSION = '1.5';
87our @ISA = qw(Exporter); 92our @ISA = qw(Exporter);
88 93
89our @EXPORT = qw(to_json from_json); 94our @EXPORT = qw(to_json from_json);
90 95
91use Exporter; 96use Exporter;
… …
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
… …
277This setting has no effect when decoding JSON texts. 329This setting has no effect when decoding JSON texts.
278 330
279Example, space_before and indent disabled, space_after enabled: 331Example, space_before and indent disabled, space_after enabled:
280 332
281 {"key": "value"} 333 {"key": "value"}
334
335=item $json = $json->relaxed ([$enable])
336
337If C<$enable> is true (or missing), then C<decode> will accept some
338extensions to normal JSON syntax (see below). C<encode> will not be
339affected in anyway. I<Be aware that this option makes you accept invalid
340JSON texts as if they were valid!>. I suggest only to use this option to
341parse application-specific files written by humans (configuration files,
342resource files etc.)
343
344If C<$enable> is false (the default), then C<decode> will only accept
345valid JSON texts.
346
347Currently accepted extensions are:
348
349=over 4
350
351=item * list items can have an end-comma
352
353JSON I<separates> array elements and key-value pairs with commas. This
354can be annoying if you write JSON texts manually and want to be able to
355quickly append elements, so this extension accepts comma at the end of
356such items not just between them:
357
358 [
359 1,
360 2, <- this comma not normally allowed
361 ]
362 {
363 "k1": "v1",
364 "k2": "v2", <- this comma not normally allowed
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 ]
377
378=back
282 379
283=item $json = $json->canonical ([$enable]) 380=item $json = $json->canonical ([$enable])
284 381
285If C<$enable> is true (or missing), then the C<encode> method will output JSON objects 382If C<$enable> is true (or missing), then the C<encode> method will output JSON objects
286by sorting their keys. This is adding a comparatively high overhead. 383by sorting their keys. This is adding a comparatively high overhead.
… …
621 to_json [\0,JSON::XS::true] # yields [false,true] 718 to_json [\0,JSON::XS::true] # yields [false,true]
622 719
623=item JSON::XS::true, JSON::XS::false 720=item JSON::XS::true, JSON::XS::false
624 721
625These special values become JSON true and JSON false values, 722These special values become JSON true and JSON false values,
626respectively. 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.
627 724
628=item blessed objects 725=item blessed objects
629 726
630Blessed objects are not allowed. JSON::XS currently tries to encode their 727Blessed objects are not allowed. JSON::XS currently tries to encode their
631underlying 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