File | /usr/local/lib/perl5/site_perl/5.10.1/JSON.pm |
Statements Executed | 130 |
Statement Execution Time | 4.40ms |
Calls | P | F | Exclusive Time |
Inclusive Time |
Subroutine |
---|---|---|---|---|---|
1 | 1 | 1 | 1.10ms | 4.41ms | _load_xs | JSON::
1 | 1 | 2 | 666µs | 666µs | CORE:readline (opcode) | JSON::
2 | 2 | 1 | 238µs | 344µs | _overrride_overload | JSON::Boolean::
8 | 1 | 1 | 157µs | 327µs | to_json | JSON::
5 | 1 | 1 | 89µs | 182µs | from_json | JSON::
1 | 1 | 1 | 47µs | 47µs | _set_module | JSON::
2 | 2 | 2 | 30µs | 275µs | import | JSON::
1 | 1 | 2 | 19µs | 19µs | CORE:close (opcode) | JSON::
1 | 1 | 1 | 14µs | 35µs | BEGIN@284 | JSON::
1 | 1 | 1 | 13µs | 16µs | BEGIN@4 | JSON::
1 | 1 | 1 | 7µs | 62µs | BEGIN@6 | JSON::
1 | 1 | 1 | 7µs | 18µs | BEGIN@349 | JSON::Backend::PP::
1 | 1 | 1 | 4µs | 4µs | BEGIN@9 | JSON::
1 | 1 | 1 | 3µs | 3µs | BEGIN@5 | JSON::
0 | 0 | 0 | 0s | 0s | __ANON__[:352] | JSON::Backend::PP::
0 | 0 | 0 | 0s | 0s | __ANON__[:353] | JSON::Backend::PP::
0 | 0 | 0 | 0s | 0s | init | JSON::Backend::PP::
0 | 0 | 0 | 0s | 0s | __ANON__[:298] | JSON::
0 | 0 | 0 | 0s | 0s | _load_pp | JSON::
0 | 0 | 0 | 0s | 0s | backend | JSON::
0 | 0 | 0 | 0s | 0s | false | JSON::
0 | 0 | 0 | 0s | 0s | is_pp | JSON::
0 | 0 | 0 | 0s | 0s | is_xs | JSON::
0 | 0 | 0 | 0s | 0s | jsonToObj | JSON::
0 | 0 | 0 | 0s | 0s | null | JSON::
0 | 0 | 0 | 0s | 0s | objToJson | JSON::
0 | 0 | 0 | 0s | 0s | property | JSON::
0 | 0 | 0 | 0s | 0s | pureperl_only_methods | JSON::
0 | 0 | 0 | 0s | 0s | require_xs_version | JSON::
0 | 0 | 0 | 0s | 0s | true | JSON::
Line | State ments |
Time on line |
Calls | Time in subs |
Code |
---|---|---|---|---|---|
1 | package JSON; | ||||
2 | |||||
3 | |||||
4 | 3 | 26µs | 2 | 18µs | # spent 16µs (13+3) within JSON::BEGIN@4 which was called
# once (13µs+3µs) by SimpleDB::Class::SQL::BEGIN@18 at line 4 # spent 16µs making 1 call to JSON::BEGIN@4
# spent 3µs making 1 call to strict::import |
5 | 3 | 20µs | 1 | 3µs | # spent 3µs within JSON::BEGIN@5 which was called
# once (3µs+0s) by SimpleDB::Class::SQL::BEGIN@18 at line 5 # spent 3µs making 1 call to JSON::BEGIN@5 |
6 | 3 | 52µs | 2 | 116µs | # spent 62µs (7+54) within JSON::BEGIN@6 which was called
# once (7µs+54µs) by SimpleDB::Class::SQL::BEGIN@18 at line 6 # spent 62µs making 1 call to JSON::BEGIN@6
# spent 54µs making 1 call to base::import |
7 | 1 | 2µs | @JSON::EXPORT = qw(from_json to_json jsonToObj objToJson encode_json decode_json); | ||
8 | |||||
9 | # spent 4µs within JSON::BEGIN@9 which was called
# once (4µs+0s) by SimpleDB::Class::SQL::BEGIN@18 at line 12 | ||||
10 | 2 | 4µs | $JSON::VERSION = '2.16'; | ||
11 | $JSON::DEBUG = 0 unless (defined $JSON::DEBUG); | ||||
12 | 1 | 1.09ms | 1 | 4µs | } # spent 4µs making 1 call to JSON::BEGIN@9 |
13 | |||||
14 | 1 | 300ns | my $Module_XS = 'JSON::XS'; | ||
15 | 1 | 200ns | my $Module_PP = 'JSON::PP'; | ||
16 | 1 | 100ns | my $XS_Version = '2.26'; | ||
17 | |||||
18 | |||||
19 | # XS and PP common methods | ||||
20 | |||||
21 | 1 | 3µs | my @PublicMethods = qw/ | ||
22 | ascii latin1 utf8 pretty indent space_before space_after relaxed canonical allow_nonref | ||||
23 | allow_blessed convert_blessed filter_json_object filter_json_single_key_object | ||||
24 | shrink max_depth max_size encode decode decode_prefix allow_unknown | ||||
25 | /; | ||||
26 | |||||
27 | 1 | 2µs | my @Properties = qw/ | ||
28 | ascii latin1 utf8 indent space_before space_after relaxed canonical allow_nonref | ||||
29 | allow_blessed convert_blessed shrink max_depth max_size allow_unknown | ||||
30 | /; | ||||
31 | |||||
32 | 1 | 100ns | my @XSOnlyMethods = qw//; # Currently nothing | ||
33 | |||||
34 | 1 | 1µs | my @PPOnlyMethods = qw/ | ||
35 | indent_length sort_by | ||||
36 | allow_singlequote allow_bignum loose allow_barekey escape_slash as_nonblessed | ||||
37 | /; # JSON::PP specific | ||||
38 | |||||
39 | |||||
40 | # used in _load_xs and _load_pp ($INSTALL_ONLY is not used currently) | ||||
41 | 1 | 100ns | my $_INSTALL_DONT_DIE = 1; # When _load_xs fails to load XS, don't die. | ||
42 | 1 | 0s | my $_INSTALL_ONLY = 2; # Don't call _set_methods() | ||
43 | 1 | 0s | my $_ALLOW_UNSUPPORTED = 0; | ||
44 | 1 | 0s | my $_UNIV_CONV_BLESSED = 0; | ||
45 | |||||
46 | |||||
47 | # Check the environment variable to decide worker module. | ||||
48 | |||||
49 | 4 | 4µs | unless ($JSON::Backend) { | ||
50 | $JSON::DEBUG and Carp::carp("Check used worker module..."); | ||||
51 | |||||
52 | my $backend = exists $ENV{PERL_JSON_BACKEND} ? $ENV{PERL_JSON_BACKEND} : 1; | ||||
53 | |||||
54 | if ($backend eq '1' or $backend =~ /JSON::XS\s*,\s*JSON::PP/) { # spent 4.41ms making 1 call to JSON::_load_xs | ||||
55 | _load_xs($_INSTALL_DONT_DIE) or _load_pp(); | ||||
56 | } | ||||
57 | elsif ($backend eq '0' or $backend eq 'JSON::PP') { | ||||
58 | _load_pp(); | ||||
59 | } | ||||
60 | elsif ($backend eq '2' or $backend eq 'JSON::XS') { | ||||
61 | _load_xs(); | ||||
62 | } | ||||
63 | else { | ||||
64 | Carp::croak "The value of environmental variable 'PERL_JSON_BACKEND' is invalid."; | ||||
65 | } | ||||
66 | } | ||||
67 | |||||
68 | |||||
69 | # spent 275µs (30+245) within JSON::import which was called 2 times, avg 138µs/call:
# once (16µs+125µs) by SimpleDB::Class::SQL::BEGIN@18 at line 18 of ../lib/SimpleDB/Class/SQL.pm
# once (13µs+121µs) by SimpleDB::Class::Types::BEGIN@74 at line 74 of ../lib/SimpleDB/Class/Types.pm | ||||
70 | 12 | 21µs | my $pkg = shift; | ||
71 | my @what_to_export; | ||||
72 | my $no_export; | ||||
73 | |||||
74 | for my $tag (@_) { | ||||
75 | if ($tag eq '-support_by_pp') { | ||||
76 | if (!$_ALLOW_UNSUPPORTED++) { | ||||
77 | JSON::Backend::XS | ||||
78 | ->support_by_pp(@PPOnlyMethods) if ($JSON::Backend eq $Module_XS); | ||||
79 | } | ||||
80 | next; | ||||
81 | } | ||||
82 | elsif ($tag eq '-no_export') { | ||||
83 | $no_export++, next; | ||||
84 | } | ||||
85 | elsif ( $tag eq '-convert_blessed_universally' ) { | ||||
86 | eval q| | ||||
87 | require B; | ||||
88 | *UNIVERSAL::TO_JSON = sub { | ||||
89 | my $b_obj = B::svref_2object( $_[0] ); | ||||
90 | return $b_obj->isa('B::HV') ? { %{ $_[0] } } | ||||
91 | : $b_obj->isa('B::AV') ? [ @{ $_[0] } ] | ||||
92 | : undef | ||||
93 | ; | ||||
94 | } | ||||
95 | | if ( !$_UNIV_CONV_BLESSED++ ); | ||||
96 | next; | ||||
97 | } | ||||
98 | push @what_to_export, $tag; | ||||
99 | } | ||||
100 | |||||
101 | return if ($no_export); | ||||
102 | |||||
103 | __PACKAGE__->export_to_level(1, $pkg, @what_to_export); # spent 52µs making 2 calls to Exporter::export_to_level, avg 26µs/call | ||||
104 | } | ||||
105 | |||||
106 | |||||
107 | # OBSOLETED | ||||
108 | |||||
109 | sub jsonToObj { | ||||
110 | my $alternative = 'from_json'; | ||||
111 | if (defined $_[0] and UNIVERSAL::isa($_[0], 'JSON')) { | ||||
112 | shift @_; $alternative = 'decode'; | ||||
113 | } | ||||
114 | Carp::carp "'jsonToObj' will be obsoleted. Please use '$alternative' instead."; | ||||
115 | return JSON::from_json(@_); | ||||
116 | }; | ||||
117 | |||||
118 | sub objToJson { | ||||
119 | my $alternative = 'to_json'; | ||||
120 | if (defined $_[0] and UNIVERSAL::isa($_[0], 'JSON')) { | ||||
121 | shift @_; $alternative = 'encode'; | ||||
122 | } | ||||
123 | Carp::carp "'objToJson' will be obsoleted. Please use '$alternative' instead."; | ||||
124 | JSON::to_json(@_); | ||||
125 | }; | ||||
126 | |||||
127 | |||||
128 | # INTERFACES | ||||
129 | |||||
130 | # spent 327µs (157+170) within JSON::to_json which was called 8 times, avg 41µs/call:
# 8 times (157µs+170µs) by SimpleDB::Class::Types::__ANON__[../lib/SimpleDB/Class/Types.pm:165] at line 165 of ../lib/SimpleDB/Class/Types.pm, avg 41µs/call | ||||
131 | 24 | 324µs | 8 | 54µs | my $json = new JSON; # spent 54µs making 8 calls to JSON::XS::new, avg 7µs/call |
132 | |||||
133 | if (@_ == 2 and ref $_[1] eq 'HASH') { | ||||
134 | my $opt = $_[1]; | ||||
135 | for my $method (keys %$opt) { | ||||
136 | $json->$method( $opt->{$method} ); | ||||
137 | } | ||||
138 | } | ||||
139 | |||||
140 | $json->encode($_[0]); # spent 103µs making 8 calls to JSON::XS::encode, avg 13µs/call | ||||
141 | } | ||||
142 | |||||
143 | |||||
144 | # spent 182µs (89+93) within JSON::from_json which was called 5 times, avg 36µs/call:
# 5 times (89µs+93µs) by SimpleDB::Class::Types::__ANON__[../lib/SimpleDB/Class/Types.pm:221] at line 213 of ../lib/SimpleDB/Class/Types.pm, avg 36µs/call | ||||
145 | 15 | 182µs | 5 | 20µs | my $json = new JSON; # spent 20µs making 5 calls to JSON::XS::new, avg 4µs/call |
146 | |||||
147 | if (@_ == 2 and ref $_[1] eq 'HASH') { | ||||
148 | my $opt = $_[1]; | ||||
149 | for my $method (keys %$opt) { | ||||
150 | $json->$method( $opt->{$method} ); | ||||
151 | } | ||||
152 | } | ||||
153 | |||||
154 | return $json->decode( $_[0] ); # spent 66µs making 5 calls to JSON::XS::decode, avg 13µs/call | ||||
155 | } | ||||
156 | |||||
157 | |||||
158 | sub true { $JSON::true } | ||||
159 | |||||
160 | sub false { $JSON::false } | ||||
161 | |||||
162 | sub null { undef; } | ||||
163 | |||||
164 | |||||
165 | sub require_xs_version { $XS_Version; } | ||||
166 | |||||
167 | sub backend { | ||||
168 | my $proto = shift; | ||||
169 | $JSON::Backend; | ||||
170 | } | ||||
171 | |||||
172 | #*module = *backend; | ||||
173 | |||||
174 | |||||
175 | sub is_xs { | ||||
176 | return $_[0]->module eq $Module_XS; | ||||
177 | } | ||||
178 | |||||
179 | |||||
180 | sub is_pp { | ||||
181 | return $_[0]->module eq $Module_PP; | ||||
182 | } | ||||
183 | |||||
184 | |||||
185 | sub pureperl_only_methods { @PPOnlyMethods; } | ||||
186 | |||||
187 | |||||
188 | sub property { | ||||
189 | my ($self, $name, $value) = @_; | ||||
190 | |||||
191 | if (@_ == 1) { | ||||
192 | my %props; | ||||
193 | for $name (@Properties) { | ||||
194 | my $method = 'get_' . $name; | ||||
195 | if ($name eq 'max_size') { | ||||
196 | my $value = $self->$method(); | ||||
197 | $props{$name} = $value == 1 ? 0 : $value; | ||||
198 | next; | ||||
199 | } | ||||
200 | $props{$name} = $self->$method(); | ||||
201 | } | ||||
202 | return \%props; | ||||
203 | } | ||||
204 | elsif (@_ > 3) { | ||||
205 | Carp::croak('property() can take only the option within 2 arguments.'); | ||||
206 | } | ||||
207 | elsif (@_ == 2) { | ||||
208 | if ( my $method = $self->can('get_' . $name) ) { | ||||
209 | if ($name eq 'max_size') { | ||||
210 | my $value = $self->$method(); | ||||
211 | return $value == 1 ? 0 : $value; | ||||
212 | } | ||||
213 | $self->$method(); | ||||
214 | } | ||||
215 | } | ||||
216 | else { | ||||
217 | $self->$name($value); | ||||
218 | } | ||||
219 | |||||
220 | } | ||||
221 | |||||
222 | |||||
223 | |||||
224 | # INTERNAL | ||||
225 | |||||
226 | # spent 4.41ms (1.10+3.31) within JSON::_load_xs which was called
# once (1.10ms+3.31ms) by SimpleDB::Class::SQL::BEGIN@18 at line 54 | ||||
227 | 8 | 32µs | my $opt = shift; | ||
228 | |||||
229 | $JSON::DEBUG and Carp::carp "Load $Module_XS."; | ||||
230 | |||||
231 | # if called after install module, overload is disable.... why? | ||||
232 | JSON::Boolean::_overrride_overload($Module_XS); # spent 193µs making 1 call to JSON::Boolean::_overrride_overload | ||||
233 | JSON::Boolean::_overrride_overload($Module_PP); # spent 151µs making 1 call to JSON::Boolean::_overrride_overload | ||||
234 | |||||
235 | 1 | 142µs | 2 | 2.04ms | eval qq| # spent 2.02ms making 1 call to JSON::BEGIN@2
# spent 18µs making 1 call to UNIVERSAL::VERSION |
236 | use $Module_XS $XS_Version (); | ||||
237 | |; | ||||
238 | |||||
239 | if ($@) { | ||||
240 | if (defined $opt and $opt & $_INSTALL_DONT_DIE) { | ||||
241 | $JSON::DEBUG and Carp::carp "Can't load $Module_XS...($@)"; | ||||
242 | return 0; | ||||
243 | } | ||||
244 | Carp::croak $@; | ||||
245 | } | ||||
246 | |||||
247 | 5 | 1.05ms | unless (defined $opt and $opt & $_INSTALL_ONLY) { | ||
248 | _set_module( $JSON::Backend = $Module_XS ); # spent 47µs making 1 call to JSON::_set_module | ||||
249 | my $data = join("", <DATA>); # this code is from Jcode 2.xx. # spent 666µs making 1 call to JSON::CORE:readline | ||||
250 | close(DATA); # spent 19µs making 1 call to JSON::CORE:close | ||||
251 | 1 | 743µs | 12 | 348µs | eval $data; # spent 112µs making 3 calls to constant::import, avg 37µs/call
# spent 64µs making 1 call to JSON::Backend::XS::BEGIN@9
# spent 46µs making 1 call to JSON::Backend::XS::BEGIN@11
# spent 35µs making 1 call to JSON::Backend::XS::BEGIN@18
# spent 35µs making 3 calls to strict::unimport, avg 12µs/call
# spent 23µs making 1 call to JSON::Backend::XS::BEGIN@29
# spent 18µs making 1 call to JSON::Backend::XS::Supportable::BEGIN@90
# spent 16µs making 1 call to JSON::Backend::XS::BEGIN@42 |
252 | JSON::Backend::XS->init; # spent 15µs making 1 call to JSON::Backend::XS::init | ||||
253 | } | ||||
254 | |||||
255 | return 1; | ||||
256 | }; | ||||
257 | |||||
258 | |||||
259 | sub _load_pp { | ||||
260 | my $opt = shift; | ||||
261 | |||||
262 | $JSON::DEBUG and Carp::carp "Load $Module_PP."; | ||||
263 | |||||
264 | # if called after install module, overload is disable.... why? | ||||
265 | JSON::Boolean::_overrride_overload($Module_XS); | ||||
266 | JSON::Boolean::_overrride_overload($Module_PP); | ||||
267 | |||||
268 | eval qq| require $Module_PP |; | ||||
269 | if ($@) { | ||||
270 | Carp::croak $@; | ||||
271 | } | ||||
272 | |||||
273 | unless (defined $opt and $opt & $_INSTALL_ONLY) { | ||||
274 | _set_module( $JSON::Backend = $Module_PP ); | ||||
275 | JSON::Backend::PP->init; | ||||
276 | } | ||||
277 | }; | ||||
278 | |||||
279 | |||||
280 | # spent 47µs within JSON::_set_module which was called
# once (47µs+0s) by JSON::_load_xs at line 248 | ||||
281 | 9 | 25µs | my $module = shift; | ||
282 | |||||
283 | local $^W; | ||||
284 | 3 | 232µs | 2 | 55µs | # spent 35µs (14+20) within JSON::BEGIN@284 which was called
# once (14µs+20µs) by SimpleDB::Class::SQL::BEGIN@18 at line 284 # spent 35µs making 1 call to JSON::BEGIN@284
# spent 20µs making 1 call to strict::unimport |
285 | |||||
286 | $JSON::true = ${"$module\::true"}; | ||||
287 | $JSON::false = ${"$module\::false"}; | ||||
288 | |||||
289 | push @JSON::ISA, $module; | ||||
290 | push @{"$module\::Boolean::ISA"}, qw(JSON::Boolean); | ||||
291 | |||||
292 | *{"JSON::is_bool"} = \&{"$module\::is_bool"}; | ||||
293 | |||||
294 | for my $method ($module eq $Module_XS ? @PPOnlyMethods : @XSOnlyMethods) { | ||||
295 | *{"JSON::$method"} = sub { | ||||
296 | Carp::carp("$method is not supported in $module."); | ||||
297 | $_[0]; | ||||
298 | 8 | 22µs | }; | ||
299 | } | ||||
300 | |||||
301 | return 1; | ||||
302 | } | ||||
303 | |||||
304 | |||||
305 | |||||
306 | # | ||||
307 | # JSON Boolean | ||||
308 | # | ||||
309 | |||||
310 | package JSON::Boolean; | ||||
311 | |||||
312 | 1 | 200ns | my %Installed; | ||
313 | |||||
314 | sub _overrride_overload { | ||||
315 | 10 | 233µs | return if ($Installed{ $_[0] }++); | ||
316 | |||||
317 | my $boolean = $_[0] . '::Boolean'; | ||||
318 | |||||
319 | 1 | 35µs | 4 | 178µs | eval sprintf(q| # spent 72µs making 2 calls to overload::import, avg 36µs/call
# spent 70µs making 1 call to JSON::XS::Boolean::BEGIN@3
# spent 37µs making 1 call to JSON::PP::Boolean::BEGIN@3 |
320 | package %s; | ||||
321 | use overload ( | ||||
322 | '""' => sub { ${$_[0]} == 1 ? 'true' : 'false' }, | ||||
323 | 'eq' => sub { | ||||
324 | my ($obj, $op) = ref ($_[0]) ? ($_[0], $_[1]) : ($_[1], $_[0]); | ||||
325 | if ($op eq 'true' or $op eq 'false') { | ||||
326 | return "$obj" eq 'true' ? 'true' eq $op : 'false' eq $op; | ||||
327 | } | ||||
328 | else { | ||||
329 | return $obj ? 1 == $op : 0 == $op; | ||||
330 | } | ||||
331 | }, | ||||
332 | ); | ||||
333 | |, $boolean); | ||||
334 | |||||
335 | if ($@) { Carp::croak $@; } | ||||
336 | |||||
337 | return 1; | ||||
338 | } | ||||
339 | |||||
340 | |||||
341 | # | ||||
342 | # Helper classes for Backend Module (PP) | ||||
343 | # | ||||
344 | |||||
345 | package JSON::Backend::PP; | ||||
346 | |||||
347 | sub init { | ||||
348 | local $^W; | ||||
349 | 3 | 101µs | 2 | 29µs | # spent 18µs (7+11) within JSON::Backend::PP::BEGIN@349 which was called
# once (7µs+11µs) by SimpleDB::Class::SQL::BEGIN@18 at line 349 # spent 18µs making 1 call to JSON::Backend::PP::BEGIN@349
# spent 11µs making 1 call to strict::unimport |
350 | *{"JSON::decode_json"} = \&{"JSON::PP::decode_json"}; | ||||
351 | *{"JSON::encode_json"} = \&{"JSON::PP::encode_json"}; | ||||
352 | *{"JSON::PP::is_xs"} = sub { 0 }; | ||||
353 | *{"JSON::PP::is_pp"} = sub { 1 }; | ||||
354 | return 1; | ||||
355 | } | ||||
356 | |||||
357 | # | ||||
358 | # To save memory, the below lines are read only when XS backend is used. | ||||
359 | # | ||||
360 | |||||
361 | package JSON; | ||||
362 | |||||
363 | 1 | 53µs | 1; | ||
364 | __DATA__ | ||||
365 | |||||
366 | |||||
367 | # | ||||
368 | # Helper classes for Backend Module (XS) | ||||
369 | # | ||||
370 | |||||
371 | package JSON::Backend::XS; | ||||
372 | |||||
373 | use constant INDENT_LENGTH_FLAG => 15 << 12; | ||||
374 | |||||
375 | use constant UNSUPPORTED_ENCODE_FLAG => { | ||||
376 | ESCAPE_SLASH => 0x00000010, | ||||
377 | ALLOW_BIGNUM => 0x00000020, | ||||
378 | AS_NONBLESSED => 0x00000040, | ||||
379 | EXPANDED => 0x10000000, # for developer's | ||||
380 | }; | ||||
381 | |||||
382 | use constant UNSUPPORTED_DECODE_FLAG => { | ||||
383 | LOOSE => 0x00000001, | ||||
384 | ALLOW_BIGNUM => 0x00000002, | ||||
385 | ALLOW_BAREKEY => 0x00000004, | ||||
386 | ALLOW_SINGLEQUOTE => 0x00000008, | ||||
387 | EXPANDED => 0x20000000, # for developer's | ||||
388 | }; | ||||
389 | |||||
390 | |||||
391 | sub init { | ||||
392 | local $^W; | ||||
393 | no strict qw(refs); | ||||
394 | *{"JSON::decode_json"} = \&{"JSON::XS::decode_json"}; | ||||
395 | *{"JSON::encode_json"} = \&{"JSON::XS::encode_json"}; | ||||
396 | *{"JSON::XS::is_xs"} = sub { 1 }; | ||||
397 | *{"JSON::XS::is_pp"} = sub { 0 }; | ||||
398 | return 1; | ||||
399 | } | ||||
400 | |||||
401 | |||||
402 | sub support_by_pp { | ||||
403 | my ($class, @methods) = @_; | ||||
404 | |||||
405 | local $^W; | ||||
406 | no strict qw(refs); | ||||
407 | |||||
408 | push @JSON::Backend::XS::Supportable::ISA, 'JSON'; | ||||
409 | |||||
410 | my $pkg = 'JSON::Backend::XS::Supportable'; | ||||
411 | |||||
412 | *{JSON::new} = sub { | ||||
413 | my $proto = new JSON::XS; $$proto = 0; | ||||
414 | bless $proto, $pkg; | ||||
415 | }; | ||||
416 | |||||
417 | for my $method (@methods) { | ||||
418 | my $flag = uc($method); | ||||
419 | my $type |= (UNSUPPORTED_ENCODE_FLAG->{$flag} || 0); | ||||
420 | $type |= (UNSUPPORTED_DECODE_FLAG->{$flag} || 0); | ||||
421 | |||||
422 | next unless($type); | ||||
423 | |||||
424 | $pkg->_make_unsupported_method($method => $type); | ||||
425 | } | ||||
426 | |||||
427 | push @{"JSON::XS::Boolean::ISA"}, qw(JSON::PP::Boolean); | ||||
428 | push @{"JSON::PP::Boolean::ISA"}, qw(JSON::Boolean); | ||||
429 | |||||
430 | $JSON::DEBUG and Carp::carp("set -support_by_pp mode."); | ||||
431 | |||||
432 | return 1; | ||||
433 | } | ||||
434 | |||||
435 | |||||
436 | |||||
437 | |||||
438 | # | ||||
439 | # Helper classes for XS | ||||
440 | # | ||||
441 | |||||
442 | package JSON::Backend::XS::Supportable; | ||||
443 | |||||
444 | |||||
445 | my $JSON_XS_encode_orignal = \&JSON::XS::encode; | ||||
446 | my $JSON_XS_decode_orignal = \&JSON::XS::decode; | ||||
447 | |||||
448 | $Carp::Internal{'JSON::Backend::XS::Supportable'} = 1; | ||||
449 | |||||
450 | sub _make_unsupported_method { | ||||
451 | my ($pkg, $method, $type) = @_; | ||||
452 | |||||
453 | local $^W; | ||||
454 | no strict qw(refs); | ||||
455 | |||||
456 | *{"$pkg\::$method"} = sub { | ||||
457 | local $^W; | ||||
458 | if (defined $_[1] ? $_[1] : 1) { | ||||
459 | ${$_[0]} |= $type; | ||||
460 | } | ||||
461 | else { | ||||
462 | ${$_[0]} &= ~$type; | ||||
463 | } | ||||
464 | |||||
465 | if (${$_[0]}) { | ||||
466 | *JSON::XS::encode = \&JSON::Backend::XS::Supportable::_encode; | ||||
467 | *JSON::XS::decode = \&JSON::Backend::XS::Supportable::_decode; | ||||
468 | } | ||||
469 | else { | ||||
470 | *JSON::XS::encode = $JSON_XS_encode_orignal; | ||||
471 | *JSON::XS::decode = $JSON_XS_decode_orignal; | ||||
472 | } | ||||
473 | |||||
474 | $_[0]; | ||||
475 | }; | ||||
476 | |||||
477 | *{"$pkg\::get_$method"} = sub { | ||||
478 | ${$_[0]} & $type ? 1 : ''; | ||||
479 | }; | ||||
480 | |||||
481 | } | ||||
482 | |||||
483 | |||||
484 | sub _set_for_pp { | ||||
485 | require JSON::PP; | ||||
486 | my $type = shift; | ||||
487 | my $pp = new JSON::PP; | ||||
488 | my $prop = $_[0]->property; | ||||
489 | |||||
490 | for my $name (keys %$prop) { | ||||
491 | $pp->$name( $prop->{$name} ? $prop->{$name} : 0 ); | ||||
492 | } | ||||
493 | |||||
494 | my $unsupported = $type eq 'encode' ? JSON::Backend::XS::UNSUPPORTED_ENCODE_FLAG | ||||
495 | : JSON::Backend::XS::UNSUPPORTED_DECODE_FLAG; | ||||
496 | my $flags = ${$_[0]} || 0; | ||||
497 | |||||
498 | for my $name (keys %$unsupported) { | ||||
499 | next if ($name eq 'EXPANDED'); # for developer's | ||||
500 | my $enable = ($flags & $unsupported->{$name}) ? 1 : 0; | ||||
501 | my $method = lc $name; | ||||
502 | $pp->$method($enable); | ||||
503 | } | ||||
504 | |||||
505 | $pp->indent_length( $_[0]->get_indent_length ); | ||||
506 | |||||
507 | return $pp; | ||||
508 | } | ||||
509 | |||||
510 | |||||
511 | sub _encode { # using with PP encod | ||||
512 | _set_for_pp('encode' => @_)->encode($_[1]); | ||||
513 | } | ||||
514 | |||||
515 | |||||
516 | sub _decode { # if unsupported-flag is set, use PP | ||||
517 | _set_for_pp('decode' => @_)->decode($_[1]); | ||||
518 | } | ||||
519 | |||||
520 | |||||
521 | sub decode_prefix { # if unsupported-flag is set, use PP | ||||
522 | _set_for_pp('decode' => @_)->decode_prefix($_[1]); | ||||
523 | } | ||||
524 | |||||
525 | |||||
526 | sub get_indent_length { | ||||
527 | ${$_[0]} << 4 >> 16; | ||||
528 | } | ||||
529 | |||||
530 | |||||
531 | sub indent_length { | ||||
532 | my $length = $_[1]; | ||||
533 | |||||
534 | if (!defined $length or $length > 15 or $length < 0) { | ||||
535 | Carp::carp "The acceptable range of indent_length() is 0 to 15."; | ||||
536 | } | ||||
537 | else { | ||||
538 | local $^W; | ||||
539 | $length <<= 12; | ||||
540 | ${$_[0]} &= ~ JSON::Backend::XS::INDENT_LENGTH_FLAG; | ||||
541 | ${$_[0]} |= $length; | ||||
542 | *JSON::XS::encode = \&JSON::Backend::XS::Supportable::_encode; | ||||
543 | } | ||||
544 | |||||
545 | $_[0]; | ||||
546 | } | ||||
547 | |||||
548 | |||||
549 | 1; | ||||
550 | __END__ | ||||
551 | |||||
552 | =head1 NAME | ||||
553 | |||||
554 | JSON - JSON (JavaScript Object Notation) encoder/decoder | ||||
555 | |||||
556 | =head1 SYNOPSIS | ||||
557 | |||||
558 | use JSON; # imports encode_json, decode_json, to_json and from_json. | ||||
559 | |||||
560 | $json_text = to_json($perl_scalar); | ||||
561 | $perl_scalar = from_json($json_text); | ||||
562 | |||||
563 | # option-acceptable | ||||
564 | $json_text = to_json($perl_scalar, {ascii => 1}); | ||||
565 | $perl_scalar = from_json($json_text, {utf8 => 1}); | ||||
566 | |||||
567 | # OOP | ||||
568 | $json = new JSON; | ||||
569 | |||||
570 | $json_text = $json->encode($perl_scalar); | ||||
571 | $perl_scalar = $json->decode($json_text); | ||||
572 | |||||
573 | # pretty-printing | ||||
574 | $json_text = $json->pretty->encode($perl_scalar); | ||||
575 | |||||
576 | # simple interface | ||||
577 | $utf8_encoded_json_text = encode_json $perl_hash_or_arrayref; | ||||
578 | $perl_hash_or_arrayref = decode_json $utf8_encoded_json_text; | ||||
579 | |||||
580 | |||||
581 | # If you want to use PP only support features, call with '-support_by_pp' | ||||
582 | # When XS unsupported feature is enable, using PP de/encode. | ||||
583 | |||||
584 | use JSON -support_by_pp; | ||||
585 | |||||
586 | |||||
587 | =head1 VERSION | ||||
588 | |||||
589 | 2.16 | ||||
590 | |||||
591 | This version is compatible with JSON::XS B<2.26> and later. | ||||
592 | |||||
593 | |||||
594 | =head1 DESCRIPTION | ||||
595 | |||||
596 | ************************** CAUTION ******************************** | ||||
597 | * This is 'JSON module version 2' and there are many differences * | ||||
598 | * to version 1.xx * | ||||
599 | * Please check your applications useing old version. * | ||||
600 | * See to 'INCOMPATIBLE CHANGES TO OLD VERSION' * | ||||
601 | ******************************************************************* | ||||
602 | |||||
603 | JSON (JavaScript Object Notation) is a simple data format. | ||||
604 | See to L<http://www.json.org/> and C<RFC4627>(L<http://www.ietf.org/rfc/rfc4627.txt>). | ||||
605 | |||||
606 | This module converts Perl data structures to JSON and vice versa using either | ||||
607 | L<JSON::XS> or L<JSON::PP>. | ||||
608 | |||||
609 | JSON::XS is the fastest and most proper JSON module on CPAN which must be | ||||
610 | compiled and installed in your environment. | ||||
611 | JSON::PP is a pure-Perl module which is bundled in this distribution and | ||||
612 | has a strong compatibility to JSON::XS. | ||||
613 | |||||
614 | This module try to use JSON::XS by default and fail to it, use JSON::PP instead. | ||||
615 | So its features completely depend on JSON::XS or JSON::PP. | ||||
616 | |||||
617 | See to L<BACKEND MODULE DECISION>. | ||||
618 | |||||
619 | To distinguish the module name 'JSON' and the format type JSON, | ||||
620 | the former is quoted by CE<lt>E<gt> (its results vary with your using media), | ||||
621 | and the latter is left just as it is. | ||||
622 | |||||
623 | Module name : C<JSON> | ||||
624 | |||||
625 | Format type : JSON | ||||
626 | |||||
627 | =head2 FEATURES | ||||
628 | |||||
629 | =over | ||||
630 | |||||
631 | =item * correct unicode handling | ||||
632 | |||||
633 | This module (i.e. backend modules) knows how to handle Unicode, documents | ||||
634 | how and when it does so, and even documents what "correct" means. | ||||
635 | |||||
636 | Even though there are limitations, this feature is available since Perl version 5.6. | ||||
637 | |||||
638 | JSON::XS requires Perl 5.8.2 (but works correctly in 5.8.8 or later), so in older versions | ||||
639 | C<JSON> sholud call JSON::PP as the backend which can be used since Perl 5.005. | ||||
640 | |||||
641 | With Perl 5.8.x JSON::PP works, but from 5.8.0 to 5.8.2, because of a Perl side problem, | ||||
642 | JSON::PP works slower in the versions. And in 5.005, the Unicode handling is not available. | ||||
643 | See to L<JSON::PP/UNICODE HANDLING ON PERLS> for more information. | ||||
644 | |||||
645 | See also to L<JSON::XS/A FEW NOTES ON UNICODE AND PERL> | ||||
646 | and L<JSON::XS/ENCODING/CODESET_FLAG_NOTES>. | ||||
647 | |||||
648 | |||||
649 | =item * round-trip integrity | ||||
650 | |||||
651 | When you serialise a perl data structure using only data types supported by JSON, | ||||
652 | the deserialised data structure is identical on the Perl level. | ||||
653 | (e.g. the string "2.0" doesn't suddenly become "2" just because it looks | ||||
654 | like a number). There minor I<are> exceptions to this, read the MAPPING | ||||
655 | section below to learn about those. | ||||
656 | |||||
657 | =item * strict checking of JSON correctness | ||||
658 | |||||
659 | There is no guessing, no generating of illegal JSON texts by default, | ||||
660 | and only JSON is accepted as input by default (the latter is a security | ||||
661 | feature). | ||||
662 | |||||
663 | See to L<JSON::XS/FEATURES> and L<JSON::PP/FEATURES>. | ||||
664 | |||||
665 | =item * fast | ||||
666 | |||||
667 | This module returns a JSON::XS object itself if avaliable. | ||||
668 | Compared to other JSON modules and other serialisers such as Storable, | ||||
669 | JSON::XS usually compares favourably in terms of speed, too. | ||||
670 | |||||
671 | If not avaliable, C<JSON> returns a JSON::PP object instead of JSON::XS and | ||||
672 | it is very slow as pure-Perl. | ||||
673 | |||||
674 | =item * simple to use | ||||
675 | |||||
676 | This module has both a simple functional interface as well as an | ||||
677 | object oriented interface interface. | ||||
678 | |||||
679 | =item * reasonably versatile output formats | ||||
680 | |||||
681 | You can choose between the most compact guaranteed-single-line format possible | ||||
682 | (nice for simple line-based protocols), a pure-ASCII format (for when your transport | ||||
683 | is not 8-bit clean, still supports the whole Unicode range), or a pretty-printed | ||||
684 | format (for when you want to read that stuff). Or you can combine those features | ||||
685 | in whatever way you like. | ||||
686 | |||||
687 | =back | ||||
688 | |||||
689 | =head1 FUNCTIONAL INTERFACE | ||||
690 | |||||
691 | Some documents are copied and modified from L<JSON::XS/FUNCTIONAL INTERFACE>. | ||||
692 | C<to_json> and C<from_json> are additional functions. | ||||
693 | |||||
694 | =head2 to_json | ||||
695 | |||||
696 | $json_text = to_json($perl_scalar) | ||||
697 | |||||
698 | Converts the given Perl data structure to a json string. | ||||
699 | |||||
700 | This function call is functionally identical to: | ||||
701 | |||||
702 | $json_text = JSON->new->encode($perl_scalar) | ||||
703 | |||||
704 | Takes a hash reference as the second. | ||||
705 | |||||
706 | $json_text = to_json($perl_scalar, $flag_hashref) | ||||
707 | |||||
708 | So, | ||||
709 | |||||
710 | $json_text = encode_json($perl_scalar, {utf8 => 1, pretty => 1}) | ||||
711 | |||||
712 | equivalent to: | ||||
713 | |||||
714 | $json_text = JSON->new->utf8(1)->pretty(1)->encode($perl_scalar) | ||||
715 | |||||
716 | |||||
717 | =head2 from_json | ||||
718 | |||||
719 | $perl_scalar = from_json($json_text) | ||||
720 | |||||
721 | The opposite of C<to_json>: expects a json string and tries | ||||
722 | to parse it, returning the resulting reference. | ||||
723 | |||||
724 | This function call is functionally identical to: | ||||
725 | |||||
726 | $perl_scalar = JSON->decode($json_text) | ||||
727 | |||||
728 | Takes a hash reference as the second. | ||||
729 | |||||
730 | $perl_scalar = from_json($json_text, $flag_hashref) | ||||
731 | |||||
732 | So, | ||||
733 | |||||
734 | $perl_scalar = from_json($json_text, {utf8 => 1}) | ||||
735 | |||||
736 | equivalent to: | ||||
737 | |||||
738 | $perl_scalar = JSON->new->utf8(1)->decode($json_text) | ||||
739 | |||||
740 | =head2 encode_json | ||||
741 | |||||
742 | $json_text = encode_json $perl_scalar | ||||
743 | |||||
744 | Converts the given Perl data structure to a UTF-8 encoded, binary string. | ||||
745 | |||||
746 | This function call is functionally identical to: | ||||
747 | |||||
748 | $json_text = JSON->new->utf8->encode($perl_scalar) | ||||
749 | |||||
750 | =head2 decode_json | ||||
751 | |||||
752 | $perl_scalar = decode_json $json_text | ||||
753 | |||||
754 | The opposite of C<encode_json>: expects an UTF-8 (binary) string and tries | ||||
755 | to parse that as an UTF-8 encoded JSON text, returning the resulting | ||||
756 | reference. | ||||
757 | |||||
758 | This function call is functionally identical to: | ||||
759 | |||||
760 | $perl_scalar = JSON->new->utf8->decode($json_text) | ||||
761 | |||||
762 | =head2 JSON::is_bool | ||||
763 | |||||
764 | $is_boolean = JSON::is_bool($scalar) | ||||
765 | |||||
766 | Returns true if the passed scalar represents either JSON::true or | ||||
767 | JSON::false, two constants that act like C<1> and C<0> respectively | ||||
768 | and are also used to represent JSON C<true> and C<false> in Perl strings. | ||||
769 | |||||
770 | =head2 JSON::true | ||||
771 | |||||
772 | Returns JSON true value which is blessed object. | ||||
773 | It C<isa> JSON::Boolean object. | ||||
774 | |||||
775 | =head2 JSON::false | ||||
776 | |||||
777 | Returns JSON false value which is blessed object. | ||||
778 | It C<isa> JSON::Boolean object. | ||||
779 | |||||
780 | =head2 JSON::null | ||||
781 | |||||
782 | Returns C<undef>. | ||||
783 | |||||
784 | See L<MAPPING>, below, for more information on how JSON values are mapped to | ||||
785 | Perl. | ||||
786 | |||||
787 | =head1 COMMON OBJECT-ORIENTED INTERFACE | ||||
788 | |||||
789 | |||||
790 | =head2 new | ||||
791 | |||||
792 | $json = new JSON | ||||
793 | |||||
794 | Returns a new C<JSON> object inherited from either JSON::XS or JSON::PP | ||||
795 | that can be used to de/encode JSON strings. | ||||
796 | |||||
797 | All boolean flags described below are by default I<disabled>. | ||||
798 | |||||
799 | The mutators for flags all return the JSON object again and thus calls can | ||||
800 | be chained: | ||||
801 | |||||
802 | my $json = JSON->new->utf8->space_after->encode({a => [1,2]}) | ||||
803 | => {"a": [1, 2]} | ||||
804 | |||||
805 | =head2 ascii | ||||
806 | |||||
807 | $json = $json->ascii([$enable]) | ||||
808 | |||||
809 | $enabled = $json->get_ascii | ||||
810 | |||||
811 | If $enable is true (or missing), then the encode method will not generate characters outside | ||||
812 | the code range 0..127. Any Unicode characters outside that range will be escaped using either | ||||
813 | a single \uXXXX or a double \uHHHH\uLLLLL escape sequence, as per RFC4627. | ||||
814 | |||||
815 | If $enable is false, then the encode method will not escape Unicode characters unless | ||||
816 | required by the JSON syntax or other flags. This results in a faster and more compact format. | ||||
817 | |||||
818 | This feature depends on the used Perl version and environment. | ||||
819 | |||||
820 | See to L<JSON::PP/UNICODE HANDLING ON PERLS> if the backend is PP. | ||||
821 | |||||
822 | JSON->new->ascii(1)->encode([chr 0x10401]) | ||||
823 | => ["\ud801\udc01"] | ||||
824 | |||||
825 | =head2 latin1 | ||||
826 | |||||
827 | $json = $json->latin1([$enable]) | ||||
828 | |||||
829 | $enabled = $json->get_latin1 | ||||
830 | |||||
831 | If $enable is true (or missing), then the encode method will encode the resulting JSON | ||||
832 | text as latin1 (or iso-8859-1), escaping any characters outside the code range 0..255. | ||||
833 | |||||
834 | If $enable is false, then the encode method will not escape Unicode characters | ||||
835 | unless required by the JSON syntax or other flags. | ||||
836 | |||||
837 | JSON->new->latin1->encode (["\x{89}\x{abc}"] | ||||
838 | => ["\x{89}\\u0abc"] # (perl syntax, U+abc escaped, U+89 not) | ||||
839 | |||||
840 | =head2 utf8 | ||||
841 | |||||
842 | $json = $json->utf8([$enable]) | ||||
843 | |||||
844 | $enabled = $json->get_utf8 | ||||
845 | |||||
846 | If $enable is true (or missing), then the encode method will encode the JSON result | ||||
847 | into UTF-8, as required by many protocols, while the decode method expects to be handled | ||||
848 | an UTF-8-encoded string. Please note that UTF-8-encoded strings do not contain any | ||||
849 | characters outside the range 0..255, they are thus useful for bytewise/binary I/O. | ||||
850 | |||||
851 | In future versions, enabling this option might enable autodetection of the UTF-16 and UTF-32 | ||||
852 | encoding families, as described in RFC4627. | ||||
853 | |||||
854 | If $enable is false, then the encode method will return the JSON string as a (non-encoded) | ||||
855 | Unicode string, while decode expects thus a Unicode string. Any decoding or encoding | ||||
856 | (e.g. to UTF-8 or UTF-16) needs to be done yourself, e.g. using the Encode module. | ||||
857 | |||||
858 | |||||
859 | Example, output UTF-16BE-encoded JSON: | ||||
860 | |||||
861 | use Encode; | ||||
862 | $jsontext = encode "UTF-16BE", JSON::XS->new->encode ($object); | ||||
863 | |||||
864 | Example, decode UTF-32LE-encoded JSON: | ||||
865 | |||||
866 | use Encode; | ||||
867 | $object = JSON::XS->new->decode (decode "UTF-32LE", $jsontext); | ||||
868 | |||||
869 | See to L<JSON::PP/UNICODE HANDLING ON PERLS> if the backend is PP. | ||||
870 | |||||
871 | |||||
872 | =head2 pretty | ||||
873 | |||||
874 | $json = $json->pretty([$enable]) | ||||
875 | |||||
876 | This enables (or disables) all of the C<indent>, C<space_before> and | ||||
877 | C<space_after> (and in the future possibly more) flags in one call to | ||||
878 | generate the most readable (or most compact) form possible. | ||||
879 | |||||
880 | Equivalent to: | ||||
881 | |||||
882 | $json->indent->space_before->space_after | ||||
883 | |||||
884 | The indent space length is three and JSON::XS cannot change the indent | ||||
885 | space length. | ||||
886 | |||||
887 | =head2 indent | ||||
888 | |||||
889 | $json = $json->indent([$enable]) | ||||
890 | |||||
891 | $enabled = $json->get_indent | ||||
892 | |||||
893 | If C<$enable> is true (or missing), then the C<encode> method will use a multiline | ||||
894 | format as output, putting every array member or object/hash key-value pair | ||||
895 | into its own line, identing them properly. | ||||
896 | |||||
897 | If C<$enable> is false, no newlines or indenting will be produced, and the | ||||
898 | resulting JSON text is guarenteed not to contain any C<newlines>. | ||||
899 | |||||
900 | This setting has no effect when decoding JSON texts. | ||||
901 | |||||
902 | The indent space length is three. | ||||
903 | With JSON::PP, you can also access C<indent_length> to change indent space length. | ||||
904 | |||||
905 | |||||
906 | =head2 space_before | ||||
907 | |||||
908 | $json = $json->space_before([$enable]) | ||||
909 | |||||
910 | $enabled = $json->get_space_before | ||||
911 | |||||
912 | If C<$enable> is true (or missing), then the C<encode> method will add an extra | ||||
913 | optional space before the C<:> separating keys from values in JSON objects. | ||||
914 | |||||
915 | If C<$enable> is false, then the C<encode> method will not add any extra | ||||
916 | space at those places. | ||||
917 | |||||
918 | This setting has no effect when decoding JSON texts. | ||||
919 | |||||
920 | Example, space_before enabled, space_after and indent disabled: | ||||
921 | |||||
922 | {"key" :"value"} | ||||
923 | |||||
924 | |||||
925 | =head2 space_after | ||||
926 | |||||
927 | $json = $json->space_after([$enable]) | ||||
928 | |||||
929 | $enabled = $json->get_space_after | ||||
930 | |||||
931 | If C<$enable> is true (or missing), then the C<encode> method will add an extra | ||||
932 | optional space after the C<:> separating keys from values in JSON objects | ||||
933 | and extra whitespace after the C<,> separating key-value pairs and array | ||||
934 | members. | ||||
935 | |||||
936 | If C<$enable> is false, then the C<encode> method will not add any extra | ||||
937 | space at those places. | ||||
938 | |||||
939 | This setting has no effect when decoding JSON texts. | ||||
940 | |||||
941 | Example, space_before and indent disabled, space_after enabled: | ||||
942 | |||||
943 | {"key": "value"} | ||||
944 | |||||
945 | |||||
946 | =head2 relaxed | ||||
947 | |||||
948 | $json = $json->relaxed([$enable]) | ||||
949 | |||||
950 | $enabled = $json->get_relaxed | ||||
951 | |||||
952 | If C<$enable> is true (or missing), then C<decode> will accept some | ||||
953 | extensions to normal JSON syntax (see below). C<encode> will not be | ||||
954 | affected in anyway. I<Be aware that this option makes you accept invalid | ||||
955 | JSON texts as if they were valid!>. I suggest only to use this option to | ||||
956 | parse application-specific files written by humans (configuration files, | ||||
957 | resource files etc.) | ||||
958 | |||||
959 | If C<$enable> is false (the default), then C<decode> will only accept | ||||
960 | valid JSON texts. | ||||
961 | |||||
962 | Currently accepted extensions are: | ||||
963 | |||||
964 | =over 4 | ||||
965 | |||||
966 | =item * list items can have an end-comma | ||||
967 | |||||
968 | JSON I<separates> array elements and key-value pairs with commas. This | ||||
969 | can be annoying if you write JSON texts manually and want to be able to | ||||
970 | quickly append elements, so this extension accepts comma at the end of | ||||
971 | such items not just between them: | ||||
972 | |||||
973 | [ | ||||
974 | 1, | ||||
975 | 2, <- this comma not normally allowed | ||||
976 | ] | ||||
977 | { | ||||
978 | "k1": "v1", | ||||
979 | "k2": "v2", <- this comma not normally allowed | ||||
980 | } | ||||
981 | |||||
982 | =item * shell-style '#'-comments | ||||
983 | |||||
984 | Whenever JSON allows whitespace, shell-style comments are additionally | ||||
985 | allowed. They are terminated by the first carriage-return or line-feed | ||||
986 | character, after which more white-space and comments are allowed. | ||||
987 | |||||
988 | [ | ||||
989 | 1, # this comment not allowed in JSON | ||||
990 | # neither this one... | ||||
991 | ] | ||||
992 | |||||
993 | =back | ||||
994 | |||||
995 | |||||
996 | =head2 canonical | ||||
997 | |||||
998 | $json = $json->canonical([$enable]) | ||||
999 | |||||
1000 | $enabled = $json->get_canonical | ||||
1001 | |||||
1002 | If C<$enable> is true (or missing), then the C<encode> method will output JSON objects | ||||
1003 | by sorting their keys. This is adding a comparatively high overhead. | ||||
1004 | |||||
1005 | If C<$enable> is false, then the C<encode> method will output key-value | ||||
1006 | pairs in the order Perl stores them (which will likely change between runs | ||||
1007 | of the same script). | ||||
1008 | |||||
1009 | This option is useful if you want the same data structure to be encoded as | ||||
1010 | the same JSON text (given the same overall settings). If it is disabled, | ||||
1011 | the same hash might be encoded differently even if contains the same data, | ||||
1012 | as key-value pairs have no inherent ordering in Perl. | ||||
1013 | |||||
1014 | This setting has no effect when decoding JSON texts. | ||||
1015 | |||||
1016 | =head2 allow_nonref | ||||
1017 | |||||
1018 | $json = $json->allow_nonref([$enable]) | ||||
1019 | |||||
1020 | $enabled = $json->get_allow_nonref | ||||
1021 | |||||
1022 | If C<$enable> is true (or missing), then the C<encode> method can convert a | ||||
1023 | non-reference into its corresponding string, number or null JSON value, | ||||
1024 | which is an extension to RFC4627. Likewise, C<decode> will accept those JSON | ||||
1025 | values instead of croaking. | ||||
1026 | |||||
1027 | If C<$enable> is false, then the C<encode> method will croak if it isn't | ||||
1028 | passed an arrayref or hashref, as JSON texts must either be an object | ||||
1029 | or array. Likewise, C<decode> will croak if given something that is not a | ||||
1030 | JSON object or array. | ||||
1031 | |||||
1032 | JSON->new->allow_nonref->encode ("Hello, World!") | ||||
1033 | => "Hello, World!" | ||||
1034 | |||||
1035 | =head2 allow_unknown | ||||
1036 | |||||
1037 | $json = $json->allow_unknown ([$enable]) | ||||
1038 | |||||
1039 | $enabled = $json->get_allow_unknown | ||||
1040 | |||||
1041 | If $enable is true (or missing), then "encode" will *not* throw an | ||||
1042 | exception when it encounters values it cannot represent in JSON (for | ||||
1043 | example, filehandles) but instead will encode a JSON "null" value. | ||||
1044 | Note that blessed objects are not included here and are handled | ||||
1045 | separately by c<allow_nonref>. | ||||
1046 | |||||
1047 | If $enable is false (the default), then "encode" will throw an | ||||
1048 | exception when it encounters anything it cannot encode as JSON. | ||||
1049 | |||||
1050 | This option does not affect "decode" in any way, and it is | ||||
1051 | recommended to leave it off unless you know your communications | ||||
1052 | partner. | ||||
1053 | |||||
1054 | =head2 allow_blessed | ||||
1055 | |||||
1056 | $json = $json->allow_blessed([$enable]) | ||||
1057 | |||||
1058 | $enabled = $json->get_allow_blessed | ||||
1059 | |||||
1060 | If C<$enable> is true (or missing), then the C<encode> method will not | ||||
1061 | barf when it encounters a blessed reference. Instead, the value of the | ||||
1062 | B<convert_blessed> option will decide whether C<null> (C<convert_blessed> | ||||
1063 | disabled or no C<TO_JSON> method found) or a representation of the | ||||
1064 | object (C<convert_blessed> enabled and C<TO_JSON> method found) is being | ||||
1065 | encoded. Has no effect on C<decode>. | ||||
1066 | |||||
1067 | If C<$enable> is false (the default), then C<encode> will throw an | ||||
1068 | exception when it encounters a blessed object. | ||||
1069 | |||||
1070 | |||||
1071 | =head2 convert_blessed | ||||
1072 | |||||
1073 | $json = $json->convert_blessed([$enable]) | ||||
1074 | |||||
1075 | $enabled = $json->get_convert_blessed | ||||
1076 | |||||
1077 | If C<$enable> is true (or missing), then C<encode>, upon encountering a | ||||
1078 | blessed object, will check for the availability of the C<TO_JSON> method | ||||
1079 | on the object's class. If found, it will be called in scalar context | ||||
1080 | and the resulting scalar will be encoded instead of the object. If no | ||||
1081 | C<TO_JSON> method is found, the value of C<allow_blessed> will decide what | ||||
1082 | to do. | ||||
1083 | |||||
1084 | The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON> | ||||
1085 | returns other blessed objects, those will be handled in the same | ||||
1086 | way. C<TO_JSON> must take care of not causing an endless recursion cycle | ||||
1087 | (== crash) in this case. The name of C<TO_JSON> was chosen because other | ||||
1088 | methods called by the Perl core (== not by the user of the object) are | ||||
1089 | usually in upper case letters and to avoid collisions with the C<to_json> | ||||
1090 | function or method. | ||||
1091 | |||||
1092 | This setting does not yet influence C<decode> in any way. | ||||
1093 | |||||
1094 | If C<$enable> is false, then the C<allow_blessed> setting will decide what | ||||
1095 | to do when a blessed object is found. | ||||
1096 | |||||
1097 | =over | ||||
1098 | |||||
1099 | =item convert_blessed_universally mode | ||||
1100 | |||||
1101 | If use C<JSON> with C<-convert_blessed_universally>, the C<UNIVERSAL::TO_JSON> | ||||
1102 | subroutine is defined as the below code: | ||||
1103 | |||||
1104 | *UNIVERSAL::TO_JSON = sub { | ||||
1105 | my $b_obj = B::svref_2object( $_[0] ); | ||||
1106 | return $b_obj->isa('B::HV') ? { %{ $_[0] } } | ||||
1107 | : $b_obj->isa('B::AV') ? [ @{ $_[0] } ] | ||||
1108 | : undef | ||||
1109 | ; | ||||
1110 | } | ||||
1111 | |||||
1112 | This will cause that C<encode> method converts simple blessed objects into | ||||
1113 | JSON objects as non-blessed object. | ||||
1114 | |||||
1115 | JSON -convert_blessed_universally; | ||||
1116 | $json->allow_blessed->convert_blessed->encode( $blessed_object ) | ||||
1117 | |||||
1118 | This feature is experimental and may be removed in the future. | ||||
1119 | |||||
1120 | =back | ||||
1121 | |||||
1122 | =head2 filter_json_object | ||||
1123 | |||||
1124 | $json = $json->filter_json_object([$coderef]) | ||||
1125 | |||||
1126 | When C<$coderef> is specified, it will be called from C<decode> each | ||||
1127 | time it decodes a JSON object. The only argument passed to the coderef | ||||
1128 | is a reference to the newly-created hash. If the code references returns | ||||
1129 | a single scalar (which need not be a reference), this value | ||||
1130 | (i.e. a copy of that scalar to avoid aliasing) is inserted into the | ||||
1131 | deserialised data structure. If it returns an empty list | ||||
1132 | (NOTE: I<not> C<undef>, which is a valid scalar), the original deserialised | ||||
1133 | hash will be inserted. This setting can slow down decoding considerably. | ||||
1134 | |||||
1135 | When C<$coderef> is omitted or undefined, any existing callback will | ||||
1136 | be removed and C<decode> will not change the deserialised hash in any | ||||
1137 | way. | ||||
1138 | |||||
1139 | Example, convert all JSON objects into the integer 5: | ||||
1140 | |||||
1141 | my $js = JSON->new->filter_json_object (sub { 5 }); | ||||
1142 | # returns [5] | ||||
1143 | $js->decode ('[{}]'); # the given subroutine takes a hash reference. | ||||
1144 | # throw an exception because allow_nonref is not enabled | ||||
1145 | # so a lone 5 is not allowed. | ||||
1146 | $js->decode ('{"a":1, "b":2}'); | ||||
1147 | |||||
1148 | |||||
1149 | =head2 filter_json_single_key_object | ||||
1150 | |||||
1151 | $json = $json->filter_json_single_key_object($key [=> $coderef]) | ||||
1152 | |||||
1153 | Works remotely similar to C<filter_json_object>, but is only called for | ||||
1154 | JSON objects having a single key named C<$key>. | ||||
1155 | |||||
1156 | This C<$coderef> is called before the one specified via | ||||
1157 | C<filter_json_object>, if any. It gets passed the single value in the JSON | ||||
1158 | object. If it returns a single value, it will be inserted into the data | ||||
1159 | structure. If it returns nothing (not even C<undef> but the empty list), | ||||
1160 | the callback from C<filter_json_object> will be called next, as if no | ||||
1161 | single-key callback were specified. | ||||
1162 | |||||
1163 | If C<$coderef> is omitted or undefined, the corresponding callback will be | ||||
1164 | disabled. There can only ever be one callback for a given key. | ||||
1165 | |||||
1166 | As this callback gets called less often then the C<filter_json_object> | ||||
1167 | one, decoding speed will not usually suffer as much. Therefore, single-key | ||||
1168 | objects make excellent targets to serialise Perl objects into, especially | ||||
1169 | as single-key JSON objects are as close to the type-tagged value concept | ||||
1170 | as JSON gets (it's basically an ID/VALUE tuple). Of course, JSON does not | ||||
1171 | support this in any way, so you need to make sure your data never looks | ||||
1172 | like a serialised Perl hash. | ||||
1173 | |||||
1174 | Typical names for the single object key are C<__class_whatever__>, or | ||||
1175 | C<$__dollars_are_rarely_used__$> or C<}ugly_brace_placement>, or even | ||||
1176 | things like C<__class_md5sum(classname)__>, to reduce the risk of clashing | ||||
1177 | with real hashes. | ||||
1178 | |||||
1179 | Example, decode JSON objects of the form C<< { "__widget__" => <id> } >> | ||||
1180 | into the corresponding C<< $WIDGET{<id>} >> object: | ||||
1181 | |||||
1182 | # return whatever is in $WIDGET{5}: | ||||
1183 | JSON | ||||
1184 | ->new | ||||
1185 | ->filter_json_single_key_object (__widget__ => sub { | ||||
1186 | $WIDGET{ $_[0] } | ||||
1187 | }) | ||||
1188 | ->decode ('{"__widget__": 5') | ||||
1189 | |||||
1190 | # this can be used with a TO_JSON method in some "widget" class | ||||
1191 | # for serialisation to json: | ||||
1192 | sub WidgetBase::TO_JSON { | ||||
1193 | my ($self) = @_; | ||||
1194 | |||||
1195 | unless ($self->{id}) { | ||||
1196 | $self->{id} = ..get..some..id..; | ||||
1197 | $WIDGET{$self->{id}} = $self; | ||||
1198 | } | ||||
1199 | |||||
1200 | { __widget__ => $self->{id} } | ||||
1201 | } | ||||
1202 | |||||
1203 | |||||
1204 | =head2 shrink | ||||
1205 | |||||
1206 | $json = $json->shrink([$enable]) | ||||
1207 | |||||
1208 | $enabled = $json->get_shrink | ||||
1209 | |||||
1210 | With JSON::XS, this flag resizes strings generated by either | ||||
1211 | C<encode> or C<decode> to their minimum size possible. This can save | ||||
1212 | memory when your JSON texts are either very very long or you have many | ||||
1213 | short strings. It will also try to downgrade any strings to octet-form | ||||
1214 | if possible: perl stores strings internally either in an encoding called | ||||
1215 | UTF-X or in octet-form. The latter cannot store everything but uses less | ||||
1216 | space in general (and some buggy Perl or C code might even rely on that | ||||
1217 | internal representation being used). | ||||
1218 | |||||
1219 | With JSON::PP, it is noop about resizing strings but tries | ||||
1220 | C<utf8::downgrade> to the returned string by C<encode>. See to L<utf8>. | ||||
1221 | |||||
1222 | See to L<JSON::XS/OBJECT-ORIENTED INTERFACE> and L<JSON::PP/METHODS>. | ||||
1223 | |||||
1224 | =head2 max_depth | ||||
1225 | |||||
1226 | $json = $json->max_depth([$maximum_nesting_depth]) | ||||
1227 | |||||
1228 | $max_depth = $json->get_max_depth | ||||
1229 | |||||
1230 | Sets the maximum nesting level (default C<512>) accepted while encoding | ||||
1231 | or decoding. If a higher nesting level is detected in JSON text or a Perl | ||||
1232 | data structure, then the encoder and decoder will stop and croak at that | ||||
1233 | point. | ||||
1234 | |||||
1235 | Nesting level is defined by number of hash- or arrayrefs that the encoder | ||||
1236 | needs to traverse to reach a given point or the number of C<{> or C<[> | ||||
1237 | characters without their matching closing parenthesis crossed to reach a | ||||
1238 | given character in a string. | ||||
1239 | |||||
1240 | If no argument is given, the highest possible setting will be used, which | ||||
1241 | is rarely useful. | ||||
1242 | |||||
1243 | Note that nesting is implemented by recursion in C. The default value has | ||||
1244 | been chosen to be as large as typical operating systems allow without | ||||
1245 | crashing. (JSON::XS) | ||||
1246 | |||||
1247 | With JSON::PP as the backend, when a large value (100 or more) was set and | ||||
1248 | it de/encodes a deep nested object/text, it may raise a warning | ||||
1249 | 'Deep recursion on subroutin' at the perl runtime phase. | ||||
1250 | |||||
1251 | See L<JSON::XS/SECURITY CONSIDERATIONS> for more info on why this is useful. | ||||
1252 | |||||
1253 | =head2 max_size | ||||
1254 | |||||
1255 | $json = $json->max_size([$maximum_string_size]) | ||||
1256 | |||||
1257 | $max_size = $json->get_max_size | ||||
1258 | |||||
1259 | Set the maximum length a JSON text may have (in bytes) where decoding is | ||||
1260 | being attempted. The default is C<0>, meaning no limit. When C<decode> | ||||
1261 | is called on a string that is longer then this many bytes, it will not | ||||
1262 | attempt to decode the string but throw an exception. This setting has no | ||||
1263 | effect on C<encode> (yet). | ||||
1264 | |||||
1265 | If no argument is given, the limit check will be deactivated (same as when | ||||
1266 | C<0> is specified). | ||||
1267 | |||||
1268 | See L<JSON::XS/SECURITY CONSIDERATIONS>, below, for more info on why this is useful. | ||||
1269 | |||||
1270 | =head2 encode | ||||
1271 | |||||
1272 | $json_text = $json->encode($perl_scalar) | ||||
1273 | |||||
1274 | Converts the given Perl data structure (a simple scalar or a reference | ||||
1275 | to a hash or array) to its JSON representation. Simple scalars will be | ||||
1276 | converted into JSON string or number sequences, while references to arrays | ||||
1277 | become JSON arrays and references to hashes become JSON objects. Undefined | ||||
1278 | Perl values (e.g. C<undef>) become JSON C<null> values. | ||||
1279 | References to the integers C<0> and C<1> are converted into C<true> and C<false>. | ||||
1280 | |||||
1281 | =head2 decode | ||||
1282 | |||||
1283 | $perl_scalar = $json->decode($json_text) | ||||
1284 | |||||
1285 | The opposite of C<encode>: expects a JSON text and tries to parse it, | ||||
1286 | returning the resulting simple scalar or reference. Croaks on error. | ||||
1287 | |||||
1288 | JSON numbers and strings become simple Perl scalars. JSON arrays become | ||||
1289 | Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes | ||||
1290 | C<1> (C<JSON::true>), C<false> becomes C<0> (C<JSON::false>) and | ||||
1291 | C<null> becomes C<undef>. | ||||
1292 | |||||
1293 | =head2 decode_prefix | ||||
1294 | |||||
1295 | ($perl_scalar, $characters) = $json->decode_prefix($json_text) | ||||
1296 | |||||
1297 | This works like the C<decode> method, but instead of raising an exception | ||||
1298 | when there is trailing garbage after the first JSON object, it will | ||||
1299 | silently stop parsing there and return the number of characters consumed | ||||
1300 | so far. | ||||
1301 | |||||
1302 | JSON->new->decode_prefix ("[1] the tail") | ||||
1303 | => ([], 3) | ||||
1304 | |||||
1305 | See to L<JSON::XS/OBJECT-ORIENTED INTERFACE> | ||||
1306 | |||||
1307 | =head2 property | ||||
1308 | |||||
1309 | $boolean = $json->property($property_name) | ||||
1310 | |||||
1311 | Returns a boolean value about above some properties. | ||||
1312 | |||||
1313 | The available properties are C<ascii>, C<latin1>, C<utf8>, | ||||
1314 | C<indent>,C<space_before>, C<space_after>, C<relaxed>, C<canonical>, | ||||
1315 | C<allow_nonref>, C<allow_unknown>, C<allow_blessed>, C<convert_blessed>, | ||||
1316 | C<shrink>, C<max_depth> and C<max_size>. | ||||
1317 | |||||
1318 | $boolean = $json->property('utf8'); | ||||
1319 | => 0 | ||||
1320 | $json->utf8; | ||||
1321 | $boolean = $json->property('utf8'); | ||||
1322 | => 1 | ||||
1323 | |||||
1324 | Sets the propery with a given boolean value. | ||||
1325 | |||||
1326 | $json = $json->property($property_name => $boolean); | ||||
1327 | |||||
1328 | With no argumnt, it returns all the above properties as a hash reference. | ||||
1329 | |||||
1330 | $flag_hashref = $json->property(); | ||||
1331 | |||||
1332 | =head1 INCREMENTAL PARSING | ||||
1333 | |||||
1334 | In JSON::XS 2.2, incremental parsing feature of JSON texts was implemented. | ||||
1335 | Please check to L<JSON::XS/INCREMENTAL PARSING>. | ||||
1336 | |||||
1337 | =over 4 | ||||
1338 | |||||
1339 | =item [void, scalar or list context] = $json->incr_parse ([$string]) | ||||
1340 | |||||
1341 | This is the central parsing function. It can both append new text and | ||||
1342 | extract objects from the stream accumulated so far (both of these | ||||
1343 | functions are optional). | ||||
1344 | |||||
1345 | If C<$string> is given, then this string is appended to the already | ||||
1346 | existing JSON fragment stored in the C<$json> object. | ||||
1347 | |||||
1348 | After that, if the function is called in void context, it will simply | ||||
1349 | return without doing anything further. This can be used to add more text | ||||
1350 | in as many chunks as you want. | ||||
1351 | |||||
1352 | If the method is called in scalar context, then it will try to extract | ||||
1353 | exactly I<one> JSON object. If that is successful, it will return this | ||||
1354 | object, otherwise it will return C<undef>. If there is a parse error, | ||||
1355 | this method will croak just as C<decode> would do (one can then use | ||||
1356 | C<incr_skip> to skip the errornous part). This is the most common way of | ||||
1357 | using the method. | ||||
1358 | |||||
1359 | And finally, in list context, it will try to extract as many objects | ||||
1360 | from the stream as it can find and return them, or the empty list | ||||
1361 | otherwise. For this to work, there must be no separators between the JSON | ||||
1362 | objects or arrays, instead they must be concatenated back-to-back. If | ||||
1363 | an error occurs, an exception will be raised as in the scalar context | ||||
1364 | case. Note that in this case, any previously-parsed JSON texts will be | ||||
1365 | lost. | ||||
1366 | |||||
1367 | =item $lvalue_string = $json->incr_text | ||||
1368 | |||||
1369 | This method returns the currently stored JSON fragment as an lvalue, that | ||||
1370 | is, you can manipulate it. This I<only> works when a preceding call to | ||||
1371 | C<incr_parse> in I<scalar context> successfully returned an object. Under | ||||
1372 | all other circumstances you must not call this function (I mean it. | ||||
1373 | although in simple tests it might actually work, it I<will> fail under | ||||
1374 | real world conditions). As a special exception, you can also call this | ||||
1375 | method before having parsed anything. | ||||
1376 | |||||
1377 | This function is useful in two cases: a) finding the trailing text after a | ||||
1378 | JSON object or b) parsing multiple JSON objects separated by non-JSON text | ||||
1379 | (such as commas). | ||||
1380 | |||||
1381 | In Perl 5.005, C<lvalue> attribute is not available. | ||||
1382 | You must write codes like the below: | ||||
1383 | |||||
1384 | $string = $json->incr_text; | ||||
1385 | $string =~ s/\s*,\s*//; | ||||
1386 | $json->incr_text( $string ); | ||||
1387 | |||||
1388 | =item $json->incr_skip | ||||
1389 | |||||
1390 | This will reset the state of the incremental parser and will remove the | ||||
1391 | parsed text from the input buffer. This is useful after C<incr_parse> | ||||
1392 | died, in which case the input buffer and incremental parser state is left | ||||
1393 | unchanged, to skip the text parsed so far and to reset the parse state. | ||||
1394 | |||||
1395 | =item $json->incr_reset | ||||
1396 | |||||
1397 | This completely resets the incremental parser, that is, after this call, | ||||
1398 | it will be as if the parser had never parsed anything. | ||||
1399 | |||||
1400 | This is useful if you want ot repeatedly parse JSON objects and want to | ||||
1401 | ignore any trailing data, which means you have to reset the parser after | ||||
1402 | each successful decode. | ||||
1403 | |||||
1404 | =back | ||||
1405 | |||||
1406 | =head1 JSON::PP SUPPORT METHODS | ||||
1407 | |||||
1408 | The below methods are JSON::PP own methods, so when C<JSON> works | ||||
1409 | with JSON::PP (i.e. the created object is a JSON::PP object), available. | ||||
1410 | See to L<JSON::PP/JSON::PP OWN METHODS> in detail. | ||||
1411 | |||||
1412 | If you use C<JSON> with additonal C<-support_by_pp>, some methods | ||||
1413 | are available even with JSON::XS. See to L<USE PP FEATURES EVEN THOUGH XS BACKEND>. | ||||
1414 | |||||
1415 | BEING { $ENV{PERL_JSON_BACKEND} = 'JSON::XS' } | ||||
1416 | |||||
1417 | use JSON -support_by_pp; | ||||
1418 | |||||
1419 | my $json = new JSON; | ||||
1420 | $json->allow_nonref->escape_slash->encode("/"); | ||||
1421 | |||||
1422 | # functional interfaces too. | ||||
1423 | print to_json(["/"], {escape_slash => 1}); | ||||
1424 | print from_json('["foo"]', {utf8 => 1}); | ||||
1425 | |||||
1426 | If you do not want to all functions but C<-support_by_pp>, | ||||
1427 | use C<-no_export>. | ||||
1428 | |||||
1429 | use JSON -support_by_pp, -no_export; | ||||
1430 | # functional interfaces are not exported. | ||||
1431 | |||||
1432 | =head2 allow_singlequote | ||||
1433 | |||||
1434 | $json = $json->allow_singlequote([$enable]) | ||||
1435 | |||||
1436 | If C<$enable> is true (or missing), then C<decode> will accept | ||||
1437 | any JSON strings quoted by single quotations that are invalid JSON | ||||
1438 | format. | ||||
1439 | |||||
1440 | $json->allow_singlequote->decode({"foo":'bar'}); | ||||
1441 | $json->allow_singlequote->decode({'foo':"bar"}); | ||||
1442 | $json->allow_singlequote->decode({'foo':'bar'}); | ||||
1443 | |||||
1444 | As same as the C<relaxed> option, this option may be used to parse | ||||
1445 | application-specific files written by humans. | ||||
1446 | |||||
1447 | =head2 allow_barekey | ||||
1448 | |||||
1449 | $json = $json->allow_barekey([$enable]) | ||||
1450 | |||||
1451 | If C<$enable> is true (or missing), then C<decode> will accept | ||||
1452 | bare keys of JSON object that are invalid JSON format. | ||||
1453 | |||||
1454 | As same as the C<relaxed> option, this option may be used to parse | ||||
1455 | application-specific files written by humans. | ||||
1456 | |||||
1457 | $json->allow_barekey->decode('{foo:"bar"}'); | ||||
1458 | |||||
1459 | =head2 allow_bignum | ||||
1460 | |||||
1461 | $json = $json->allow_bignum([$enable]) | ||||
1462 | |||||
1463 | If C<$enable> is true (or missing), then C<decode> will convert | ||||
1464 | the big integer Perl cannot handle as integer into a L<Math::BigInt> | ||||
1465 | object and convert a floating number (any) into a L<Math::BigFloat>. | ||||
1466 | |||||
1467 | On the contary, C<encode> converts C<Math::BigInt> objects and C<Math::BigFloat> | ||||
1468 | objects into JSON numbers with C<allow_blessed> enable. | ||||
1469 | |||||
1470 | $json->allow_nonref->allow_blessed->allow_bignum; | ||||
1471 | $bigfloat = $json->decode('2.000000000000000000000000001'); | ||||
1472 | print $json->encode($bigfloat); | ||||
1473 | # => 2.000000000000000000000000001 | ||||
1474 | |||||
1475 | See to L<MAPPING> aboout the conversion of JSON number. | ||||
1476 | |||||
1477 | =head2 loose | ||||
1478 | |||||
1479 | $json = $json->loose([$enable]) | ||||
1480 | |||||
1481 | The unescaped [\x00-\x1f\x22\x2f\x5c] strings are invalid in JSON strings | ||||
1482 | and the module doesn't allow to C<decode> to these (except for \x2f). | ||||
1483 | If C<$enable> is true (or missing), then C<decode> will accept these | ||||
1484 | unescaped strings. | ||||
1485 | |||||
1486 | $json->loose->decode(qq|["abc | ||||
1487 | def"]|); | ||||
1488 | |||||
1489 | See to L<JSON::PP/JSON::PP OWN METHODS>. | ||||
1490 | |||||
1491 | =head2 escape_slash | ||||
1492 | |||||
1493 | $json = $json->escape_slash([$enable]) | ||||
1494 | |||||
1495 | According to JSON Grammar, I<slash> (U+002F) is escaped. But by default | ||||
1496 | JSON backend modules encode strings without escaping slash. | ||||
1497 | |||||
1498 | If C<$enable> is true (or missing), then C<encode> will escape slashes. | ||||
1499 | |||||
1500 | =head2 indent_length | ||||
1501 | |||||
1502 | $json = $json->indent_length($length) | ||||
1503 | |||||
1504 | With JSON::XS, The indent space length is 3 and cannot be changed. | ||||
1505 | With JSON::PP, it sets the indent space length with the given $length. | ||||
1506 | The default is 3. The acceptable range is 0 to 15. | ||||
1507 | |||||
1508 | =head2 sort_by | ||||
1509 | |||||
1510 | $json = $json->sort_by($function_name) | ||||
1511 | $json = $json->sort_by($subroutine_ref) | ||||
1512 | |||||
1513 | If $function_name or $subroutine_ref are set, its sort routine are used. | ||||
1514 | |||||
1515 | $js = $pc->sort_by(sub { $JSON::PP::a cmp $JSON::PP::b })->encode($obj); | ||||
1516 | # is($js, q|{"a":1,"b":2,"c":3,"d":4,"e":5,"f":6,"g":7,"h":8,"i":9}|); | ||||
1517 | |||||
1518 | $js = $pc->sort_by('own_sort')->encode($obj); | ||||
1519 | # is($js, q|{"a":1,"b":2,"c":3,"d":4,"e":5,"f":6,"g":7,"h":8,"i":9}|); | ||||
1520 | |||||
1521 | sub JSON::PP::own_sort { $JSON::PP::a cmp $JSON::PP::b } | ||||
1522 | |||||
1523 | As the sorting routine runs in the JSON::PP scope, the given | ||||
1524 | subroutine name and the special variables C<$a>, C<$b> will begin | ||||
1525 | with 'JSON::PP::'. | ||||
1526 | |||||
1527 | If $integer is set, then the effect is same as C<canonical> on. | ||||
1528 | |||||
1529 | See to L<JSON::PP/JSON::PP OWN METHODS>. | ||||
1530 | |||||
1531 | =head1 MAPPING | ||||
1532 | |||||
1533 | This section is copied from JSON::XS and modified to C<JSON>. | ||||
1534 | JSON::XS and JSON::PP mapping mechanisms are almost equivalent. | ||||
1535 | |||||
1536 | See to L<JSON::XS/MAPPING>. | ||||
1537 | |||||
1538 | =head2 JSON -> PERL | ||||
1539 | |||||
1540 | =over 4 | ||||
1541 | |||||
1542 | =item object | ||||
1543 | |||||
1544 | A JSON object becomes a reference to a hash in Perl. No ordering of object | ||||
1545 | keys is preserved (JSON does not preserver object key ordering itself). | ||||
1546 | |||||
1547 | =item array | ||||
1548 | |||||
1549 | A JSON array becomes a reference to an array in Perl. | ||||
1550 | |||||
1551 | =item string | ||||
1552 | |||||
1553 | A JSON string becomes a string scalar in Perl - Unicode codepoints in JSON | ||||
1554 | are represented by the same codepoints in the Perl string, so no manual | ||||
1555 | decoding is necessary. | ||||
1556 | |||||
1557 | =item number | ||||
1558 | |||||
1559 | A JSON number becomes either an integer, numeric (floating point) or | ||||
1560 | string scalar in perl, depending on its range and any fractional parts. On | ||||
1561 | the Perl level, there is no difference between those as Perl handles all | ||||
1562 | the conversion details, but an integer may take slightly less memory and | ||||
1563 | might represent more values exactly than floating point numbers. | ||||
1564 | |||||
1565 | If the number consists of digits only, C<JSON> will try to represent | ||||
1566 | it as an integer value. If that fails, it will try to represent it as | ||||
1567 | a numeric (floating point) value if that is possible without loss of | ||||
1568 | precision. Otherwise it will preserve the number as a string value (in | ||||
1569 | which case you lose roundtripping ability, as the JSON number will be | ||||
1570 | re-encoded toa JSON string). | ||||
1571 | |||||
1572 | Numbers containing a fractional or exponential part will always be | ||||
1573 | represented as numeric (floating point) values, possibly at a loss of | ||||
1574 | precision (in which case you might lose perfect roundtripping ability, but | ||||
1575 | the JSON number will still be re-encoded as a JSON number). | ||||
1576 | |||||
1577 | If the backend is JSON::PP and C<allow_bignum> is enable, the big integers | ||||
1578 | and the numeric can be optionally converted into L<Math::BigInt> and | ||||
1579 | L<Math::BigFloat> objects. | ||||
1580 | |||||
1581 | =item true, false | ||||
1582 | |||||
1583 | These JSON atoms become C<JSON::true> and C<JSON::false>, | ||||
1584 | respectively. They are overloaded to act almost exactly like the numbers | ||||
1585 | C<1> and C<0>. You can check wether a scalar is a JSON boolean by using | ||||
1586 | the C<JSON::is_bool> function. | ||||
1587 | |||||
1588 | If C<JSON::true> and C<JSON::false> are used as strings or compared as strings, | ||||
1589 | they represent as C<true> and C<false> respectively. | ||||
1590 | |||||
1591 | print JSON::true . "\n"; | ||||
1592 | => true | ||||
1593 | print JSON::true + 1; | ||||
1594 | => 1 | ||||
1595 | |||||
1596 | ok(JSON::true eq 'true'); | ||||
1597 | ok(JSON::true eq '1'); | ||||
1598 | ok(JSON::true == 1); | ||||
1599 | |||||
1600 | C<JSON> will install these missing overloading features to the backend modules. | ||||
1601 | |||||
1602 | |||||
1603 | =item null | ||||
1604 | |||||
1605 | A JSON null atom becomes C<undef> in Perl. | ||||
1606 | |||||
1607 | C<JSON::null> returns C<unddef>. | ||||
1608 | |||||
1609 | =back | ||||
1610 | |||||
1611 | |||||
1612 | =head2 PERL -> JSON | ||||
1613 | |||||
1614 | The mapping from Perl to JSON is slightly more difficult, as Perl is a | ||||
1615 | truly typeless language, so we can only guess which JSON type is meant by | ||||
1616 | a Perl value. | ||||
1617 | |||||
1618 | =over 4 | ||||
1619 | |||||
1620 | =item hash references | ||||
1621 | |||||
1622 | Perl hash references become JSON objects. As there is no inherent ordering | ||||
1623 | in hash keys (or JSON objects), they will usually be encoded in a | ||||
1624 | pseudo-random order that can change between runs of the same program but | ||||
1625 | stays generally the same within a single run of a program. C<JSON> | ||||
1626 | optionally sort the hash keys (determined by the I<canonical> flag), so | ||||
1627 | the same datastructure will serialise to the same JSON text (given same | ||||
1628 | settings and version of JSON::XS), but this incurs a runtime overhead | ||||
1629 | and is only rarely useful, e.g. when you want to compare some JSON text | ||||
1630 | against another for equality. | ||||
1631 | |||||
1632 | In future, the ordered object feature will be added to JSON::PP using C<tie> mechanism. | ||||
1633 | |||||
1634 | |||||
1635 | =item array references | ||||
1636 | |||||
1637 | Perl array references become JSON arrays. | ||||
1638 | |||||
1639 | =item other references | ||||
1640 | |||||
1641 | Other unblessed references are generally not allowed and will cause an | ||||
1642 | exception to be thrown, except for references to the integers C<0> and | ||||
1643 | C<1>, which get turned into C<false> and C<true> atoms in JSON. You can | ||||
1644 | also use C<JSON::false> and C<JSON::true> to improve readability. | ||||
1645 | |||||
1646 | to_json [\0,JSON::true] # yields [false,true] | ||||
1647 | |||||
1648 | =item JSON::true, JSON::false, JSON::null | ||||
1649 | |||||
1650 | These special values become JSON true and JSON false values, | ||||
1651 | respectively. You can also use C<\1> and C<\0> directly if you want. | ||||
1652 | |||||
1653 | JSON::null returns C<undef>. | ||||
1654 | |||||
1655 | =item blessed objects | ||||
1656 | |||||
1657 | Blessed objects are not directly representable in JSON. See the | ||||
1658 | C<allow_blessed> and C<convert_blessed> methods on various options on | ||||
1659 | how to deal with this: basically, you can choose between throwing an | ||||
1660 | exception, encoding the reference as if it weren't blessed, or provide | ||||
1661 | your own serialiser method. | ||||
1662 | |||||
1663 | With C<convert_blessed_universally> mode, C<encode> converts blessed | ||||
1664 | hash references or blessed array references (contains other blessed references) | ||||
1665 | into JSON members and arrays. | ||||
1666 | |||||
1667 | use JSON -convert_blessed_universally; | ||||
1668 | JSON->new->allow_blessed->convert_blessed->encode( $blessed_object ); | ||||
1669 | |||||
1670 | See to L<convert_blessed>. | ||||
1671 | |||||
1672 | =item simple scalars | ||||
1673 | |||||
1674 | Simple Perl scalars (any scalar that is not a reference) are the most | ||||
1675 | difficult objects to encode: JSON::XS and JSON::PP will encode undefined scalars as | ||||
1676 | JSON C<null> values, scalars that have last been used in a string context | ||||
1677 | before encoding as JSON strings, and anything else as number value: | ||||
1678 | |||||
1679 | # dump as number | ||||
1680 | encode_json [2] # yields [2] | ||||
1681 | encode_json [-3.0e17] # yields [-3e+17] | ||||
1682 | my $value = 5; encode_json [$value] # yields [5] | ||||
1683 | |||||
1684 | # used as string, so dump as string | ||||
1685 | print $value; | ||||
1686 | encode_json [$value] # yields ["5"] | ||||
1687 | |||||
1688 | # undef becomes null | ||||
1689 | encode_json [undef] # yields [null] | ||||
1690 | |||||
1691 | You can force the type to be a string by stringifying it: | ||||
1692 | |||||
1693 | my $x = 3.1; # some variable containing a number | ||||
1694 | "$x"; # stringified | ||||
1695 | $x .= ""; # another, more awkward way to stringify | ||||
1696 | print $x; # perl does it for you, too, quite often | ||||
1697 | |||||
1698 | You can force the type to be a number by numifying it: | ||||
1699 | |||||
1700 | my $x = "3"; # some variable containing a string | ||||
1701 | $x += 0; # numify it, ensuring it will be dumped as a number | ||||
1702 | $x *= 1; # same thing, the choise is yours. | ||||
1703 | |||||
1704 | You can not currently force the type in other, less obscure, ways. | ||||
1705 | |||||
1706 | =item Big Number | ||||
1707 | |||||
1708 | If the backend is JSON::PP and C<allow_bignum> is enable, | ||||
1709 | C<encode> converts C<Math::BigInt> objects and C<Math::BigFloat> | ||||
1710 | objects into JSON numbers. | ||||
1711 | |||||
1712 | |||||
1713 | =back | ||||
1714 | |||||
1715 | =head1 JSON and ECMAscript | ||||
1716 | |||||
1717 | See to L<JSON::XS/JSON and ECMAscript>. | ||||
1718 | |||||
1719 | =head1 JSON and YAML | ||||
1720 | |||||
1721 | JSON is not a subset of YAML. | ||||
1722 | See to L<JSON::XS/JSON and YAML>. | ||||
1723 | |||||
1724 | |||||
1725 | =head1 BACKEND MODULE DECISION | ||||
1726 | |||||
1727 | When you use C<JSON>, C<JSON> tries to C<use> JSON::XS. If this call failed, it will | ||||
1728 | C<uses> JSON::PP. The required JSON::XS version is I<2.2> or later. | ||||
1729 | |||||
1730 | The C<JSON> constructor method returns an object inherited from the backend module, | ||||
1731 | and JSON::XS object is a blessed scaler reference while JSON::PP is a blessed hash | ||||
1732 | reference. | ||||
1733 | |||||
1734 | So, your program should not depend on the backend module, especially | ||||
1735 | returned objects should not be modified. | ||||
1736 | |||||
1737 | my $json = JSON->new; # XS or PP? | ||||
1738 | $json->{stash} = 'this is xs object'; # this code may raise an error! | ||||
1739 | |||||
1740 | To check the backend module, there are some methods - C<backend>, C<is_pp> and C<is_xs>. | ||||
1741 | |||||
1742 | JSON->backend; # 'JSON::XS' or 'JSON::PP' | ||||
1743 | |||||
1744 | JSON->backend->is_pp: # 0 or 1 | ||||
1745 | |||||
1746 | JSON->backend->is_xs: # 1 or 0 | ||||
1747 | |||||
1748 | $json->is_xs; # 1 or 0 | ||||
1749 | |||||
1750 | $json->is_pp; # 0 or 1 | ||||
1751 | |||||
1752 | |||||
1753 | If you set an enviornment variable C<PERL_JSON_BACKEND>, The calling action will be changed. | ||||
1754 | |||||
1755 | =over | ||||
1756 | |||||
1757 | =item PERL_JSON_BACKEND = 0 or PERL_JSON_BACKEND = 'JSON::PP' | ||||
1758 | |||||
1759 | Always use JSON::PP | ||||
1760 | |||||
1761 | =item PERL_JSON_BACKEND == 1 or PERL_JSON_BACKEND = 'JSON::XS,JSON::PP' | ||||
1762 | |||||
1763 | (The default) Use compiled JSON::XS if it is properly compiled & installed, | ||||
1764 | otherwise use JSON::PP. | ||||
1765 | |||||
1766 | =item PERL_JSON_BACKEND == 2 or PERL_JSON_BACKEND = 'JSON::XS' | ||||
1767 | |||||
1768 | Always use compiled JSON::XS, die if it isn't properly compiled & installed. | ||||
1769 | |||||
1770 | =back | ||||
1771 | |||||
1772 | These ideas come from L<DBI::PurePerl> mechanism. | ||||
1773 | |||||
1774 | example: | ||||
1775 | |||||
1776 | BEGIN { $ENV{PERL_JSON_BACKEND} = 'JSON::PP' } | ||||
1777 | use JSON; # always uses JSON::PP | ||||
1778 | |||||
1779 | In future, it may be able to specify another module. | ||||
1780 | |||||
1781 | =head1 USE PP FEATURES EVEN THOUGH XS BACKEND | ||||
1782 | |||||
1783 | Many methods are available with either JSON::XS or JSON::PP and | ||||
1784 | when the backend module is JSON::XS, if any JSON::PP specific (i.e. JSON::XS unspported) | ||||
1785 | method is called, it will C<warn> and be noop. | ||||
1786 | |||||
1787 | But If you C<use> C<JSON> passing the optional string C<-support_by_pp>, | ||||
1788 | it makes a part of those unupported methods available. | ||||
1789 | This feature is achieved by using JSON::PP in C<de/encode>. | ||||
1790 | |||||
1791 | BEGIN { $ENV{PERL_JSON_BACKEND} = 2 } # with JSON::XS | ||||
1792 | use JSON -support_by_pp; | ||||
1793 | my $json = new JSON; | ||||
1794 | $json->allow_nonref->escape_slash->encode("/"); | ||||
1795 | |||||
1796 | At this time, the returned object is a C<JSON::Backend::XS::Supportable> | ||||
1797 | object (re-blessed XS object), and by checking JSON::XS unsupported flags | ||||
1798 | in de/encoding, can support some unsupported methods - C<loose>, C<allow_bignum>, | ||||
1799 | C<allow_barekey>, C<allow_singlequote>, C<escape_slash>, C<as_nonblessed> | ||||
1800 | and C<indent_length>. | ||||
1801 | |||||
1802 | When any unsupported methods are not enable, C<XS de/encode> will be | ||||
1803 | used as is. The switch is achieved by changing the symbolic tables. | ||||
1804 | |||||
1805 | C<-support_by_pp> is effective only when the backend module is JSON::XS | ||||
1806 | and it makes the de/encoding speed down a bit. | ||||
1807 | |||||
1808 | See to L<JSON::PP SUPPORT METHODS>. | ||||
1809 | |||||
1810 | =head1 INCOMPATIBLE CHANGES TO OLD VERSION | ||||
1811 | |||||
1812 | There are big incompatibility between new version (2.00) and old (1.xx). | ||||
1813 | If you use old C<JSON> 1.xx in your code, please check it. | ||||
1814 | |||||
1815 | See to L<Transition ways from 1.xx to 2.xx.> | ||||
1816 | |||||
1817 | =over | ||||
1818 | |||||
1819 | =item jsonToObj and objToJson are obsoleted. | ||||
1820 | |||||
1821 | Non Perl-style name C<jsonToObj> and C<objToJson> are obsoleted | ||||
1822 | (but not yet deleted from the source). | ||||
1823 | If you use these functions in your code, please replace them | ||||
1824 | with C<from_json> and C<to_json>. | ||||
1825 | |||||
1826 | |||||
1827 | =item Global variables are no longer available. | ||||
1828 | |||||
1829 | C<JSON> class variables - C<$JSON::AUTOCONVERT>, C<$JSON::BareKey>, etc... | ||||
1830 | - are not avaliable any longer. | ||||
1831 | Instead, various features can be used through object methods. | ||||
1832 | |||||
1833 | |||||
1834 | =item Package JSON::Converter and JSON::Parser are deleted. | ||||
1835 | |||||
1836 | Now C<JSON> bundles with JSON::PP which can handle JSON more properly than them. | ||||
1837 | |||||
1838 | =item Package JSON::NotString is deleted. | ||||
1839 | |||||
1840 | There was C<JSON::NotString> class which represents JSON value C<true>, C<false>, C<null> | ||||
1841 | and numbers. It was deleted and replaced by C<JSON::Boolean>. | ||||
1842 | |||||
1843 | C<JSON::Boolean> represents C<true> and C<false>. | ||||
1844 | |||||
1845 | C<JSON::Boolean> does not represent C<null>. | ||||
1846 | |||||
1847 | C<JSON::null> returns C<undef>. | ||||
1848 | |||||
1849 | C<JSON> makes L<JSON::XS::Boolean> and L<JSON::PP::Boolean> is-a relation | ||||
1850 | to L<JSON::Boolean>. | ||||
1851 | |||||
1852 | =item function JSON::Number is obsoleted. | ||||
1853 | |||||
1854 | C<JSON::Number> is now needless because JSON::XS and JSON::PP have | ||||
1855 | round-trip integrity. | ||||
1856 | |||||
1857 | =item JSONRPC modules are deleted. | ||||
1858 | |||||
1859 | Perl implementation of JSON-RPC protocol - C<JSONRPC >, C<JSONRPC::Transport::HTTP> | ||||
1860 | and C<Apache::JSONRPC > are deleted in this distribution. | ||||
1861 | Instead of them, there is L<JSON::RPC> which supports JSON-RPC protocol version 1.1. | ||||
1862 | |||||
1863 | =back | ||||
1864 | |||||
1865 | =head2 Transition ways from 1.xx to 2.xx. | ||||
1866 | |||||
1867 | You should set C<suport_by_pp> mode firstly, because | ||||
1868 | it is always successful for the below codes even with JSON::XS. | ||||
1869 | |||||
1870 | use JSON -support_by_pp; | ||||
1871 | |||||
1872 | =over | ||||
1873 | |||||
1874 | =item Exported jsonToObj (simple) | ||||
1875 | |||||
1876 | from_json($json_text); | ||||
1877 | |||||
1878 | =item Exported objToJson (simple) | ||||
1879 | |||||
1880 | to_json($perl_scalar); | ||||
1881 | |||||
1882 | =item Exported jsonToObj (advanced) | ||||
1883 | |||||
1884 | $flags = {allow_barekey => 1, allow_singlequote => 1}; | ||||
1885 | from_json($json_text, $flags); | ||||
1886 | |||||
1887 | equivalent to: | ||||
1888 | |||||
1889 | $JSON::BareKey = 1; | ||||
1890 | $JSON::QuotApos = 1; | ||||
1891 | jsonToObj($json_text); | ||||
1892 | |||||
1893 | =item Exported objToJson (advanced) | ||||
1894 | |||||
1895 | $flags = {allow_blessed => 1, allow_barekey => 1}; | ||||
1896 | to_json($perl_scalar, $flags); | ||||
1897 | |||||
1898 | equivalent to: | ||||
1899 | |||||
1900 | $JSON::BareKey = 1; | ||||
1901 | objToJson($perl_scalar); | ||||
1902 | |||||
1903 | =item jsonToObj as object method | ||||
1904 | |||||
1905 | $json->decode($json_text); | ||||
1906 | |||||
1907 | =item objToJson as object method | ||||
1908 | |||||
1909 | $json->encode($perl_scalar); | ||||
1910 | |||||
1911 | =item new method with parameters | ||||
1912 | |||||
1913 | The C<new> method in 2.x takes any parameters no longer. | ||||
1914 | You can set parameters instead; | ||||
1915 | |||||
1916 | $json = JSON->new->pretty; | ||||
1917 | |||||
1918 | =item $JSON::Pretty, $JSON::Indent, $JSON::Delimiter | ||||
1919 | |||||
1920 | If C<indent> is enable, that menas C<$JSON::Pretty> flag set. And | ||||
1921 | C<$JSON::Delimiter> was substituted by C<space_before> and C<space_after>. | ||||
1922 | In conclusion: | ||||
1923 | |||||
1924 | $json->indent->space_before->space_after; | ||||
1925 | |||||
1926 | Equivalent to: | ||||
1927 | |||||
1928 | $json->pretty; | ||||
1929 | |||||
1930 | To change indent length, use C<indent_length>. | ||||
1931 | |||||
1932 | (Only with JSON::PP, if C<-support_by_pp> is not used.) | ||||
1933 | |||||
1934 | $json->pretty->indent_length(2)->encode($perl_scalar); | ||||
1935 | |||||
1936 | =item $JSON::BareKey | ||||
1937 | |||||
1938 | (Only with JSON::PP, if C<-support_by_pp> is not used.) | ||||
1939 | |||||
1940 | $json->allow_barekey->decode($json_text) | ||||
1941 | |||||
1942 | =item $JSON::ConvBlessed | ||||
1943 | |||||
1944 | use C<-convert_blessed_universally>. See to L<convert_blessed>. | ||||
1945 | |||||
1946 | =item $JSON::QuotApos | ||||
1947 | |||||
1948 | (Only with JSON::PP, if C<-support_by_pp> is not used.) | ||||
1949 | |||||
1950 | $json->allow_singlequote->decode($json_text) | ||||
1951 | |||||
1952 | =item $JSON::SingleQuote | ||||
1953 | |||||
1954 | Disable. C<JSON> does not make such a invalid JSON string any longer. | ||||
1955 | |||||
1956 | =item $JSON::KeySort | ||||
1957 | |||||
1958 | $json->canonical->encode($perl_scalar) | ||||
1959 | |||||
1960 | This is the ascii sort. | ||||
1961 | |||||
1962 | If you want to use with your own sort routine, check the C<sort_by> method. | ||||
1963 | |||||
1964 | (Only with JSON::PP, even if C<-support_by_pp> is used currently.) | ||||
1965 | |||||
1966 | $json->sort_by($sort_routine_ref)->encode($perl_scalar) | ||||
1967 | |||||
1968 | $json->sort_by(sub { $JSON::PP::a <=> $JSON::PP::b })->encode($perl_scalar) | ||||
1969 | |||||
1970 | Can't access C<$a> and C<$b> but C<$JSON::PP::a> and C<$JSON::PP::b>. | ||||
1971 | |||||
1972 | =item $JSON::SkipInvalid | ||||
1973 | |||||
1974 | $json->allow_unknown | ||||
1975 | |||||
1976 | =item $JSON::AUTOCONVERT | ||||
1977 | |||||
1978 | Needless. C<JSON> backend modules have the round-trip integrity. | ||||
1979 | |||||
1980 | =item $JSON::UTF8 | ||||
1981 | |||||
1982 | Needless because C<JSON> (JSON::XS/JSON::PP) sets | ||||
1983 | the UTF8 flag on properly. | ||||
1984 | |||||
1985 | # With UTF8-flagged strings | ||||
1986 | |||||
1987 | $json->allow_nonref; | ||||
1988 | $str = chr(1000); # UTF8-flagged | ||||
1989 | |||||
1990 | $json_text = $json->utf8(0)->encode($str); | ||||
1991 | utf8::is_utf8($json_text); | ||||
1992 | # true | ||||
1993 | $json_text = $json->utf8(1)->encode($str); | ||||
1994 | utf8::is_utf8($json_text); | ||||
1995 | # false | ||||
1996 | |||||
1997 | $str = '"' . chr(1000) . '"'; # UTF8-flagged | ||||
1998 | |||||
1999 | $perl_scalar = $json->utf8(0)->decode($str); | ||||
2000 | utf8::is_utf8($perl_scalar); | ||||
2001 | # true | ||||
2002 | $perl_scalar = $json->utf8(1)->decode($str); | ||||
2003 | # died because of 'Wide character in subroutine' | ||||
2004 | |||||
2005 | See to L<JSON::XS/A FEW NOTES ON UNICODE AND PERL>. | ||||
2006 | |||||
2007 | =item $JSON::UnMapping | ||||
2008 | |||||
2009 | Disable. See to L<MAPPING>. | ||||
2010 | |||||
2011 | =item $JSON::SelfConvert | ||||
2012 | |||||
2013 | This option was deleted. | ||||
2014 | Instead of it, if a givien blessed object has the C<TO_JSON> method, | ||||
2015 | C<TO_JSON> will be executed with C<convert_blessed>. | ||||
2016 | |||||
2017 | $json->convert_blessed->encode($bleesed_hashref_or_arrayref) | ||||
2018 | # if need, call allow_blessed | ||||
2019 | |||||
2020 | Note that it was C<toJson> in old version, but now not C<toJson> but C<TO_JSON>. | ||||
2021 | |||||
2022 | =back | ||||
2023 | |||||
2024 | =head1 TODO | ||||
2025 | |||||
2026 | =over | ||||
2027 | |||||
2028 | =item example programs | ||||
2029 | |||||
2030 | =back | ||||
2031 | |||||
2032 | =head1 THREADS | ||||
2033 | |||||
2034 | No test with JSON::PP. If with JSON::XS, See to L<JSON::XS/THREADS>. | ||||
2035 | |||||
2036 | |||||
2037 | =head1 BUGS | ||||
2038 | |||||
2039 | Please report bugs relevant to C<JSON> to E<lt>makamaka[at]cpan.orgE<gt>. | ||||
2040 | |||||
2041 | |||||
2042 | =head1 SEE ALSO | ||||
2043 | |||||
2044 | Most of the document is copied and modified from JSON::XS doc. | ||||
2045 | |||||
2046 | L<JSON::XS>, L<JSON::PP> | ||||
2047 | |||||
2048 | C<RFC4627>(L<http://www.ietf.org/rfc/rfc4627.txt>) | ||||
2049 | |||||
2050 | =head1 AUTHOR | ||||
2051 | |||||
2052 | Makamaka Hannyaharamitu, E<lt>makamaka[at]cpan.orgE<gt> | ||||
2053 | |||||
2054 | JSON::XS was written by Marc Lehmann <schmorp[at]schmorp.de> | ||||
2055 | |||||
2056 | The relese of this new version owes to the courtesy of Marc Lehmann. | ||||
2057 | |||||
2058 | |||||
2059 | =head1 COPYRIGHT AND LICENSE | ||||
2060 | |||||
2061 | Copyright 2005-2009 by Makamaka Hannyaharamitu | ||||
2062 | |||||
2063 | This library is free software; you can redistribute it and/or modify | ||||
2064 | it under the same terms as Perl itself. | ||||
2065 | |||||
2066 | =cut | ||||
2067 | |||||
# spent 19µs within JSON::CORE:close which was called
# once (19µs+0s) by JSON::_load_xs at line 250 of JSON.pm | |||||
# spent 666µs within JSON::CORE:readline which was called
# once (666µs+0s) by JSON::_load_xs at line 249 of JSON.pm |