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.60 by root, Mon Aug 27 02:03:23 2007 UTC vs.
Revision 1.67 by root, Mon Oct 15 01:22:34 2007 UTC

1=head1 NAME 1=head1 NAME
2 2
3JSON::XS - JSON serialising/deserialising, done correctly and fast 3JSON::XS - JSON serialising/deserialising, done correctly and fast
4
5JSON::XS - 正しくて高速な JSON シリアライザ/デシリアライザ
6 (http://fleur.hio.jp/perldoc/mix/lib/JSON/XS.html)
4 7
5=head1 SYNOPSIS 8=head1 SYNOPSIS
6 9
7 use JSON::XS; 10 use JSON::XS;
8 11
… …
81 84
82package JSON::XS; 85package JSON::XS;
83 86
84use strict; 87use strict;
85 88
86our $VERSION = '1.5'; 89our $VERSION = '1.52';
87our @ISA = qw(Exporter); 90our @ISA = qw(Exporter);
88 91
89our @EXPORT = qw(to_json from_json); 92our @EXPORT = qw(to_json from_json);
90 93
91use Exporter; 94use Exporter;
… …
98 101
99=over 4 102=over 4
100 103
101=item $json_text = to_json $perl_scalar 104=item $json_text = to_json $perl_scalar
102 105
103Converts the given Perl data structure (a simple scalar or a reference to 106Converts 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 107(that is, the string contains octets only). Croaks on error.
105octets only). Croaks on error.
106 108
107This function call is functionally identical to: 109This function call is functionally identical to:
108 110
109 $json_text = JSON::XS->new->utf8->encode ($perl_scalar) 111 $json_text = JSON::XS->new->utf8->encode ($perl_scalar)
110 112
111except being faster. 113except being faster.
112 114
113=item $perl_scalar = from_json $json_text 115=item $perl_scalar = from_json $json_text
114 116
115The opposite of C<to_json>: expects an UTF-8 (binary) string and tries to 117The 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 118to parse that as an UTF-8 encoded JSON text, returning the resulting
117scalar or reference. Croaks on error. 119reference. Croaks on error.
118 120
119This function call is functionally identical to: 121This function call is functionally identical to:
120 122
121 $perl_scalar = JSON::XS->new->utf8->decode ($json_text) 123 $perl_scalar = JSON::XS->new->utf8->decode ($json_text)
122 124
… …
130 132
131See MAPPING, below, for more information on how JSON values are mapped to 133See MAPPING, below, for more information on how JSON values are mapped to
132Perl. 134Perl.
133 135
134=back 136=back
137
138
139=head1 A FEW NOTES ON UNICODE AND PERL
140
141Since this often leads to confusion, here are a few very clear words on
142how Unicode works in Perl, modulo bugs.
143
144=over 4
145
146=item 1. Perl strings can store characters with ordinal values > 255.
147
148This enables you to store unicode characters as single characters in a
149Perl string - very natural.
150
151=item 2. Perl does I<not> associate an encoding with your strings.
152
153Unless you force it to, e.g. when matching it against a regex, or printing
154the scalar to a file, in which case Perl either interprets your string as
155locale-encoded text, octets/binary, or as Unicode, depending on various
156settings. In no case is an encoding stored together with your data, it is
157I<use> that decides encoding, not any magical metadata.
158
159=item 3. The internal utf-8 flag has no meaning with regards to the
160encoding of your string.
161
162Just ignore that flag unless you debug a Perl bug, a module written in
163XS or want to dive into the internals of perl. Otherwise it will only
164confuse you, as, despite the name, it says nothing about how your string
165is encoded. You can have unicode strings with that flag set, with that
166flag clear, and you can have binary data with that flag set and that flag
167clear. Other possibilities exist, too.
168
169If you didn't know about that flag, just the better, pretend it doesn't
170exist.
171
172=item 4. A "Unicode String" is simply a string where each character can be
173validly interpreted as a Unicode codepoint.
174
175If you have UTF-8 encoded data, it is no longer a Unicode string, but a
176Unicode string encoded in UTF-8, giving you a binary string.
177
178=item 5. A string containing "high" (> 255) character values is I<not> a UTF-8 string.
179
180Its a fact. Learn to live with it.
181
182=back
183
184I hope this helps :)
135 185
136 186
137=head1 OBJECT-ORIENTED INTERFACE 187=head1 OBJECT-ORIENTED INTERFACE
138 188
139The object oriented interface lets you configure your own encoding or 189The object oriented interface lets you configure your own encoding or
… …
666 to_json [\0,JSON::XS::true] # yields [false,true] 716 to_json [\0,JSON::XS::true] # yields [false,true]
667 717
668=item JSON::XS::true, JSON::XS::false 718=item JSON::XS::true, JSON::XS::false
669 719
670These special values become JSON true and JSON false values, 720These special values become JSON true and JSON false values,
671respectively. You cna alos use C<\1> and C<\0> directly if you want. 721respectively. You can also use C<\1> and C<\0> directly if you want.
672 722
673=item blessed objects 723=item blessed objects
674 724
675Blessed objects are not allowed. JSON::XS currently tries to encode their 725Blessed objects are not allowed. JSON::XS currently tries to encode their
676underlying representation (hash- or arrayref), but this behaviour might 726underlying representation (hash- or arrayref), but this behaviour might
… …
926design bugs, but it is still you who will have to deal with it, as major 976design bugs, but it is still you who will have to deal with it, as major
927browser developers care only for features, not about doing security 977browser developers care only for features, not about doing security
928right). 978right).
929 979
930 980
981=head1 THREADS
982
983This module is I<not> guarenteed to be thread safe and there are no
984plans to change this until Perl gets thread support (as opposed to the
985horribly slow so-called "threads" which are simply slow and bloated
986process simulations - use fork, its I<much> faster, cheaper, better).
987
988(It might actually work, but you ahve ben warned).
989
990
931=head1 BUGS 991=head1 BUGS
932 992
933While the goal of this module is to be correct, that unfortunately does 993While the goal of this module is to be correct, that unfortunately does
934not mean its bug-free, only that I think its design is bug-free. It is 994not mean its bug-free, only that I think its design is bug-free. It is
935still relatively early in its development. If you keep reporting bugs they 995still relatively early in its development. If you keep reporting bugs they
936will be fixed swiftly, though. 996will be fixed swiftly, though.
997
998Please refrain from using rt.cpan.org or any other bug reporting
999service. I put the contact address into my modules for a reason.
937 1000
938=cut 1001=cut
939 1002
940our $true = do { bless \(my $dummy = 1), "JSON::XS::Boolean" }; 1003our $true = do { bless \(my $dummy = 1), "JSON::XS::Boolean" };
941our $false = do { bless \(my $dummy = 0), "JSON::XS::Boolean" }; 1004our $false = do { bless \(my $dummy = 0), "JSON::XS::Boolean" };

Diff Legend

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