| OLD | NEW |
|---|
| (Empty) | |
| 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 o
nes. |
| 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 distributio
n, 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 ei
ther |
| 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 an
d |
| 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), s
o 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 Per
l side problem, |
| 236 \&\s-1JSON::PP\s0 works slower in the versions. And in 5.005, the Unicode handli
ng is not available. |
| 237 See to \*(L"\s-1UNICODE\s0 \s-1HANDLING\s0 \s-1ON\s0 \s-1PERLS\s0\*(R" in \s-1JS
ON::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 Per
l |
| 246 level. (e.g. the string \*(L"2.0\*(R" doesn't suddenly become \*(L"2\*(R" just b
ecause |
| 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 instea
d 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 trans
port |
| 276 is not 8\-bit clean, still supports the whole Unicode range), or a pretty-printe
d |
| 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 funct
ions. |
| 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 result
ing |
| 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 ma
pped 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-1UNIC
ODE\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`d
ecode\*(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`utf
8\*(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 dat
a 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\-e
ncoded 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 mo
dule 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`utf
8\*(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 i
t. |
| 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_jso
n\*(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\s
0 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 ca
n |
| 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 generat
e 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 char
acters 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-1JS
ON::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 char
acters |
| 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 expec
ts to be handled |
| 566 an UTF\-8\-encoded string. Please note that UTF\-8\-encoded strings do not conta
in 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-1U
TF\-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 enco
ding |
| 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-1JS
ON::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 c
all 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 metho
d 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 cha
nge 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 metho
d 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 a
dd 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 metho
d will add an extra |
| 658 optional space after the \f(CW\*(C`:\*(C'\fR separating keys from values in \s-1
JSON\s0 objects |
| 659 and extra whitespace after the \f(CW\*(C`,\*(C'\fR separating key-value pairs an
d array |
| 660 members. |
| 661 .PP |
| 662 If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will not a
dd 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 acce
pt some |
| 681 extensions to normal \s-1JSON\s0 syntax (see below). \f(CW\*(C`encode\*(C'\fR wi
ll 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 on
ly 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. Th
is |
| 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 metho
d 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 outpu
t 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 metho
d 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 metho
d 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 th
e |
| 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 th
row 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 enc
ountering 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_blesse
d\*(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 recursio
n cycle |
| 820 (== crash) in this case. The name of \f(CW\*(C`TO_JSON\*(C'\fR was chosen becaus
e 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 wi
ll 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 obj
ects 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 o
riginal 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 referenc
e. |
| 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 call
ed 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 i
f 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-1JS
ON\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_p
lacement\*(C'\fR, or even |
| 911 things like \f(CW\*(C`_\|_class_md5sum(classname)_\|_\*(C'\fR, to reduce the ris
k 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 pos
sible. 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 an
d |
| 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`deco
de\*(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, f
or 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 array
s |
| 1017 become \s-1JSON\s0 arrays and references to hashes become \s-1JSON\s0 objects. U
ndefined |
| 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 t
o 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(C
W0\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 e
xception |
| 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`all
ow_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-1PA
RSING\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 su
re 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 nee
d |
| 1099 to set resource limits (e.g. \f(CW\*(C`max_size\*(C'\fR) to ensure the parser wi
ll 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 er
ror, |
| 1127 this method will croak just as \f(CW\*(C`decode\*(C'\fR would do (one can then u
se |
| 1128 \&\f(CW\*(C`incr_skip\*(C'\fR to skip the erroneous part). This is the most comm
on 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 exampl
es. |
| 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'\f
R works |
| 1201 with \s-1JSON::PP\s0 (i.e. the created object is a \s-1JSON::PP\s0 object), avai
lable. |
| 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-1FE
ATURES\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 acce
pt |
| 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 pars
e |
| 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 acce
pt |
| 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 pars
e |
| 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 conv
ert |
| 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'\f
R 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 s
trings |
| 1288 and the module doesn't allow to \f(CW\*(C`decode\*(C'\fR to these (except for \e
x2f). |
| 1289 If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will acc
ept 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 defaul
t |
| 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 esca
pe 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$lengt
h\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 a
re 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 objec
t |
| 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 repres
ent |
| 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 i
ncluding |
| 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 boole
an 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 st
rings or compared as strings, |
| 1399 they represent as \f(CW\*(C`true\*(C'\fR and \f(CW\*(C`false\*(C'\fR respectivel
y. |
| 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 orderin
g |
| 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'\f
R |
| 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 impro
ve 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 d
irectly 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 und
efined 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`u
se\*(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 i
s \fI2.2\fR or later. |
| 1535 .PP |
| 1536 The \f(CW\*(C`JSON\*(C'\fR constructor method returns an object inherited from t
he backend module, |
| 1537 and \s-1JSON::XS\s0 object is a blessed scalar reference while \s-1JSON::PP\s0 i
s 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 call
ing 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\s
0,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 & installe
d, |
| 1569 otherwise use \s-1JSON::PP\s0. |
| 1570 .IP "\s-1PERL_JSON_BACKEND\s0 == 2 or \s-1PERL_JSON_BACKEND\s0 = '\s-1JSON::XS\s
0'" 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 & install
ed. |
| 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 str
ing \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 unsupport
ed 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$JS
ON::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-1JSO
N\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 v
alue \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 rela
tion |
| 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 vers
ion 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 cu
rrently.) |
| 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-1PE
RL\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 metho
d, |
| 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\s
0\*(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. |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 15736030:
Add JSON.pm to third_party (Closed)
Base URL: svn://svn.chromium.org/chrome/trunk/src