← Index
NYTProf Performance Profile   « block view • line view • sub view »
For 05.Domain_and_Item.t
  Run on Tue May 4 17:21:41 2010
Reported on Tue May 4 17:22:23 2010

File /usr/local/lib/perl5/site_perl/5.10.1/JSON.pm
Statements Executed 130
Statement Execution Time 4.40ms
Subroutines — ordered by exclusive time
Calls P F Exclusive
Time
Inclusive
Time
Subroutine
1111.10ms4.41msJSON::::_load_xs JSON::_load_xs
112666µs666µsJSON::::CORE:readline JSON::CORE:readline (opcode)
221238µs344µsJSON::Boolean::::_overrride_overload JSON::Boolean::_overrride_overload
811157µs327µsJSON::::to_json JSON::to_json
51189µs182µsJSON::::from_json JSON::from_json
11147µs47µsJSON::::_set_module JSON::_set_module
22230µs275µsJSON::::import JSON::import
11219µs19µsJSON::::CORE:close JSON::CORE:close (opcode)
11114µs35µsJSON::::BEGIN@284 JSON::BEGIN@284
11113µs16µsJSON::::BEGIN@4 JSON::BEGIN@4
1117µs62µsJSON::::BEGIN@6 JSON::BEGIN@6
1117µs18µsJSON::Backend::PP::::BEGIN@349JSON::Backend::PP::BEGIN@349
1114µs4µsJSON::::BEGIN@9 JSON::BEGIN@9
1113µs3µsJSON::::BEGIN@5 JSON::BEGIN@5
0000s0sJSON::Backend::PP::::__ANON__[:352]JSON::Backend::PP::__ANON__[:352]
0000s0sJSON::Backend::PP::::__ANON__[:353]JSON::Backend::PP::__ANON__[:353]
0000s0sJSON::Backend::PP::::initJSON::Backend::PP::init
0000s0sJSON::::__ANON__[:298] JSON::__ANON__[:298]
0000s0sJSON::::_load_pp JSON::_load_pp
0000s0sJSON::::backend JSON::backend
0000s0sJSON::::false JSON::false
0000s0sJSON::::is_pp JSON::is_pp
0000s0sJSON::::is_xs JSON::is_xs
0000s0sJSON::::jsonToObj JSON::jsonToObj
0000s0sJSON::::null JSON::null
0000s0sJSON::::objToJson JSON::objToJson
0000s0sJSON::::property JSON::property
0000s0sJSON::::pureperl_only_methods JSON::pureperl_only_methods
0000s0sJSON::::require_xs_version JSON::require_xs_version
0000s0sJSON::::true JSON::true
Call graph for these subroutines as a Graphviz dot language file.
Line State
ments
Time
on line
Calls Time
in subs
Code
1package JSON;
2
3
4326µs218µ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
use strict;
# spent 16µs making 1 call to JSON::BEGIN@4 # spent 3µs making 1 call to strict::import
5320µs13µs
# spent 3µs within JSON::BEGIN@5 which was called # once (3µs+0s) by SimpleDB::Class::SQL::BEGIN@18 at line 5
use Carp ();
# spent 3µs making 1 call to JSON::BEGIN@5
6352µs2116µ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
use base qw(Exporter);
# spent 62µs making 1 call to JSON::BEGIN@6 # spent 54µs making 1 call to base::import
712µ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
BEGIN {
1024µs $JSON::VERSION = '2.16';
11 $JSON::DEBUG = 0 unless (defined $JSON::DEBUG);
1211.09ms14µs}
# spent 4µs making 1 call to JSON::BEGIN@9
13
141300nsmy $Module_XS = 'JSON::XS';
151200nsmy $Module_PP = 'JSON::PP';
161100nsmy $XS_Version = '2.26';
17
18
19# XS and PP common methods
20
2113µsmy @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
2712µsmy @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
321100nsmy @XSOnlyMethods = qw//; # Currently nothing
33
3411µsmy @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)
411100nsmy $_INSTALL_DONT_DIE = 1; # When _load_xs fails to load XS, don't die.
4210smy $_INSTALL_ONLY = 2; # Don't call _set_methods()
4310smy $_ALLOW_UNSUPPORTED = 0;
4410smy $_UNIV_CONV_BLESSED = 0;
45
46
47# Check the environment variable to decide worker module.
48
491400nsunless ($JSON::Backend) {
501100ns $JSON::DEBUG and Carp::carp("Check used worker module...");
51
521700ns my $backend = exists $ENV{PERL_JSON_BACKEND} ? $ENV{PERL_JSON_BACKEND} : 1;
53
5413µs14.41ms 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
sub import {
701221µ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
109sub 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
118sub 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
sub to_json ($@) {
13124324µs854µ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
sub from_json ($@) {
14515182µs520µ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
158sub true { $JSON::true }
159
160sub false { $JSON::false }
161
162sub null { undef; }
163
164
165sub require_xs_version { $XS_Version; }
166
167sub backend {
168 my $proto = shift;
169 $JSON::Backend;
170}
171
172#*module = *backend;
173
174
175sub is_xs {
176 return $_[0]->module eq $Module_XS;
177}
178
179
180sub is_pp {
181 return $_[0]->module eq $Module_PP;
182}
183
184
185sub pureperl_only_methods { @PPOnlyMethods; }
186
187
188sub 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
sub _load_xs {
227131.08ms 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
2351142µs22.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 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
2511743µs12348µ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
259sub _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
sub _set_module {
2811747µs my $module = shift;
282
283 local $^W;
2843232µs255µ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
no strict qw(refs);
# 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 };
299 }
300
301 return 1;
302}
303
304
305
306#
307# JSON Boolean
308#
309
310package JSON::Boolean;
311
3121200nsmy %Installed;
313
314
# spent 344µs (238+106) within JSON::Boolean::_overrride_overload which was called 2 times, avg 172µs/call: # once (123µs+70µs) by JSON::_load_xs at line 232 # once (114µs+37µs) by JSON::_load_xs at line 233
sub _overrride_overload {
31510233µs return if ($Installed{ $_[0] }++);
316
317 my $boolean = $_[0] . '::Boolean';
318
319135µs4178µ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
345package JSON::Backend::PP;
346
347sub init {
348 local $^W;
3493101µs229µ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
no strict qw(refs);
# 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
361package JSON;
362
363153µs1;
364__DATA__
365
366
367#
368# Helper classes for Backend Module (XS)
369#
370
371package JSON::Backend::XS;
372
373use constant INDENT_LENGTH_FLAG => 15 << 12;
374
375use constant UNSUPPORTED_ENCODE_FLAG => {
376 ESCAPE_SLASH => 0x00000010,
377 ALLOW_BIGNUM => 0x00000020,
378 AS_NONBLESSED => 0x00000040,
379 EXPANDED => 0x10000000, # for developer's
380};
381
382use 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
391sub 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
402sub 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
442package JSON::Backend::XS::Supportable;
443
444
445my $JSON_XS_encode_orignal = \&JSON::XS::encode;
446my $JSON_XS_decode_orignal = \&JSON::XS::decode;
447
448$Carp::Internal{'JSON::Backend::XS::Supportable'} = 1;
449
450sub _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
484sub _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
511sub _encode { # using with PP encod
512 _set_for_pp('encode' => @_)->encode($_[1]);
513}
514
515
516sub _decode { # if unsupported-flag is set, use PP
517 _set_for_pp('decode' => @_)->decode($_[1]);
518}
519
520
521sub decode_prefix { # if unsupported-flag is set, use PP
522 _set_for_pp('decode' => @_)->decode_prefix($_[1]);
523}
524
525
526sub get_indent_length {
527 ${$_[0]} << 4 >> 16;
528}
529
530
531sub 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
5491;
550__END__
551
552=head1 NAME
553
554JSON - 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
591This 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
603JSON (JavaScript Object Notation) is a simple data format.
604See to L<http://www.json.org/> and C<RFC4627>(L<http://www.ietf.org/rfc/rfc4627.txt>).
605
606This module converts Perl data structures to JSON and vice versa using either
607L<JSON::XS> or L<JSON::PP>.
608
609JSON::XS is the fastest and most proper JSON module on CPAN which must be
610compiled and installed in your environment.
611JSON::PP is a pure-Perl module which is bundled in this distribution and
612has a strong compatibility to JSON::XS.
613
614This module try to use JSON::XS by default and fail to it, use JSON::PP instead.
615So its features completely depend on JSON::XS or JSON::PP.
616
617See to L<BACKEND MODULE DECISION>.
618
619To distinguish the module name 'JSON' and the format type JSON,
620the former is quoted by CE<lt>E<gt> (its results vary with your using media),
621and the latter is left just as it is.
622
623Module name : C<JSON>
624
625Format type : JSON
626
627=head2 FEATURES
628
629=over
630
631=item * correct unicode handling
632
633This module (i.e. backend modules) knows how to handle Unicode, documents
634how and when it does so, and even documents what "correct" means.
635
636Even though there are limitations, this feature is available since Perl version 5.6.
637
638JSON::XS requires Perl 5.8.2 (but works correctly in 5.8.8 or later), so in older versions
639C<JSON> sholud call JSON::PP as the backend which can be used since Perl 5.005.
640
641With Perl 5.8.x JSON::PP works, but from 5.8.0 to 5.8.2, because of a Perl side problem,
642JSON::PP works slower in the versions. And in 5.005, the Unicode handling is not available.
643See to L<JSON::PP/UNICODE HANDLING ON PERLS> for more information.
644
645See also to L<JSON::XS/A FEW NOTES ON UNICODE AND PERL>
646and L<JSON::XS/ENCODING/CODESET_FLAG_NOTES>.
647
648
649=item * round-trip integrity
650
651When you serialise a perl data structure using only data types supported by JSON,
652the 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
654like a number). There minor I<are> exceptions to this, read the MAPPING
655section below to learn about those.
656
657=item * strict checking of JSON correctness
658
659There is no guessing, no generating of illegal JSON texts by default,
660and only JSON is accepted as input by default (the latter is a security
661feature).
662
663See to L<JSON::XS/FEATURES> and L<JSON::PP/FEATURES>.
664
665=item * fast
666
667This module returns a JSON::XS object itself if avaliable.
668Compared to other JSON modules and other serialisers such as Storable,
669JSON::XS usually compares favourably in terms of speed, too.
670
671If not avaliable, C<JSON> returns a JSON::PP object instead of JSON::XS and
672it is very slow as pure-Perl.
673
674=item * simple to use
675
676This module has both a simple functional interface as well as an
677object oriented interface interface.
678
679=item * reasonably versatile output formats
680
681You 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
683is not 8-bit clean, still supports the whole Unicode range), or a pretty-printed
684format (for when you want to read that stuff). Or you can combine those features
685in whatever way you like.
686
687=back
688
689=head1 FUNCTIONAL INTERFACE
690
691Some documents are copied and modified from L<JSON::XS/FUNCTIONAL INTERFACE>.
692C<to_json> and C<from_json> are additional functions.
693
694=head2 to_json
695
696 $json_text = to_json($perl_scalar)
697
698Converts the given Perl data structure to a json string.
699
700This function call is functionally identical to:
701
702 $json_text = JSON->new->encode($perl_scalar)
703
704Takes a hash reference as the second.
705
706 $json_text = to_json($perl_scalar, $flag_hashref)
707
708So,
709
710 $json_text = encode_json($perl_scalar, {utf8 => 1, pretty => 1})
711
712equivalent 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
721The opposite of C<to_json>: expects a json string and tries
722to parse it, returning the resulting reference.
723
724This function call is functionally identical to:
725
726 $perl_scalar = JSON->decode($json_text)
727
728Takes a hash reference as the second.
729
730 $perl_scalar = from_json($json_text, $flag_hashref)
731
732So,
733
734 $perl_scalar = from_json($json_text, {utf8 => 1})
735
736equivalent 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
744Converts the given Perl data structure to a UTF-8 encoded, binary string.
745
746This 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
754The opposite of C<encode_json>: expects an UTF-8 (binary) string and tries
755to parse that as an UTF-8 encoded JSON text, returning the resulting
756reference.
757
758This 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
766Returns true if the passed scalar represents either JSON::true or
767JSON::false, two constants that act like C<1> and C<0> respectively
768and are also used to represent JSON C<true> and C<false> in Perl strings.
769
770=head2 JSON::true
771
772Returns JSON true value which is blessed object.
773It C<isa> JSON::Boolean object.
774
775=head2 JSON::false
776
777Returns JSON false value which is blessed object.
778It C<isa> JSON::Boolean object.
779
780=head2 JSON::null
781
782Returns C<undef>.
783
784See L<MAPPING>, below, for more information on how JSON values are mapped to
785Perl.
786
787=head1 COMMON OBJECT-ORIENTED INTERFACE
788
789
790=head2 new
791
792 $json = new JSON
793
794Returns a new C<JSON> object inherited from either JSON::XS or JSON::PP
795that can be used to de/encode JSON strings.
796
797All boolean flags described below are by default I<disabled>.
798
799The mutators for flags all return the JSON object again and thus calls can
800be 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
811If $enable is true (or missing), then the encode method will not generate characters outside
812the code range 0..127. Any Unicode characters outside that range will be escaped using either
813a single \uXXXX or a double \uHHHH\uLLLLL escape sequence, as per RFC4627.
814
815If $enable is false, then the encode method will not escape Unicode characters unless
816required by the JSON syntax or other flags. This results in a faster and more compact format.
817
818This feature depends on the used Perl version and environment.
819
820See 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
831If $enable is true (or missing), then the encode method will encode the resulting JSON
832text as latin1 (or iso-8859-1), escaping any characters outside the code range 0..255.
833
834If $enable is false, then the encode method will not escape Unicode characters
835unless 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
846If $enable is true (or missing), then the encode method will encode the JSON result
847into UTF-8, as required by many protocols, while the decode method expects to be handled
848an UTF-8-encoded string. Please note that UTF-8-encoded strings do not contain any
849characters outside the range 0..255, they are thus useful for bytewise/binary I/O.
850
851In future versions, enabling this option might enable autodetection of the UTF-16 and UTF-32
852encoding families, as described in RFC4627.
853
854If $enable is false, then the encode method will return the JSON string as a (non-encoded)
855Unicode 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
859Example, output UTF-16BE-encoded JSON:
860
861 use Encode;
862 $jsontext = encode "UTF-16BE", JSON::XS->new->encode ($object);
863
864Example, decode UTF-32LE-encoded JSON:
865
866 use Encode;
867 $object = JSON::XS->new->decode (decode "UTF-32LE", $jsontext);
868
869See 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
876This enables (or disables) all of the C<indent>, C<space_before> and
877C<space_after> (and in the future possibly more) flags in one call to
878generate the most readable (or most compact) form possible.
879
880Equivalent to:
881
882 $json->indent->space_before->space_after
883
884The indent space length is three and JSON::XS cannot change the indent
885space length.
886
887=head2 indent
888
889 $json = $json->indent([$enable])
890
891 $enabled = $json->get_indent
892
893If C<$enable> is true (or missing), then the C<encode> method will use a multiline
894format as output, putting every array member or object/hash key-value pair
895into its own line, identing them properly.
896
897If C<$enable> is false, no newlines or indenting will be produced, and the
898resulting JSON text is guarenteed not to contain any C<newlines>.
899
900This setting has no effect when decoding JSON texts.
901
902The indent space length is three.
903With 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
912If C<$enable> is true (or missing), then the C<encode> method will add an extra
913optional space before the C<:> separating keys from values in JSON objects.
914
915If C<$enable> is false, then the C<encode> method will not add any extra
916space at those places.
917
918This setting has no effect when decoding JSON texts.
919
920Example, 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
931If C<$enable> is true (or missing), then the C<encode> method will add an extra
932optional space after the C<:> separating keys from values in JSON objects
933and extra whitespace after the C<,> separating key-value pairs and array
934members.
935
936If C<$enable> is false, then the C<encode> method will not add any extra
937space at those places.
938
939This setting has no effect when decoding JSON texts.
940
941Example, 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
952If C<$enable> is true (or missing), then C<decode> will accept some
953extensions to normal JSON syntax (see below). C<encode> will not be
954affected in anyway. I<Be aware that this option makes you accept invalid
955JSON texts as if they were valid!>. I suggest only to use this option to
956parse application-specific files written by humans (configuration files,
957resource files etc.)
958
959If C<$enable> is false (the default), then C<decode> will only accept
960valid JSON texts.
961
962Currently accepted extensions are:
963
964=over 4
965
966=item * list items can have an end-comma
967
968JSON I<separates> array elements and key-value pairs with commas. This
969can be annoying if you write JSON texts manually and want to be able to
970quickly append elements, so this extension accepts comma at the end of
971such 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
984Whenever JSON allows whitespace, shell-style comments are additionally
985allowed. They are terminated by the first carriage-return or line-feed
986character, 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
1002If C<$enable> is true (or missing), then the C<encode> method will output JSON objects
1003by sorting their keys. This is adding a comparatively high overhead.
1004
1005If C<$enable> is false, then the C<encode> method will output key-value
1006pairs in the order Perl stores them (which will likely change between runs
1007of the same script).
1008
1009This option is useful if you want the same data structure to be encoded as
1010the same JSON text (given the same overall settings). If it is disabled,
1011the same hash might be encoded differently even if contains the same data,
1012as key-value pairs have no inherent ordering in Perl.
1013
1014This 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
1022If C<$enable> is true (or missing), then the C<encode> method can convert a
1023non-reference into its corresponding string, number or null JSON value,
1024which is an extension to RFC4627. Likewise, C<decode> will accept those JSON
1025values instead of croaking.
1026
1027If C<$enable> is false, then the C<encode> method will croak if it isn't
1028passed an arrayref or hashref, as JSON texts must either be an object
1029or array. Likewise, C<decode> will croak if given something that is not a
1030JSON 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
1041If $enable is true (or missing), then "encode" will *not* throw an
1042exception when it encounters values it cannot represent in JSON (for
1043example, filehandles) but instead will encode a JSON "null" value.
1044Note that blessed objects are not included here and are handled
1045separately by c<allow_nonref>.
1046
1047If $enable is false (the default), then "encode" will throw an
1048exception when it encounters anything it cannot encode as JSON.
1049
1050This option does not affect "decode" in any way, and it is
1051recommended to leave it off unless you know your communications
1052partner.
1053
1054=head2 allow_blessed
1055
1056 $json = $json->allow_blessed([$enable])
1057
1058 $enabled = $json->get_allow_blessed
1059
1060If C<$enable> is true (or missing), then the C<encode> method will not
1061barf when it encounters a blessed reference. Instead, the value of the
1062B<convert_blessed> option will decide whether C<null> (C<convert_blessed>
1063disabled or no C<TO_JSON> method found) or a representation of the
1064object (C<convert_blessed> enabled and C<TO_JSON> method found) is being
1065encoded. Has no effect on C<decode>.
1066
1067If C<$enable> is false (the default), then C<encode> will throw an
1068exception 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
1077If C<$enable> is true (or missing), then C<encode>, upon encountering a
1078blessed object, will check for the availability of the C<TO_JSON> method
1079on the object's class. If found, it will be called in scalar context
1080and the resulting scalar will be encoded instead of the object. If no
1081C<TO_JSON> method is found, the value of C<allow_blessed> will decide what
1082to do.
1083
1084The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON>
1085returns other blessed objects, those will be handled in the same
1086way. 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
1088methods called by the Perl core (== not by the user of the object) are
1089usually in upper case letters and to avoid collisions with the C<to_json>
1090function or method.
1091
1092This setting does not yet influence C<decode> in any way.
1093
1094If C<$enable> is false, then the C<allow_blessed> setting will decide what
1095to do when a blessed object is found.
1096
1097=over
1098
1099=item convert_blessed_universally mode
1100
1101If use C<JSON> with C<-convert_blessed_universally>, the C<UNIVERSAL::TO_JSON>
1102subroutine 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
1112This will cause that C<encode> method converts simple blessed objects into
1113JSON objects as non-blessed object.
1114
1115 JSON -convert_blessed_universally;
1116 $json->allow_blessed->convert_blessed->encode( $blessed_object )
1117
1118This 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
1126When C<$coderef> is specified, it will be called from C<decode> each
1127time it decodes a JSON object. The only argument passed to the coderef
1128is a reference to the newly-created hash. If the code references returns
1129a 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
1131deserialised data structure. If it returns an empty list
1132(NOTE: I<not> C<undef>, which is a valid scalar), the original deserialised
1133hash will be inserted. This setting can slow down decoding considerably.
1134
1135When C<$coderef> is omitted or undefined, any existing callback will
1136be removed and C<decode> will not change the deserialised hash in any
1137way.
1138
1139Example, 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
1153Works remotely similar to C<filter_json_object>, but is only called for
1154JSON objects having a single key named C<$key>.
1155
1156This C<$coderef> is called before the one specified via
1157C<filter_json_object>, if any. It gets passed the single value in the JSON
1158object. If it returns a single value, it will be inserted into the data
1159structure. If it returns nothing (not even C<undef> but the empty list),
1160the callback from C<filter_json_object> will be called next, as if no
1161single-key callback were specified.
1162
1163If C<$coderef> is omitted or undefined, the corresponding callback will be
1164disabled. There can only ever be one callback for a given key.
1165
1166As this callback gets called less often then the C<filter_json_object>
1167one, decoding speed will not usually suffer as much. Therefore, single-key
1168objects make excellent targets to serialise Perl objects into, especially
1169as single-key JSON objects are as close to the type-tagged value concept
1170as JSON gets (it's basically an ID/VALUE tuple). Of course, JSON does not
1171support this in any way, so you need to make sure your data never looks
1172like a serialised Perl hash.
1173
1174Typical names for the single object key are C<__class_whatever__>, or
1175C<$__dollars_are_rarely_used__$> or C<}ugly_brace_placement>, or even
1176things like C<__class_md5sum(classname)__>, to reduce the risk of clashing
1177with real hashes.
1178
1179Example, decode JSON objects of the form C<< { "__widget__" => <id> } >>
1180into 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
1210With JSON::XS, this flag resizes strings generated by either
1211C<encode> or C<decode> to their minimum size possible. This can save
1212memory when your JSON texts are either very very long or you have many
1213short strings. It will also try to downgrade any strings to octet-form
1214if possible: perl stores strings internally either in an encoding called
1215UTF-X or in octet-form. The latter cannot store everything but uses less
1216space in general (and some buggy Perl or C code might even rely on that
1217internal representation being used).
1218
1219With JSON::PP, it is noop about resizing strings but tries
1220C<utf8::downgrade> to the returned string by C<encode>. See to L<utf8>.
1221
1222See 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
1230Sets the maximum nesting level (default C<512>) accepted while encoding
1231or decoding. If a higher nesting level is detected in JSON text or a Perl
1232data structure, then the encoder and decoder will stop and croak at that
1233point.
1234
1235Nesting level is defined by number of hash- or arrayrefs that the encoder
1236needs to traverse to reach a given point or the number of C<{> or C<[>
1237characters without their matching closing parenthesis crossed to reach a
1238given character in a string.
1239
1240If no argument is given, the highest possible setting will be used, which
1241is rarely useful.
1242
1243Note that nesting is implemented by recursion in C. The default value has
1244been chosen to be as large as typical operating systems allow without
1245crashing. (JSON::XS)
1246
1247With JSON::PP as the backend, when a large value (100 or more) was set and
1248it de/encodes a deep nested object/text, it may raise a warning
1249'Deep recursion on subroutin' at the perl runtime phase.
1250
1251See 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
1259Set the maximum length a JSON text may have (in bytes) where decoding is
1260being attempted. The default is C<0>, meaning no limit. When C<decode>
1261is called on a string that is longer then this many bytes, it will not
1262attempt to decode the string but throw an exception. This setting has no
1263effect on C<encode> (yet).
1264
1265If no argument is given, the limit check will be deactivated (same as when
1266C<0> is specified).
1267
1268See 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
1274Converts the given Perl data structure (a simple scalar or a reference
1275to a hash or array) to its JSON representation. Simple scalars will be
1276converted into JSON string or number sequences, while references to arrays
1277become JSON arrays and references to hashes become JSON objects. Undefined
1278Perl values (e.g. C<undef>) become JSON C<null> values.
1279References 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
1285The opposite of C<encode>: expects a JSON text and tries to parse it,
1286returning the resulting simple scalar or reference. Croaks on error.
1287
1288JSON numbers and strings become simple Perl scalars. JSON arrays become
1289Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes
1290C<1> (C<JSON::true>), C<false> becomes C<0> (C<JSON::false>) and
1291C<null> becomes C<undef>.
1292
1293=head2 decode_prefix
1294
1295 ($perl_scalar, $characters) = $json->decode_prefix($json_text)
1296
1297This works like the C<decode> method, but instead of raising an exception
1298when there is trailing garbage after the first JSON object, it will
1299silently stop parsing there and return the number of characters consumed
1300so far.
1301
1302 JSON->new->decode_prefix ("[1] the tail")
1303 => ([], 3)
1304
1305See to L<JSON::XS/OBJECT-ORIENTED INTERFACE>
1306
1307=head2 property
1308
1309 $boolean = $json->property($property_name)
1310
1311Returns a boolean value about above some properties.
1312
1313The available properties are C<ascii>, C<latin1>, C<utf8>,
1314C<indent>,C<space_before>, C<space_after>, C<relaxed>, C<canonical>,
1315C<allow_nonref>, C<allow_unknown>, C<allow_blessed>, C<convert_blessed>,
1316C<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
1324Sets the propery with a given boolean value.
1325
1326 $json = $json->property($property_name => $boolean);
1327
1328With no argumnt, it returns all the above properties as a hash reference.
1329
1330 $flag_hashref = $json->property();
1331
1332=head1 INCREMENTAL PARSING
1333
1334In JSON::XS 2.2, incremental parsing feature of JSON texts was implemented.
1335Please check to L<JSON::XS/INCREMENTAL PARSING>.
1336
1337=over 4
1338
1339=item [void, scalar or list context] = $json->incr_parse ([$string])
1340
1341This is the central parsing function. It can both append new text and
1342extract objects from the stream accumulated so far (both of these
1343functions are optional).
1344
1345If C<$string> is given, then this string is appended to the already
1346existing JSON fragment stored in the C<$json> object.
1347
1348After that, if the function is called in void context, it will simply
1349return without doing anything further. This can be used to add more text
1350in as many chunks as you want.
1351
1352If the method is called in scalar context, then it will try to extract
1353exactly I<one> JSON object. If that is successful, it will return this
1354object, otherwise it will return C<undef>. If there is a parse error,
1355this method will croak just as C<decode> would do (one can then use
1356C<incr_skip> to skip the errornous part). This is the most common way of
1357using the method.
1358
1359And finally, in list context, it will try to extract as many objects
1360from the stream as it can find and return them, or the empty list
1361otherwise. For this to work, there must be no separators between the JSON
1362objects or arrays, instead they must be concatenated back-to-back. If
1363an error occurs, an exception will be raised as in the scalar context
1364case. Note that in this case, any previously-parsed JSON texts will be
1365lost.
1366
1367=item $lvalue_string = $json->incr_text
1368
1369This method returns the currently stored JSON fragment as an lvalue, that
1370is, you can manipulate it. This I<only> works when a preceding call to
1371C<incr_parse> in I<scalar context> successfully returned an object. Under
1372all other circumstances you must not call this function (I mean it.
1373although in simple tests it might actually work, it I<will> fail under
1374real world conditions). As a special exception, you can also call this
1375method before having parsed anything.
1376
1377This function is useful in two cases: a) finding the trailing text after a
1378JSON object or b) parsing multiple JSON objects separated by non-JSON text
1379(such as commas).
1380
1381In Perl 5.005, C<lvalue> attribute is not available.
1382You 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
1390This will reset the state of the incremental parser and will remove the
1391parsed text from the input buffer. This is useful after C<incr_parse>
1392died, in which case the input buffer and incremental parser state is left
1393unchanged, to skip the text parsed so far and to reset the parse state.
1394
1395=item $json->incr_reset
1396
1397This completely resets the incremental parser, that is, after this call,
1398it will be as if the parser had never parsed anything.
1399
1400This is useful if you want ot repeatedly parse JSON objects and want to
1401ignore any trailing data, which means you have to reset the parser after
1402each successful decode.
1403
1404=back
1405
1406=head1 JSON::PP SUPPORT METHODS
1407
1408The below methods are JSON::PP own methods, so when C<JSON> works
1409with JSON::PP (i.e. the created object is a JSON::PP object), available.
1410See to L<JSON::PP/JSON::PP OWN METHODS> in detail.
1411
1412If you use C<JSON> with additonal C<-support_by_pp>, some methods
1413are 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
1426If you do not want to all functions but C<-support_by_pp>,
1427use 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
1436If C<$enable> is true (or missing), then C<decode> will accept
1437any JSON strings quoted by single quotations that are invalid JSON
1438format.
1439
1440 $json->allow_singlequote->decode({"foo":'bar'});
1441 $json->allow_singlequote->decode({'foo':"bar"});
1442 $json->allow_singlequote->decode({'foo':'bar'});
1443
1444As same as the C<relaxed> option, this option may be used to parse
1445application-specific files written by humans.
1446
1447=head2 allow_barekey
1448
1449 $json = $json->allow_barekey([$enable])
1450
1451If C<$enable> is true (or missing), then C<decode> will accept
1452bare keys of JSON object that are invalid JSON format.
1453
1454As same as the C<relaxed> option, this option may be used to parse
1455application-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
1463If C<$enable> is true (or missing), then C<decode> will convert
1464the big integer Perl cannot handle as integer into a L<Math::BigInt>
1465object and convert a floating number (any) into a L<Math::BigFloat>.
1466
1467On the contary, C<encode> converts C<Math::BigInt> objects and C<Math::BigFloat>
1468objects 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
1475See to L<MAPPING> aboout the conversion of JSON number.
1476
1477=head2 loose
1478
1479 $json = $json->loose([$enable])
1480
1481The unescaped [\x00-\x1f\x22\x2f\x5c] strings are invalid in JSON strings
1482and the module doesn't allow to C<decode> to these (except for \x2f).
1483If C<$enable> is true (or missing), then C<decode> will accept these
1484unescaped strings.
1485
1486 $json->loose->decode(qq|["abc
1487 def"]|);
1488
1489See to L<JSON::PP/JSON::PP OWN METHODS>.
1490
1491=head2 escape_slash
1492
1493 $json = $json->escape_slash([$enable])
1494
1495According to JSON Grammar, I<slash> (U+002F) is escaped. But by default
1496JSON backend modules encode strings without escaping slash.
1497
1498If 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
1504With JSON::XS, The indent space length is 3 and cannot be changed.
1505With JSON::PP, it sets the indent space length with the given $length.
1506The 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
1513If $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
1523As the sorting routine runs in the JSON::PP scope, the given
1524subroutine name and the special variables C<$a>, C<$b> will begin
1525with 'JSON::PP::'.
1526
1527If $integer is set, then the effect is same as C<canonical> on.
1528
1529See to L<JSON::PP/JSON::PP OWN METHODS>.
1530
1531=head1 MAPPING
1532
1533This section is copied from JSON::XS and modified to C<JSON>.
1534JSON::XS and JSON::PP mapping mechanisms are almost equivalent.
1535
1536See to L<JSON::XS/MAPPING>.
1537
1538=head2 JSON -> PERL
1539
1540=over 4
1541
1542=item object
1543
1544A JSON object becomes a reference to a hash in Perl. No ordering of object
1545keys is preserved (JSON does not preserver object key ordering itself).
1546
1547=item array
1548
1549A JSON array becomes a reference to an array in Perl.
1550
1551=item string
1552
1553A JSON string becomes a string scalar in Perl - Unicode codepoints in JSON
1554are represented by the same codepoints in the Perl string, so no manual
1555decoding is necessary.
1556
1557=item number
1558
1559A JSON number becomes either an integer, numeric (floating point) or
1560string scalar in perl, depending on its range and any fractional parts. On
1561the Perl level, there is no difference between those as Perl handles all
1562the conversion details, but an integer may take slightly less memory and
1563might represent more values exactly than floating point numbers.
1564
1565If the number consists of digits only, C<JSON> will try to represent
1566it as an integer value. If that fails, it will try to represent it as
1567a numeric (floating point) value if that is possible without loss of
1568precision. Otherwise it will preserve the number as a string value (in
1569which case you lose roundtripping ability, as the JSON number will be
1570re-encoded toa JSON string).
1571
1572Numbers containing a fractional or exponential part will always be
1573represented as numeric (floating point) values, possibly at a loss of
1574precision (in which case you might lose perfect roundtripping ability, but
1575the JSON number will still be re-encoded as a JSON number).
1576
1577If the backend is JSON::PP and C<allow_bignum> is enable, the big integers
1578and the numeric can be optionally converted into L<Math::BigInt> and
1579L<Math::BigFloat> objects.
1580
1581=item true, false
1582
1583These JSON atoms become C<JSON::true> and C<JSON::false>,
1584respectively. They are overloaded to act almost exactly like the numbers
1585C<1> and C<0>. You can check wether a scalar is a JSON boolean by using
1586the C<JSON::is_bool> function.
1587
1588If C<JSON::true> and C<JSON::false> are used as strings or compared as strings,
1589they 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
1600C<JSON> will install these missing overloading features to the backend modules.
1601
1602
1603=item null
1604
1605A JSON null atom becomes C<undef> in Perl.
1606
1607C<JSON::null> returns C<unddef>.
1608
1609=back
1610
1611
1612=head2 PERL -> JSON
1613
1614The mapping from Perl to JSON is slightly more difficult, as Perl is a
1615truly typeless language, so we can only guess which JSON type is meant by
1616a Perl value.
1617
1618=over 4
1619
1620=item hash references
1621
1622Perl hash references become JSON objects. As there is no inherent ordering
1623in hash keys (or JSON objects), they will usually be encoded in a
1624pseudo-random order that can change between runs of the same program but
1625stays generally the same within a single run of a program. C<JSON>
1626optionally sort the hash keys (determined by the I<canonical> flag), so
1627the same datastructure will serialise to the same JSON text (given same
1628settings and version of JSON::XS), but this incurs a runtime overhead
1629and is only rarely useful, e.g. when you want to compare some JSON text
1630against another for equality.
1631
1632In future, the ordered object feature will be added to JSON::PP using C<tie> mechanism.
1633
1634
1635=item array references
1636
1637Perl array references become JSON arrays.
1638
1639=item other references
1640
1641Other unblessed references are generally not allowed and will cause an
1642exception to be thrown, except for references to the integers C<0> and
1643C<1>, which get turned into C<false> and C<true> atoms in JSON. You can
1644also 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
1650These special values become JSON true and JSON false values,
1651respectively. You can also use C<\1> and C<\0> directly if you want.
1652
1653JSON::null returns C<undef>.
1654
1655=item blessed objects
1656
1657Blessed objects are not directly representable in JSON. See the
1658C<allow_blessed> and C<convert_blessed> methods on various options on
1659how to deal with this: basically, you can choose between throwing an
1660exception, encoding the reference as if it weren't blessed, or provide
1661your own serialiser method.
1662
1663With C<convert_blessed_universally> mode, C<encode> converts blessed
1664hash references or blessed array references (contains other blessed references)
1665into JSON members and arrays.
1666
1667 use JSON -convert_blessed_universally;
1668 JSON->new->allow_blessed->convert_blessed->encode( $blessed_object );
1669
1670See to L<convert_blessed>.
1671
1672=item simple scalars
1673
1674Simple Perl scalars (any scalar that is not a reference) are the most
1675difficult objects to encode: JSON::XS and JSON::PP will encode undefined scalars as
1676JSON C<null> values, scalars that have last been used in a string context
1677before 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
1691You 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
1698You 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
1704You can not currently force the type in other, less obscure, ways.
1705
1706=item Big Number
1707
1708If the backend is JSON::PP and C<allow_bignum> is enable,
1709C<encode> converts C<Math::BigInt> objects and C<Math::BigFloat>
1710objects into JSON numbers.
1711
1712
1713=back
1714
1715=head1 JSON and ECMAscript
1716
1717See to L<JSON::XS/JSON and ECMAscript>.
1718
1719=head1 JSON and YAML
1720
1721JSON is not a subset of YAML.
1722See to L<JSON::XS/JSON and YAML>.
1723
1724
1725=head1 BACKEND MODULE DECISION
1726
1727When you use C<JSON>, C<JSON> tries to C<use> JSON::XS. If this call failed, it will
1728C<uses> JSON::PP. The required JSON::XS version is I<2.2> or later.
1729
1730The C<JSON> constructor method returns an object inherited from the backend module,
1731and JSON::XS object is a blessed scaler reference while JSON::PP is a blessed hash
1732reference.
1733
1734So, your program should not depend on the backend module, especially
1735returned 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
1740To 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
1753If 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
1759Always 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,
1764otherwise use JSON::PP.
1765
1766=item PERL_JSON_BACKEND == 2 or PERL_JSON_BACKEND = 'JSON::XS'
1767
1768Always use compiled JSON::XS, die if it isn't properly compiled & installed.
1769
1770=back
1771
1772These ideas come from L<DBI::PurePerl> mechanism.
1773
1774example:
1775
1776 BEGIN { $ENV{PERL_JSON_BACKEND} = 'JSON::PP' }
1777 use JSON; # always uses JSON::PP
1778
1779In future, it may be able to specify another module.
1780
1781=head1 USE PP FEATURES EVEN THOUGH XS BACKEND
1782
1783Many methods are available with either JSON::XS or JSON::PP and
1784when the backend module is JSON::XS, if any JSON::PP specific (i.e. JSON::XS unspported)
1785method is called, it will C<warn> and be noop.
1786
1787But If you C<use> C<JSON> passing the optional string C<-support_by_pp>,
1788it makes a part of those unupported methods available.
1789This 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
1796At this time, the returned object is a C<JSON::Backend::XS::Supportable>
1797object (re-blessed XS object), and by checking JSON::XS unsupported flags
1798in de/encoding, can support some unsupported methods - C<loose>, C<allow_bignum>,
1799C<allow_barekey>, C<allow_singlequote>, C<escape_slash>, C<as_nonblessed>
1800and C<indent_length>.
1801
1802When any unsupported methods are not enable, C<XS de/encode> will be
1803used as is. The switch is achieved by changing the symbolic tables.
1804
1805C<-support_by_pp> is effective only when the backend module is JSON::XS
1806and it makes the de/encoding speed down a bit.
1807
1808See to L<JSON::PP SUPPORT METHODS>.
1809
1810=head1 INCOMPATIBLE CHANGES TO OLD VERSION
1811
1812There are big incompatibility between new version (2.00) and old (1.xx).
1813If you use old C<JSON> 1.xx in your code, please check it.
1814
1815See to L<Transition ways from 1.xx to 2.xx.>
1816
1817=over
1818
1819=item jsonToObj and objToJson are obsoleted.
1820
1821Non Perl-style name C<jsonToObj> and C<objToJson> are obsoleted
1822(but not yet deleted from the source).
1823If you use these functions in your code, please replace them
1824with C<from_json> and C<to_json>.
1825
1826
1827=item Global variables are no longer available.
1828
1829C<JSON> class variables - C<$JSON::AUTOCONVERT>, C<$JSON::BareKey>, etc...
1830- are not avaliable any longer.
1831Instead, various features can be used through object methods.
1832
1833
1834=item Package JSON::Converter and JSON::Parser are deleted.
1835
1836Now C<JSON> bundles with JSON::PP which can handle JSON more properly than them.
1837
1838=item Package JSON::NotString is deleted.
1839
1840There was C<JSON::NotString> class which represents JSON value C<true>, C<false>, C<null>
1841and numbers. It was deleted and replaced by C<JSON::Boolean>.
1842
1843C<JSON::Boolean> represents C<true> and C<false>.
1844
1845C<JSON::Boolean> does not represent C<null>.
1846
1847C<JSON::null> returns C<undef>.
1848
1849C<JSON> makes L<JSON::XS::Boolean> and L<JSON::PP::Boolean> is-a relation
1850to L<JSON::Boolean>.
1851
1852=item function JSON::Number is obsoleted.
1853
1854C<JSON::Number> is now needless because JSON::XS and JSON::PP have
1855round-trip integrity.
1856
1857=item JSONRPC modules are deleted.
1858
1859Perl implementation of JSON-RPC protocol - C<JSONRPC >, C<JSONRPC::Transport::HTTP>
1860and C<Apache::JSONRPC > are deleted in this distribution.
1861Instead 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
1867You should set C<suport_by_pp> mode firstly, because
1868it 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
1887equivalent 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
1898equivalent 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
1913The C<new> method in 2.x takes any parameters no longer.
1914You can set parameters instead;
1915
1916 $json = JSON->new->pretty;
1917
1918=item $JSON::Pretty, $JSON::Indent, $JSON::Delimiter
1919
1920If C<indent> is enable, that menas C<$JSON::Pretty> flag set. And
1921C<$JSON::Delimiter> was substituted by C<space_before> and C<space_after>.
1922In conclusion:
1923
1924 $json->indent->space_before->space_after;
1925
1926Equivalent to:
1927
1928 $json->pretty;
1929
1930To 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
1944use 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
1954Disable. 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
1960This is the ascii sort.
1961
1962If 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
1970Can'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
1978Needless. C<JSON> backend modules have the round-trip integrity.
1979
1980=item $JSON::UTF8
1981
1982Needless because C<JSON> (JSON::XS/JSON::PP) sets
1983the 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
2005See to L<JSON::XS/A FEW NOTES ON UNICODE AND PERL>.
2006
2007=item $JSON::UnMapping
2008
2009Disable. See to L<MAPPING>.
2010
2011=item $JSON::SelfConvert
2012
2013This option was deleted.
2014Instead of it, if a givien blessed object has the C<TO_JSON> method,
2015C<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
2020Note 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
2034No test with JSON::PP. If with JSON::XS, See to L<JSON::XS/THREADS>.
2035
2036
2037=head1 BUGS
2038
2039Please report bugs relevant to C<JSON> to E<lt>makamaka[at]cpan.orgE<gt>.
2040
2041
2042=head1 SEE ALSO
2043
2044Most of the document is copied and modified from JSON::XS doc.
2045
2046L<JSON::XS>, L<JSON::PP>
2047
2048C<RFC4627>(L<http://www.ietf.org/rfc/rfc4627.txt>)
2049
2050=head1 AUTHOR
2051
2052Makamaka Hannyaharamitu, E<lt>makamaka[at]cpan.orgE<gt>
2053
2054JSON::XS was written by Marc Lehmann <schmorp[at]schmorp.de>
2055
2056The relese of this new version owes to the courtesy of Marc Lehmann.
2057
2058
2059=head1 COPYRIGHT AND LICENSE
2060
2061Copyright 2005-2009 by Makamaka Hannyaharamitu
2062
2063This library is free software; you can redistribute it and/or modify
2064it 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
sub JSON::CORE:close; # xsub
# spent 666µs within JSON::CORE:readline which was called # once (666µs+0s) by JSON::_load_xs at line 249 of JSON.pm
sub JSON::CORE:readline; # xsub