src/third_party/JSON/JSON-2.59/blib/man3/JSON.3pm

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