| 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::backportPP 3pm" | |
| 127 .TH JSON::backportPP 3pm "2013-05-23" "perl v5.14.2" "User Contributed Perl Docu
mentation" | |
| 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::PP \- JSON::XS compatible pure\-Perl module. | |
| 134 .SH "SYNOPSIS" | |
| 135 .IX Header "SYNOPSIS" | |
| 136 .Vb 1 | |
| 137 \& use JSON::PP; | |
| 138 \& | |
| 139 \& # exported functions, they croak on error | |
| 140 \& # and expect/generate UTF\-8 | |
| 141 \& | |
| 142 \& $utf8_encoded_json_text = encode_json $perl_hash_or_arrayref; | |
| 143 \& $perl_hash_or_arrayref = decode_json $utf8_encoded_json_text; | |
| 144 \& | |
| 145 \& # OO\-interface | |
| 146 \& | |
| 147 \& $coder = JSON::PP\->new\->ascii\->pretty\->allow_nonref; | |
| 148 \& | |
| 149 \& $json_text = $json\->encode( $perl_scalar ); | |
| 150 \& $perl_scalar = $json\->decode( $json_text ); | |
| 151 \& | |
| 152 \& $pretty_printed = $json\->pretty\->encode( $perl_scalar ); # pretty\-printing | |
| 153 \& | |
| 154 \& # Note that JSON version 2.0 and above will automatically use | |
| 155 \& # JSON::XS or JSON::PP, so you should be able to just: | |
| 156 \& | |
| 157 \& use JSON; | |
| 158 .Ve | |
| 159 .SH "VERSION" | |
| 160 .IX Header "VERSION" | |
| 161 .Vb 1 | |
| 162 \& 2.27200 | |
| 163 .Ve | |
| 164 .PP | |
| 165 \&\s-1JSON::XS\s0 2.27 (~2.30) compatible. | |
| 166 .SH "DESCRIPTION" | |
| 167 .IX Header "DESCRIPTION" | |
| 168 This module is \s-1JSON::XS\s0 compatible pure Perl module. | |
| 169 (Perl 5.8 or later is recommended) | |
| 170 .PP | |
| 171 \&\s-1JSON::XS\s0 is the fastest and most proper \s-1JSON\s0 module on \s-1CPAN\
s0. | |
| 172 It is written by Marc Lehmann in C, so must be compiled and | |
| 173 installed in the used environment. | |
| 174 .PP | |
| 175 \&\s-1JSON::PP\s0 is a pure-Perl module and has compatibility to \s-1JSON::XS\s0
. | |
| 176 .SS "\s-1FEATURES\s0" | |
| 177 .IX Subsection "FEATURES" | |
| 178 .IP "\(bu" 4 | |
| 179 correct unicode handling | |
| 180 .Sp | |
| 181 This module knows how to handle Unicode (depending on Perl version). | |
| 182 .Sp | |
| 183 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 and | |
| 184 \&\*(L"\s-1UNICODE\s0 \s-1HANDLING\s0 \s-1ON\s0 \s-1PERLS\s0\*(R". | |
| 185 .IP "\(bu" 4 | |
| 186 round-trip integrity | |
| 187 .Sp | |
| 188 When you serialise a perl data structure using only data types | |
| 189 supported by \s-1JSON\s0 and Perl, the deserialised data structure is | |
| 190 identical on the Perl level. (e.g. the string \*(L"2.0\*(R" doesn't suddenly | |
| 191 become \*(L"2\*(R" just because it looks like a number). There \fIare\fR minor | |
| 192 exceptions to this, read the \s-1MAPPING\s0 section below to learn about | |
| 193 those. | |
| 194 .IP "\(bu" 4 | |
| 195 strict checking of \s-1JSON\s0 correctness | |
| 196 .Sp | |
| 197 There is no guessing, no generating of illegal \s-1JSON\s0 texts by default, | |
| 198 and only \s-1JSON\s0 is accepted as input by default (the latter is a | |
| 199 security feature). But when some options are set, loose checking | |
| 200 features are available. | |
| 201 .SH "FUNCTIONAL INTERFACE" | |
| 202 .IX Header "FUNCTIONAL INTERFACE" | |
| 203 Some documents are copied and modified from \*(L"\s-1FUNCTIONAL\s0 \s-1INTERFACE
\s0\*(R" in \s-1JSON::XS\s0. | |
| 204 .SS "encode_json" | |
| 205 .IX Subsection "encode_json" | |
| 206 .Vb 1 | |
| 207 \& $json_text = encode_json $perl_scalar | |
| 208 .Ve | |
| 209 .PP | |
| 210 Converts the given Perl data structure to a \s-1UTF\-8\s0 encoded, binary string
. | |
| 211 .PP | |
| 212 This function call is functionally identical to: | |
| 213 .PP | |
| 214 .Vb 1 | |
| 215 \& $json_text = JSON::PP\->new\->utf8\->encode($perl_scalar) | |
| 216 .Ve | |
| 217 .SS "decode_json" | |
| 218 .IX Subsection "decode_json" | |
| 219 .Vb 1 | |
| 220 \& $perl_scalar = decode_json $json_text | |
| 221 .Ve | |
| 222 .PP | |
| 223 The opposite of \f(CW\*(C`encode_json\*(C'\fR: expects an \s-1UTF\-8\s0 (binary)
string and tries | |
| 224 to parse that as an \s-1UTF\-8\s0 encoded \s-1JSON\s0 text, returning the result
ing | |
| 225 reference. | |
| 226 .PP | |
| 227 This function call is functionally identical to: | |
| 228 .PP | |
| 229 .Vb 1 | |
| 230 \& $perl_scalar = JSON::PP\->new\->utf8\->decode($json_text) | |
| 231 .Ve | |
| 232 .SS "JSON::PP::is_bool" | |
| 233 .IX Subsection "JSON::PP::is_bool" | |
| 234 .Vb 1 | |
| 235 \& $is_boolean = JSON::PP::is_bool($scalar) | |
| 236 .Ve | |
| 237 .PP | |
| 238 Returns true if the passed scalar represents either JSON::PP::true or | |
| 239 JSON::PP::false, two constants that act like \f(CW1\fR and \f(CW0\fR respectivel
y | |
| 240 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. | |
| 241 .SS "JSON::PP::true" | |
| 242 .IX Subsection "JSON::PP::true" | |
| 243 Returns \s-1JSON\s0 true value which is blessed object. | |
| 244 It \f(CW\*(C`isa\*(C'\fR JSON::PP::Boolean object. | |
| 245 .SS "JSON::PP::false" | |
| 246 .IX Subsection "JSON::PP::false" | |
| 247 Returns \s-1JSON\s0 false value which is blessed object. | |
| 248 It \f(CW\*(C`isa\*(C'\fR JSON::PP::Boolean object. | |
| 249 .SS "JSON::PP::null" | |
| 250 .IX Subsection "JSON::PP::null" | |
| 251 Returns \f(CW\*(C`undef\*(C'\fR. | |
| 252 .PP | |
| 253 See \s-1MAPPING\s0, below, for more information on how \s-1JSON\s0 values are ma
pped to | |
| 254 Perl. | |
| 255 .SH "HOW DO I DECODE A DATA FROM OUTER AND ENCODE TO OUTER" | |
| 256 .IX Header "HOW DO I DECODE A DATA FROM OUTER AND ENCODE TO OUTER" | |
| 257 This section supposes that your perl version is 5.8 or later. | |
| 258 .PP | |
| 259 If you know a \s-1JSON\s0 text from an outer world \- a network, a file content,
and so on, | |
| 260 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 | |
| 261 with \f(CW\*(C`utf8\*(C'\fR enable. And the decoded result will contain \s-1UNIC
ODE\s0 characters. | |
| 262 .PP | |
| 263 .Vb 4 | |
| 264 \& # from network | |
| 265 \& my $json = JSON::PP\->new\->utf8; | |
| 266 \& my $json_text = CGI\->new\->param( \*(Aqjson_data\*(Aq ); | |
| 267 \& my $perl_scalar = $json\->decode( $json_text ); | |
| 268 \& | |
| 269 \& # from file content | |
| 270 \& local $/; | |
| 271 \& open( my $fh, \*(Aq<\*(Aq, \*(Aqjson.data\*(Aq ); | |
| 272 \& $json_text = <$fh>; | |
| 273 \& $perl_scalar = decode_json( $json_text ); | |
| 274 .Ve | |
| 275 .PP | |
| 276 If an outer data is not encoded in \s-1UTF\-8\s0, firstly you should \f(CW\*(C`d
ecode\*(C'\fR it. | |
| 277 .PP | |
| 278 .Vb 5 | |
| 279 \& use Encode; | |
| 280 \& local $/; | |
| 281 \& open( my $fh, \*(Aq<\*(Aq, \*(Aqjson.data\*(Aq ); | |
| 282 \& my $encoding = \*(Aqcp932\*(Aq; | |
| 283 \& my $unicode_json_text = decode( $encoding, <$fh> ); # UNICODE | |
| 284 \& | |
| 285 \& # or you can write the below code. | |
| 286 \& # | |
| 287 \& # open( my $fh, "<:encoding($encoding)", \*(Aqjson.data\*(Aq ); | |
| 288 \& # $unicode_json_text = <$fh>; | |
| 289 .Ve | |
| 290 .PP | |
| 291 In this case, \f(CW$unicode_json_text\fR is of course \s-1UNICODE\s0 string. | |
| 292 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. | |
| 293 Instead of them, you use \f(CW\*(C`JSON\*(C'\fR module object with \f(CW\*(C`utf
8\*(C'\fR disable. | |
| 294 .PP | |
| 295 .Vb 1 | |
| 296 \& $perl_scalar = $json\->utf8(0)\->decode( $unicode_json_text ); | |
| 297 .Ve | |
| 298 .PP | |
| 299 Or \f(CW\*(C`encode \*(Aqutf8\*(Aq\*(C'\fR and \f(CW\*(C`decode_json\*(C'\fR: | |
| 300 .PP | |
| 301 .Vb 2 | |
| 302 \& $perl_scalar = decode_json( encode( \*(Aqutf8\*(Aq, $unicode_json_text ) ); | |
| 303 \& # this way is not efficient. | |
| 304 .Ve | |
| 305 .PP | |
| 306 And now, you want to convert your \f(CW$perl_scalar\fR into \s-1JSON\s0 data and | |
| 307 send it to an outer world \- a network or a file content, and so on. | |
| 308 .PP | |
| 309 Your data usually contains \s-1UNICODE\s0 strings and you want the converted dat
a to be encoded | |
| 310 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. | |
| 311 .PP | |
| 312 .Vb 3 | |
| 313 \& print encode_json( $perl_scalar ); # to a network? file? or display? | |
| 314 \& # or | |
| 315 \& print $json\->utf8\->encode( $perl_scalar ); | |
| 316 .Ve | |
| 317 .PP | |
| 318 If \f(CW$perl_scalar\fR does not contain \s-1UNICODE\s0 but \f(CW$encoding\fR\-e
ncoded strings | |
| 319 for some reason, then its characters are regarded as \fBlatin1\fR for perl | |
| 320 (because it does not concern with your \f(CW$encoding\fR). | |
| 321 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. | |
| 322 Instead of them, you use \f(CW\*(C`JSON\*(C'\fR module object with \f(CW\*(C`utf
8\*(C'\fR disable. | |
| 323 Note that the resulted text is a \s-1UNICODE\s0 string but no problem to print i
t. | |
| 324 .PP | |
| 325 .Vb 4 | |
| 326 \& # $perl_scalar contains $encoding encoded string values | |
| 327 \& $unicode_json_text = $json\->utf8(0)\->encode( $perl_scalar ); | |
| 328 \& # $unicode_json_text consists of characters less than 0x100 | |
| 329 \& print $unicode_json_text; | |
| 330 .Ve | |
| 331 .PP | |
| 332 Or \f(CW\*(C`decode $encoding\*(C'\fR all string values and \f(CW\*(C`encode_jso
n\*(C'\fR: | |
| 333 .PP | |
| 334 .Vb 3 | |
| 335 \& $perl_scalar\->{ foo } = decode( $encoding, $perl_scalar\->{ foo } ); | |
| 336 \& # ... do it to each string values, then encode_json | |
| 337 \& $json_text = encode_json( $perl_scalar ); | |
| 338 .Ve | |
| 339 .PP | |
| 340 This method is a proper way but probably not efficient. | |
| 341 .PP | |
| 342 See to Encode, perluniintro. | |
| 343 .SH "METHODS" | |
| 344 .IX Header "METHODS" | |
| 345 Basically, check to \s-1JSON\s0 or \s-1JSON::XS\s0. | |
| 346 .SS "new" | |
| 347 .IX Subsection "new" | |
| 348 .Vb 1 | |
| 349 \& $json = JSON::PP\->new | |
| 350 .Ve | |
| 351 .PP | |
| 352 Returns a new \s-1JSON::PP\s0 object that can be used to de/encode \s-1JSON\s0 | |
| 353 strings. | |
| 354 .PP | |
| 355 All boolean flags described below are by default \fIdisabled\fR. | |
| 356 .PP | |
| 357 The mutators for flags all return the \s-1JSON\s0 object again and thus calls ca
n | |
| 358 be chained: | |
| 359 .PP | |
| 360 .Vb 2 | |
| 361 \& my $json = JSON::PP\->new\->utf8\->space_after\->encode({a => [1,2]}) | |
| 362 \& => {"a": [1, 2]} | |
| 363 .Ve | |
| 364 .SS "ascii" | |
| 365 .IX Subsection "ascii" | |
| 366 .Vb 1 | |
| 367 \& $json = $json\->ascii([$enable]) | |
| 368 \& | |
| 369 \& $enabled = $json\->get_ascii | |
| 370 .Ve | |
| 371 .PP | |
| 372 If \f(CW$enable\fR is true (or missing), then the encode method will not generat
e characters outside | |
| 373 the code range 0..127. Any Unicode characters outside that range will be escaped
using either | |
| 374 a single \euXXXX or a double \euHHHH\euLLLLL escape sequence, as per \s-1RFC4627
\s0. | |
| 375 (See to \*(L"OBJECT-ORIENTED \s-1INTERFACE\s0\*(R" in \s-1JSON::XS\s0). | |
| 376 .PP | |
| 377 In Perl 5.005, there is no character having high value (more than 255). | |
| 378 See to \*(L"\s-1UNICODE\s0 \s-1HANDLING\s0 \s-1ON\s0 \s-1PERLS\s0\*(R". | |
| 379 .PP | |
| 380 If \f(CW$enable\fR is false, then the encode method will not escape Unicode char
acters unless | |
| 381 required by the \s-1JSON\s0 syntax or other flags. This results in a faster and
more compact format. | |
| 382 .PP | |
| 383 .Vb 2 | |
| 384 \& JSON::PP\->new\->ascii(1)\->encode([chr 0x10401]) | |
| 385 \& => ["\eud801\eudc01"] | |
| 386 .Ve | |
| 387 .SS "latin1" | |
| 388 .IX Subsection "latin1" | |
| 389 .Vb 1 | |
| 390 \& $json = $json\->latin1([$enable]) | |
| 391 \& | |
| 392 \& $enabled = $json\->get_latin1 | |
| 393 .Ve | |
| 394 .PP | |
| 395 If \f(CW$enable\fR is true (or missing), then the encode method will encode the
resulting \s-1JSON\s0 | |
| 396 text as latin1 (or iso\-8859\-1), escaping any characters outside the code range
0..255. | |
| 397 .PP | |
| 398 If \f(CW$enable\fR is false, then the encode method will not escape Unicode char
acters | |
| 399 unless required by the \s-1JSON\s0 syntax or other flags. | |
| 400 .PP | |
| 401 .Vb 2 | |
| 402 \& JSON::XS\->new\->latin1\->encode (["\ex{89}\ex{abc}"] | |
| 403 \& => ["\ex{89}\e\eu0abc"] # (perl syntax, U+abc escaped, U+89 not) | |
| 404 .Ve | |
| 405 .PP | |
| 406 See to \*(L"\s-1UNICODE\s0 \s-1HANDLING\s0 \s-1ON\s0 \s-1PERLS\s0\*(R". | |
| 407 .SS "utf8" | |
| 408 .IX Subsection "utf8" | |
| 409 .Vb 1 | |
| 410 \& $json = $json\->utf8([$enable]) | |
| 411 \& | |
| 412 \& $enabled = $json\->get_utf8 | |
| 413 .Ve | |
| 414 .PP | |
| 415 If \f(CW$enable\fR is true (or missing), then the encode method will encode the
\s-1JSON\s0 result | |
| 416 into \s-1UTF\-8\s0, as required by many protocols, while the decode method expec
ts to be handled | |
| 417 an UTF\-8\-encoded string. Please note that UTF\-8\-encoded strings do not conta
in any | |
| 418 characters outside the range 0..255, they are thus useful for bytewise/binary I/
O. | |
| 419 .PP | |
| 420 (In Perl 5.005, any character outside the range 0..255 does not exist. | |
| 421 See to \*(L"\s-1UNICODE\s0 \s-1HANDLING\s0 \s-1ON\s0 \s-1PERLS\s0\*(R".) | |
| 422 .PP | |
| 423 In future versions, enabling this option might enable autodetection of the \s-1U
TF\-16\s0 and \s-1UTF\-32\s0 | |
| 424 encoding families, as described in \s-1RFC4627\s0. | |
| 425 .PP | |
| 426 If \f(CW$enable\fR is false, then the encode method will return the \s-1JSON\s0
string as a (non-encoded) | |
| 427 Unicode string, while decode expects thus a Unicode string. Any decoding or enco
ding | |
| 428 (e.g. to \s-1UTF\-8\s0 or \s-1UTF\-16\s0) needs to be done yourself, e.g. using
the Encode module. | |
| 429 .PP | |
| 430 Example, output UTF\-16BE\-encoded \s-1JSON:\s0 | |
| 431 .PP | |
| 432 .Vb 2 | |
| 433 \& use Encode; | |
| 434 \& $jsontext = encode "UTF\-16BE", JSON::PP\->new\->encode ($object); | |
| 435 .Ve | |
| 436 .PP | |
| 437 Example, decode UTF\-32LE\-encoded \s-1JSON:\s0 | |
| 438 .PP | |
| 439 .Vb 2 | |
| 440 \& use Encode; | |
| 441 \& $object = JSON::PP\->new\->decode (decode "UTF\-32LE", $jsontext); | |
| 442 .Ve | |
| 443 .SS "pretty" | |
| 444 .IX Subsection "pretty" | |
| 445 .Vb 1 | |
| 446 \& $json = $json\->pretty([$enable]) | |
| 447 .Ve | |
| 448 .PP | |
| 449 This enables (or disables) all of the \f(CW\*(C`indent\*(C'\fR, \f(CW\*(C`space_
before\*(C'\fR and | |
| 450 \&\f(CW\*(C`space_after\*(C'\fR flags in one call to generate the most readable | |
| 451 (or most compact) form possible. | |
| 452 .PP | |
| 453 Equivalent to: | |
| 454 .PP | |
| 455 .Vb 1 | |
| 456 \& $json\->indent\->space_before\->space_after | |
| 457 .Ve | |
| 458 .SS "indent" | |
| 459 .IX Subsection "indent" | |
| 460 .Vb 1 | |
| 461 \& $json = $json\->indent([$enable]) | |
| 462 \& | |
| 463 \& $enabled = $json\->get_indent | |
| 464 .Ve | |
| 465 .PP | |
| 466 The default indent space length is three. | |
| 467 You can use \f(CW\*(C`indent_length\*(C'\fR to change the length. | |
| 468 .SS "space_before" | |
| 469 .IX Subsection "space_before" | |
| 470 .Vb 1 | |
| 471 \& $json = $json\->space_before([$enable]) | |
| 472 \& | |
| 473 \& $enabled = $json\->get_space_before | |
| 474 .Ve | |
| 475 .PP | |
| 476 If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR metho
d will add an extra | |
| 477 optional space before the \f(CW\*(C`:\*(C'\fR separating keys from values in \s-
1JSON\s0 objects. | |
| 478 .PP | |
| 479 If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will not a
dd any extra | |
| 480 space at those places. | |
| 481 .PP | |
| 482 This setting has no effect when decoding \s-1JSON\s0 texts. | |
| 483 .PP | |
| 484 Example, space_before enabled, space_after and indent disabled: | |
| 485 .PP | |
| 486 .Vb 1 | |
| 487 \& {"key" :"value"} | |
| 488 .Ve | |
| 489 .SS "space_after" | |
| 490 .IX Subsection "space_after" | |
| 491 .Vb 1 | |
| 492 \& $json = $json\->space_after([$enable]) | |
| 493 \& | |
| 494 \& $enabled = $json\->get_space_after | |
| 495 .Ve | |
| 496 .PP | |
| 497 If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR metho
d will add an extra | |
| 498 optional space after the \f(CW\*(C`:\*(C'\fR separating keys from values in \s-1
JSON\s0 objects | |
| 499 and extra whitespace after the \f(CW\*(C`,\*(C'\fR separating key-value pairs an
d array | |
| 500 members. | |
| 501 .PP | |
| 502 If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will not a
dd any extra | |
| 503 space at those places. | |
| 504 .PP | |
| 505 This setting has no effect when decoding \s-1JSON\s0 texts. | |
| 506 .PP | |
| 507 Example, space_before and indent disabled, space_after enabled: | |
| 508 .PP | |
| 509 .Vb 1 | |
| 510 \& {"key": "value"} | |
| 511 .Ve | |
| 512 .SS "relaxed" | |
| 513 .IX Subsection "relaxed" | |
| 514 .Vb 1 | |
| 515 \& $json = $json\->relaxed([$enable]) | |
| 516 \& | |
| 517 \& $enabled = $json\->get_relaxed | |
| 518 .Ve | |
| 519 .PP | |
| 520 If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will acce
pt some | |
| 521 extensions to normal \s-1JSON\s0 syntax (see below). \f(CW\*(C`encode\*(C'\fR wi
ll not be | |
| 522 affected in anyway. \fIBe aware that this option makes you accept invalid | |
| 523 \&\s-1JSON\s0 texts as if they were valid!\fR. I suggest only to use this option
to | |
| 524 parse application-specific files written by humans (configuration files, | |
| 525 resource files etc.) | |
| 526 .PP | |
| 527 If \f(CW$enable\fR is false (the default), then \f(CW\*(C`decode\*(C'\fR will on
ly accept | |
| 528 valid \s-1JSON\s0 texts. | |
| 529 .PP | |
| 530 Currently accepted extensions are: | |
| 531 .IP "\(bu" 4 | |
| 532 list items can have an end-comma | |
| 533 .Sp | |
| 534 \&\s-1JSON\s0 \fIseparates\fR array elements and key-value pairs with commas. Th
is | |
| 535 can be annoying if you write \s-1JSON\s0 texts manually and want to be able to | |
| 536 quickly append elements, so this extension accepts comma at the end of | |
| 537 such items not just between them: | |
| 538 .Sp | |
| 539 .Vb 8 | |
| 540 \& [ | |
| 541 \& 1, | |
| 542 \& 2, <\- this comma not normally allowed | |
| 543 \& ] | |
| 544 \& { | |
| 545 \& "k1": "v1", | |
| 546 \& "k2": "v2", <\- this comma not normally allowed | |
| 547 \& } | |
| 548 .Ve | |
| 549 .IP "\(bu" 4 | |
| 550 shell-style '#'\-comments | |
| 551 .Sp | |
| 552 Whenever \s-1JSON\s0 allows whitespace, shell-style comments are additionally | |
| 553 allowed. They are terminated by the first carriage-return or line-feed | |
| 554 character, after which more white-space and comments are allowed. | |
| 555 .Sp | |
| 556 .Vb 4 | |
| 557 \& [ | |
| 558 \& 1, # this comment not allowed in JSON | |
| 559 \& # neither this one... | |
| 560 \& ] | |
| 561 .Ve | |
| 562 .SS "canonical" | |
| 563 .IX Subsection "canonical" | |
| 564 .Vb 1 | |
| 565 \& $json = $json\->canonical([$enable]) | |
| 566 \& | |
| 567 \& $enabled = $json\->get_canonical | |
| 568 .Ve | |
| 569 .PP | |
| 570 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 | |
| 571 by sorting their keys. This is adding a comparatively high overhead. | |
| 572 .PP | |
| 573 If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will outpu
t key-value | |
| 574 pairs in the order Perl stores them (which will likely change between runs | |
| 575 of the same script). | |
| 576 .PP | |
| 577 This option is useful if you want the same data structure to be encoded as | |
| 578 the same \s-1JSON\s0 text (given the same overall settings). If it is disabled, | |
| 579 the same hash might be encoded differently even if contains the same data, | |
| 580 as key-value pairs have no inherent ordering in Perl. | |
| 581 .PP | |
| 582 This setting has no effect when decoding \s-1JSON\s0 texts. | |
| 583 .PP | |
| 584 If you want your own sorting routine, you can give a code reference | |
| 585 or a subroutine name to \f(CW\*(C`sort_by\*(C'\fR. See to \f(CW\*(C`JSON::PP OWN
METHODS\*(C'\fR. | |
| 586 .SS "allow_nonref" | |
| 587 .IX Subsection "allow_nonref" | |
| 588 .Vb 1 | |
| 589 \& $json = $json\->allow_nonref([$enable]) | |
| 590 \& | |
| 591 \& $enabled = $json\->get_allow_nonref | |
| 592 .Ve | |
| 593 .PP | |
| 594 If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR metho
d can convert a | |
| 595 non-reference into its corresponding string, number or null \s-1JSON\s0 value, | |
| 596 which is an extension to \s-1RFC4627\s0. Likewise, \f(CW\*(C`decode\*(C'\fR will
accept those \s-1JSON\s0 | |
| 597 values instead of croaking. | |
| 598 .PP | |
| 599 If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will croak
if it isn't | |
| 600 passed an arrayref or hashref, as \s-1JSON\s0 texts must either be an object | |
| 601 or array. Likewise, \f(CW\*(C`decode\*(C'\fR will croak if given something that
is not a | |
| 602 \&\s-1JSON\s0 object or array. | |
| 603 .PP | |
| 604 .Vb 2 | |
| 605 \& JSON::PP\->new\->allow_nonref\->encode ("Hello, World!") | |
| 606 \& => "Hello, World!" | |
| 607 .Ve | |
| 608 .SS "allow_unknown" | |
| 609 .IX Subsection "allow_unknown" | |
| 610 .Vb 1 | |
| 611 \& $json = $json\->allow_unknown ([$enable]) | |
| 612 \& | |
| 613 \& $enabled = $json\->get_allow_unknown | |
| 614 .Ve | |
| 615 .PP | |
| 616 If \f(CW$enable\fR is true (or missing), then \*(L"encode\*(R" will *not* throw
an | |
| 617 exception when it encounters values it cannot represent in \s-1JSON\s0 (for | |
| 618 example, filehandles) but instead will encode a \s-1JSON\s0 \*(L"null\*(R" value
. | |
| 619 Note that blessed objects are not included here and are handled | |
| 620 separately by c<allow_nonref>. | |
| 621 .PP | |
| 622 If \f(CW$enable\fR is false (the default), then \*(L"encode\*(R" will throw an | |
| 623 exception when it encounters anything it cannot encode as \s-1JSON\s0. | |
| 624 .PP | |
| 625 This option does not affect \*(L"decode\*(R" in any way, and it is | |
| 626 recommended to leave it off unless you know your communications | |
| 627 partner. | |
| 628 .SS "allow_blessed" | |
| 629 .IX Subsection "allow_blessed" | |
| 630 .Vb 1 | |
| 631 \& $json = $json\->allow_blessed([$enable]) | |
| 632 \& | |
| 633 \& $enabled = $json\->get_allow_blessed | |
| 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 not | |
| 637 barf when it encounters a blessed reference. Instead, the value of the | |
| 638 \&\fBconvert_blessed\fR option will decide whether \f(CW\*(C`null\*(C'\fR (\f(CW
\*(C`convert_blessed\*(C'\fR | |
| 639 disabled or no \f(CW\*(C`TO_JSON\*(C'\fR method found) or a representation of th
e | |
| 640 object (\f(CW\*(C`convert_blessed\*(C'\fR enabled and \f(CW\*(C`TO_JSON\*(C'\fR
method found) is being | |
| 641 encoded. Has no effect on \f(CW\*(C`decode\*(C'\fR. | |
| 642 .PP | |
| 643 If \f(CW$enable\fR is false (the default), then \f(CW\*(C`encode\*(C'\fR will th
row an | |
| 644 exception when it encounters a blessed object. | |
| 645 .SS "convert_blessed" | |
| 646 .IX Subsection "convert_blessed" | |
| 647 .Vb 1 | |
| 648 \& $json = $json\->convert_blessed([$enable]) | |
| 649 \& | |
| 650 \& $enabled = $json\->get_convert_blessed | |
| 651 .Ve | |
| 652 .PP | |
| 653 If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`encode\*(C'\fR, upon enc
ountering a | |
| 654 blessed object, will check for the availability of the \f(CW\*(C`TO_JSON\*(C'\fR
method | |
| 655 on the object's class. If found, it will be called in scalar context | |
| 656 and the resulting scalar will be encoded instead of the object. If no | |
| 657 \&\f(CW\*(C`TO_JSON\*(C'\fR method is found, the value of \f(CW\*(C`allow_blesse
d\*(C'\fR will decide what | |
| 658 to do. | |
| 659 .PP | |
| 660 The \f(CW\*(C`TO_JSON\*(C'\fR method may safely call die if it wants. If \f(CW\*
(C`TO_JSON\*(C'\fR | |
| 661 returns other blessed objects, those will be handled in the same | |
| 662 way. \f(CW\*(C`TO_JSON\*(C'\fR must take care of not causing an endless recursio
n cycle | |
| 663 (== crash) in this case. The name of \f(CW\*(C`TO_JSON\*(C'\fR was chosen becaus
e other | |
| 664 methods called by the Perl core (== not by the user of the object) are | |
| 665 usually in upper case letters and to avoid collisions with the \f(CW\*(C`to_json
\*(C'\fR | |
| 666 function or method. | |
| 667 .PP | |
| 668 This setting does not yet influence \f(CW\*(C`decode\*(C'\fR in any way. | |
| 669 .PP | |
| 670 If \f(CW$enable\fR is false, then the \f(CW\*(C`allow_blessed\*(C'\fR setting wi
ll decide what | |
| 671 to do when a blessed object is found. | |
| 672 .SS "filter_json_object" | |
| 673 .IX Subsection "filter_json_object" | |
| 674 .Vb 1 | |
| 675 \& $json = $json\->filter_json_object([$coderef]) | |
| 676 .Ve | |
| 677 .PP | |
| 678 When \f(CW$coderef\fR is specified, it will be called from \f(CW\*(C`decode\*(C'
\fR each | |
| 679 time it decodes a \s-1JSON\s0 object. The only argument passed to the coderef | |
| 680 is a reference to the newly-created hash. If the code references returns | |
| 681 a single scalar (which need not be a reference), this value | |
| 682 (i.e. a copy of that scalar to avoid aliasing) is inserted into the | |
| 683 deserialised data structure. If it returns an empty list | |
| 684 (\s-1NOTE:\s0 \fInot\fR \f(CW\*(C`undef\*(C'\fR, which is a valid scalar), the o
riginal deserialised | |
| 685 hash will be inserted. This setting can slow down decoding considerably. | |
| 686 .PP | |
| 687 When \f(CW$coderef\fR is omitted or undefined, any existing callback will | |
| 688 be removed and \f(CW\*(C`decode\*(C'\fR will not change the deserialised hash in
any | |
| 689 way. | |
| 690 .PP | |
| 691 Example, convert all \s-1JSON\s0 objects into the integer 5: | |
| 692 .PP | |
| 693 .Vb 6 | |
| 694 \& my $js = JSON::PP\->new\->filter_json_object (sub { 5 }); | |
| 695 \& # returns [5] | |
| 696 \& $js\->decode (\*(Aq[{}]\*(Aq); # the given subroutine takes a hash referenc
e. | |
| 697 \& # throw an exception because allow_nonref is not enabled | |
| 698 \& # so a lone 5 is not allowed. | |
| 699 \& $js\->decode (\*(Aq{"a":1, "b":2}\*(Aq); | |
| 700 .Ve | |
| 701 .SS "filter_json_single_key_object" | |
| 702 .IX Subsection "filter_json_single_key_object" | |
| 703 .Vb 1 | |
| 704 \& $json = $json\->filter_json_single_key_object($key [=> $coderef]) | |
| 705 .Ve | |
| 706 .PP | |
| 707 Works remotely similar to \f(CW\*(C`filter_json_object\*(C'\fR, but is only call
ed for | |
| 708 \&\s-1JSON\s0 objects having a single key named \f(CW$key\fR. | |
| 709 .PP | |
| 710 This \f(CW$coderef\fR is called before the one specified via | |
| 711 \&\f(CW\*(C`filter_json_object\*(C'\fR, if any. It gets passed the single value
in the \s-1JSON\s0 | |
| 712 object. If it returns a single value, it will be inserted into the data | |
| 713 structure. If it returns nothing (not even \f(CW\*(C`undef\*(C'\fR but the empty
list), | |
| 714 the callback from \f(CW\*(C`filter_json_object\*(C'\fR will be called next, as i
f no | |
| 715 single-key callback were specified. | |
| 716 .PP | |
| 717 If \f(CW$coderef\fR is omitted or undefined, the corresponding callback will be | |
| 718 disabled. There can only ever be one callback for a given key. | |
| 719 .PP | |
| 720 As this callback gets called less often then the \f(CW\*(C`filter_json_object\*(
C'\fR | |
| 721 one, decoding speed will not usually suffer as much. Therefore, single-key | |
| 722 objects make excellent targets to serialise Perl objects into, especially | |
| 723 as single-key \s-1JSON\s0 objects are as close to the type-tagged value concept | |
| 724 as \s-1JSON\s0 gets (it's basically an \s-1ID/VALUE\s0 tuple). Of course, \s-1JS
ON\s0 does not | |
| 725 support this in any way, so you need to make sure your data never looks | |
| 726 like a serialised Perl hash. | |
| 727 .PP | |
| 728 Typical names for the single object key are \f(CW\*(C`_\|_class_whatever_\|_\*(C
'\fR, or | |
| 729 \&\f(CW\*(C`$_\|_dollars_are_rarely_used_\|_$\*(C'\fR or \f(CW\*(C`}ugly_brace_p
lacement\*(C'\fR, or even | |
| 730 things like \f(CW\*(C`_\|_class_md5sum(classname)_\|_\*(C'\fR, to reduce the ris
k of clashing | |
| 731 with real hashes. | |
| 732 .PP | |
| 733 Example, decode \s-1JSON\s0 objects of the form \f(CW\*(C`{ "_\|_widget_\|_" =>
<id> }\*(C'\fR | |
| 734 into the corresponding \f(CW$WIDGET{<id>}\fR object: | |
| 735 .PP | |
| 736 .Vb 7 | |
| 737 \& # return whatever is in $WIDGET{5}: | |
| 738 \& JSON::PP | |
| 739 \& \->new | |
| 740 \& \->filter_json_single_key_object (_\|_widget_\|_ => sub { | |
| 741 \& $WIDGET{ $_[0] } | |
| 742 \& }) | |
| 743 \& \->decode (\*(Aq{"_\|_widget_\|_": 5\*(Aq) | |
| 744 \& | |
| 745 \& # this can be used with a TO_JSON method in some "widget" class | |
| 746 \& # for serialisation to json: | |
| 747 \& sub WidgetBase::TO_JSON { | |
| 748 \& my ($self) = @_; | |
| 749 \& | |
| 750 \& unless ($self\->{id}) { | |
| 751 \& $self\->{id} = ..get..some..id..; | |
| 752 \& $WIDGET{$self\->{id}} = $self; | |
| 753 \& } | |
| 754 \& | |
| 755 \& { _\|_widget_\|_ => $self\->{id} } | |
| 756 \& } | |
| 757 .Ve | |
| 758 .SS "shrink" | |
| 759 .IX Subsection "shrink" | |
| 760 .Vb 1 | |
| 761 \& $json = $json\->shrink([$enable]) | |
| 762 \& | |
| 763 \& $enabled = $json\->get_shrink | |
| 764 .Ve | |
| 765 .PP | |
| 766 In \s-1JSON::XS\s0, this flag resizes strings generated by either | |
| 767 \&\f(CW\*(C`encode\*(C'\fR or \f(CW\*(C`decode\*(C'\fR to their minimum size pos
sible. | |
| 768 It will also try to downgrade any strings to octet-form if possible. | |
| 769 .PP | |
| 770 In \s-1JSON::PP\s0, it is noop about resizing strings but tries | |
| 771 \&\f(CW\*(C`utf8::downgrade\*(C'\fR to the returned string by \f(CW\*(C`encode\*
(C'\fR. | |
| 772 See to utf8. | |
| 773 .PP | |
| 774 See to \*(L"OBJECT-ORIENTED \s-1INTERFACE\s0\*(R" in \s-1JSON::XS\s0 | |
| 775 .SS "max_depth" | |
| 776 .IX Subsection "max_depth" | |
| 777 .Vb 1 | |
| 778 \& $json = $json\->max_depth([$maximum_nesting_depth]) | |
| 779 \& | |
| 780 \& $max_depth = $json\->get_max_depth | |
| 781 .Ve | |
| 782 .PP | |
| 783 Sets the maximum nesting level (default \f(CW512\fR) accepted while encoding | |
| 784 or decoding. If a higher nesting level is detected in \s-1JSON\s0 text or a Perl | |
| 785 data structure, then the encoder and decoder will stop and croak at that | |
| 786 point. | |
| 787 .PP | |
| 788 Nesting level is defined by number of hash\- or arrayrefs that the encoder | |
| 789 needs to traverse to reach a given point or the number of \f(CW\*(C`{\*(C'\fR or
\f(CW\*(C`[\*(C'\fR | |
| 790 characters without their matching closing parenthesis crossed to reach a | |
| 791 given character in a string. | |
| 792 .PP | |
| 793 If no argument is given, the highest possible setting will be used, which | |
| 794 is rarely useful. | |
| 795 .PP | |
| 796 See \*(L"\s-1SSECURITY\s0 \s-1CONSIDERATIONS\s0\*(R" in \s-1JSON::XS\s0 for more
info on why this is useful. | |
| 797 .PP | |
| 798 When a large value (100 or more) was set and it de/encodes a deep nested object/
text, | |
| 799 it may raise a warning 'Deep recursion on subroutine' at the perl runtime phase. | |
| 800 .SS "max_size" | |
| 801 .IX Subsection "max_size" | |
| 802 .Vb 1 | |
| 803 \& $json = $json\->max_size([$maximum_string_size]) | |
| 804 \& | |
| 805 \& $max_size = $json\->get_max_size | |
| 806 .Ve | |
| 807 .PP | |
| 808 Set the maximum length a \s-1JSON\s0 text may have (in bytes) where decoding is | |
| 809 being attempted. The default is \f(CW0\fR, meaning no limit. When \f(CW\*(C`deco
de\*(C'\fR | |
| 810 is called on a string that is longer then this many bytes, it will not | |
| 811 attempt to decode the string but throw an exception. This setting has no | |
| 812 effect on \f(CW\*(C`encode\*(C'\fR (yet). | |
| 813 .PP | |
| 814 If no argument is given, the limit check will be deactivated (same as when | |
| 815 \&\f(CW0\fR is specified). | |
| 816 .PP | |
| 817 See \*(L"\s-1SECURITY\s0 \s-1CONSIDERATIONS\s0\*(R" in \s-1JSON::XS\s0 for more
info on why this is useful. | |
| 818 .SS "encode" | |
| 819 .IX Subsection "encode" | |
| 820 .Vb 1 | |
| 821 \& $json_text = $json\->encode($perl_scalar) | |
| 822 .Ve | |
| 823 .PP | |
| 824 Converts the given Perl data structure (a simple scalar or a reference | |
| 825 to a hash or array) to its \s-1JSON\s0 representation. Simple scalars will be | |
| 826 converted into \s-1JSON\s0 string or number sequences, while references to array
s | |
| 827 become \s-1JSON\s0 arrays and references to hashes become \s-1JSON\s0 objects. U
ndefined | |
| 828 Perl values (e.g. \f(CW\*(C`undef\*(C'\fR) become \s-1JSON\s0 \f(CW\*(C`null\*(C
'\fR values. | |
| 829 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. | |
| 830 .SS "decode" | |
| 831 .IX Subsection "decode" | |
| 832 .Vb 1 | |
| 833 \& $perl_scalar = $json\->decode($json_text) | |
| 834 .Ve | |
| 835 .PP | |
| 836 The opposite of \f(CW\*(C`encode\*(C'\fR: expects a \s-1JSON\s0 text and tries t
o parse it, | |
| 837 returning the resulting simple scalar or reference. Croaks on error. | |
| 838 .PP | |
| 839 \&\s-1JSON\s0 numbers and strings become simple Perl scalars. \s-1JSON\s0 arrays
become | |
| 840 Perl arrayrefs and \s-1JSON\s0 objects become Perl hashrefs. \f(CW\*(C`true\*(C'
\fR becomes | |
| 841 \&\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 | |
| 842 \&\f(CW\*(C`null\*(C'\fR becomes \f(CW\*(C`undef\*(C'\fR. | |
| 843 .SS "decode_prefix" | |
| 844 .IX Subsection "decode_prefix" | |
| 845 .Vb 1 | |
| 846 \& ($perl_scalar, $characters) = $json\->decode_prefix($json_text) | |
| 847 .Ve | |
| 848 .PP | |
| 849 This works like the \f(CW\*(C`decode\*(C'\fR method, but instead of raising an e
xception | |
| 850 when there is trailing garbage after the first \s-1JSON\s0 object, it will | |
| 851 silently stop parsing there and return the number of characters consumed | |
| 852 so far. | |
| 853 .PP | |
| 854 .Vb 2 | |
| 855 \& JSON\->new\->decode_prefix ("[1] the tail") | |
| 856 \& => ([], 3) | |
| 857 .Ve | |
| 858 .SH "INCREMENTAL PARSING" | |
| 859 .IX Header "INCREMENTAL PARSING" | |
| 860 Most of this section are copied and modified from \*(L"\s-1INCREMENTAL\s0 \s-1PA
RSING\s0\*(R" in \s-1JSON::XS\s0. | |
| 861 .PP | |
| 862 In some cases, there is the need for incremental parsing of \s-1JSON\s0 texts. | |
| 863 This module does allow you to parse a \s-1JSON\s0 stream incrementally. | |
| 864 It does so by accumulating text until it has a full \s-1JSON\s0 object, which | |
| 865 it then can decode. This process is similar to using \f(CW\*(C`decode_prefix\*(C
'\fR | |
| 866 to see if a full \s-1JSON\s0 object is available, but is much more efficient | |
| 867 (and can be implemented with a minimum of method calls). | |
| 868 .PP | |
| 869 This module will only attempt to parse the \s-1JSON\s0 text once it is sure it | |
| 870 has enough text to get a decisive result, using a very simple but | |
| 871 truly incremental parser. This means that it sometimes won't stop as | |
| 872 early as the full parser, for example, it doesn't detect parenthesis | |
| 873 mismatches. The only thing it guarantees is that it starts decoding as | |
| 874 soon as a syntactically valid \s-1JSON\s0 text has been seen. This means you nee
d | |
| 875 to set resource limits (e.g. \f(CW\*(C`max_size\*(C'\fR) to ensure the parser wi
ll stop | |
| 876 parsing in the presence if syntax errors. | |
| 877 .PP | |
| 878 The following methods implement this incremental parser. | |
| 879 .SS "incr_parse" | |
| 880 .IX Subsection "incr_parse" | |
| 881 .Vb 1 | |
| 882 \& $json\->incr_parse( [$string] ) # void context | |
| 883 \& | |
| 884 \& $obj_or_undef = $json\->incr_parse( [$string] ) # scalar context | |
| 885 \& | |
| 886 \& @obj_or_empty = $json\->incr_parse( [$string] ) # list context | |
| 887 .Ve | |
| 888 .PP | |
| 889 This is the central parsing function. It can both append new text and | |
| 890 extract objects from the stream accumulated so far (both of these | |
| 891 functions are optional). | |
| 892 .PP | |
| 893 If \f(CW$string\fR is given, then this string is appended to the already | |
| 894 existing \s-1JSON\s0 fragment stored in the \f(CW$json\fR object. | |
| 895 .PP | |
| 896 After that, if the function is called in void context, it will simply | |
| 897 return without doing anything further. This can be used to add more text | |
| 898 in as many chunks as you want. | |
| 899 .PP | |
| 900 If the method is called in scalar context, then it will try to extract | |
| 901 exactly \fIone\fR \s-1JSON\s0 object. If that is successful, it will return this | |
| 902 object, otherwise it will return \f(CW\*(C`undef\*(C'\fR. If there is a parse er
ror, | |
| 903 this method will croak just as \f(CW\*(C`decode\*(C'\fR would do (one can then u
se | |
| 904 \&\f(CW\*(C`incr_skip\*(C'\fR to skip the erroneous part). This is the most comm
on way of | |
| 905 using the method. | |
| 906 .PP | |
| 907 And finally, in list context, it will try to extract as many objects | |
| 908 from the stream as it can find and return them, or the empty list | |
| 909 otherwise. For this to work, there must be no separators between the \s-1JSON\s0 | |
| 910 objects or arrays, instead they must be concatenated back-to-back. If | |
| 911 an error occurs, an exception will be raised as in the scalar context | |
| 912 case. Note that in this case, any previously-parsed \s-1JSON\s0 texts will be | |
| 913 lost. | |
| 914 .PP | |
| 915 Example: Parse some \s-1JSON\s0 arrays/objects in a given string and return them
. | |
| 916 .PP | |
| 917 .Vb 1 | |
| 918 \& my @objs = JSON\->new\->incr_parse ("[5][7][1,2]"); | |
| 919 .Ve | |
| 920 .SS "incr_text" | |
| 921 .IX Subsection "incr_text" | |
| 922 .Vb 1 | |
| 923 \& $lvalue_string = $json\->incr_text | |
| 924 .Ve | |
| 925 .PP | |
| 926 This method returns the currently stored \s-1JSON\s0 fragment as an lvalue, that | |
| 927 is, you can manipulate it. This \fIonly\fR works when a preceding call to | |
| 928 \&\f(CW\*(C`incr_parse\*(C'\fR in \fIscalar context\fR successfully returned an
object. Under | |
| 929 all other circumstances you must not call this function (I mean it. | |
| 930 although in simple tests it might actually work, it \fIwill\fR fail under | |
| 931 real world conditions). As a special exception, you can also call this | |
| 932 method before having parsed anything. | |
| 933 .PP | |
| 934 This function is useful in two cases: a) finding the trailing text after a | |
| 935 \&\s-1JSON\s0 object or b) parsing multiple \s-1JSON\s0 objects separated by non
-JSON text | |
| 936 (such as commas). | |
| 937 .PP | |
| 938 .Vb 1 | |
| 939 \& $json\->incr_text =~ s/\es*,\es*//; | |
| 940 .Ve | |
| 941 .PP | |
| 942 In Perl 5.005, \f(CW\*(C`lvalue\*(C'\fR attribute is not available. | |
| 943 You must write codes like the below: | |
| 944 .PP | |
| 945 .Vb 3 | |
| 946 \& $string = $json\->incr_text; | |
| 947 \& $string =~ s/\es*,\es*//; | |
| 948 \& $json\->incr_text( $string ); | |
| 949 .Ve | |
| 950 .SS "incr_skip" | |
| 951 .IX Subsection "incr_skip" | |
| 952 .Vb 1 | |
| 953 \& $json\->incr_skip | |
| 954 .Ve | |
| 955 .PP | |
| 956 This will reset the state of the incremental parser and will remove the | |
| 957 parsed text from the input buffer. This is useful after \f(CW\*(C`incr_parse\*(C
'\fR | |
| 958 died, in which case the input buffer and incremental parser state is left | |
| 959 unchanged, to skip the text parsed so far and to reset the parse state. | |
| 960 .SS "incr_reset" | |
| 961 .IX Subsection "incr_reset" | |
| 962 .Vb 1 | |
| 963 \& $json\->incr_reset | |
| 964 .Ve | |
| 965 .PP | |
| 966 This completely resets the incremental parser, that is, after this call, | |
| 967 it will be as if the parser had never parsed anything. | |
| 968 .PP | |
| 969 This is useful if you want to repeatedly parse \s-1JSON\s0 objects and want to | |
| 970 ignore any trailing data, which means you have to reset the parser after | |
| 971 each successful decode. | |
| 972 .PP | |
| 973 See to \*(L"\s-1INCREMENTAL\s0 \s-1PARSING\s0\*(R" in \s-1JSON::XS\s0 for exampl
es. | |
| 974 .SH "JSON::PP OWN METHODS" | |
| 975 .IX Header "JSON::PP OWN METHODS" | |
| 976 .SS "allow_singlequote" | |
| 977 .IX Subsection "allow_singlequote" | |
| 978 .Vb 1 | |
| 979 \& $json = $json\->allow_singlequote([$enable]) | |
| 980 .Ve | |
| 981 .PP | |
| 982 If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will acce
pt | |
| 983 \&\s-1JSON\s0 strings quoted by single quotations that are invalid \s-1JSON\s0 | |
| 984 format. | |
| 985 .PP | |
| 986 .Vb 3 | |
| 987 \& $json\->allow_singlequote\->decode({"foo":\*(Aqbar\*(Aq}); | |
| 988 \& $json\->allow_singlequote\->decode({\*(Aqfoo\*(Aq:"bar"}); | |
| 989 \& $json\->allow_singlequote\->decode({\*(Aqfoo\*(Aq:\*(Aqbar\*(Aq}); | |
| 990 .Ve | |
| 991 .PP | |
| 992 As same as the \f(CW\*(C`relaxed\*(C'\fR option, this option may be used to pars
e | |
| 993 application-specific files written by humans. | |
| 994 .SS "allow_barekey" | |
| 995 .IX Subsection "allow_barekey" | |
| 996 .Vb 1 | |
| 997 \& $json = $json\->allow_barekey([$enable]) | |
| 998 .Ve | |
| 999 .PP | |
| 1000 If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will acce
pt | |
| 1001 bare keys of \s-1JSON\s0 object that are invalid \s-1JSON\s0 format. | |
| 1002 .PP | |
| 1003 As same as the \f(CW\*(C`relaxed\*(C'\fR option, this option may be used to pars
e | |
| 1004 application-specific files written by humans. | |
| 1005 .PP | |
| 1006 .Vb 1 | |
| 1007 \& $json\->allow_barekey\->decode(\*(Aq{foo:"bar"}\*(Aq); | |
| 1008 .Ve | |
| 1009 .SS "allow_bignum" | |
| 1010 .IX Subsection "allow_bignum" | |
| 1011 .Vb 1 | |
| 1012 \& $json = $json\->allow_bignum([$enable]) | |
| 1013 .Ve | |
| 1014 .PP | |
| 1015 If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will conv
ert | |
| 1016 the big integer Perl cannot handle as integer into a Math::BigInt | |
| 1017 object and convert a floating number (any) into a Math::BigFloat. | |
| 1018 .PP | |
| 1019 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 | |
| 1020 objects into \s-1JSON\s0 numbers with \f(CW\*(C`allow_blessed\*(C'\fR enable. | |
| 1021 .PP | |
| 1022 .Vb 4 | |
| 1023 \& $json\->allow_nonref\->allow_blessed\->allow_bignum; | |
| 1024 \& $bigfloat = $json\->decode(\*(Aq2.000000000000000000000000001\*(Aq); | |
| 1025 \& print $json\->encode($bigfloat); | |
| 1026 \& # => 2.000000000000000000000000001 | |
| 1027 .Ve | |
| 1028 .PP | |
| 1029 See to \*(L"\s-1MAPPING\s0\*(R" in \s-1JSON::XS\s0 about the normal conversion o
f \s-1JSON\s0 number. | |
| 1030 .SS "loose" | |
| 1031 .IX Subsection "loose" | |
| 1032 .Vb 1 | |
| 1033 \& $json = $json\->loose([$enable]) | |
| 1034 .Ve | |
| 1035 .PP | |
| 1036 The unescaped [\ex00\-\ex1f\ex22\ex2f\ex5c] strings are invalid in \s-1JSON\s0 s
trings | |
| 1037 and the module doesn't allow to \f(CW\*(C`decode\*(C'\fR to these (except for \e
x2f). | |
| 1038 If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will acc
ept these | |
| 1039 unescaped strings. | |
| 1040 .PP | |
| 1041 .Vb 2 | |
| 1042 \& $json\->loose\->decode(qq|["abc | |
| 1043 \& def"]|); | |
| 1044 .Ve | |
| 1045 .PP | |
| 1046 See \*(L"\s-1SSECURITY\s0 \s-1CONSIDERATIONS\s0\*(R" in \s-1JSON::XS\s0. | |
| 1047 .SS "escape_slash" | |
| 1048 .IX Subsection "escape_slash" | |
| 1049 .Vb 1 | |
| 1050 \& $json = $json\->escape_slash([$enable]) | |
| 1051 .Ve | |
| 1052 .PP | |
| 1053 According to \s-1JSON\s0 Grammar, \fIslash\fR (U+002F) is escaped. But default | |
| 1054 \&\s-1JSON::PP\s0 (as same as \s-1JSON::XS\s0) encodes strings without escaping
slash. | |
| 1055 .PP | |
| 1056 If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`encode\*(C'\fR will esca
pe slashes. | |
| 1057 .SS "indent_length" | |
| 1058 .IX Subsection "indent_length" | |
| 1059 .Vb 1 | |
| 1060 \& $json = $json\->indent_length($length) | |
| 1061 .Ve | |
| 1062 .PP | |
| 1063 \&\s-1JSON::XS\s0 indent space length is 3 and cannot be changed. | |
| 1064 \&\s-1JSON::PP\s0 set the indent space length with the given \f(CW$length\fR. | |
| 1065 The default is 3. The acceptable range is 0 to 15. | |
| 1066 .SS "sort_by" | |
| 1067 .IX Subsection "sort_by" | |
| 1068 .Vb 2 | |
| 1069 \& $json = $json\->sort_by($function_name) | |
| 1070 \& $json = $json\->sort_by($subroutine_ref) | |
| 1071 .Ve | |
| 1072 .PP | |
| 1073 If \f(CW$function_name\fR or \f(CW$subroutine_ref\fR are set, its sort routine a
re used | |
| 1074 in encoding \s-1JSON\s0 objects. | |
| 1075 .PP | |
| 1076 .Vb 2 | |
| 1077 \& $js = $pc\->sort_by(sub { $JSON::PP::a cmp $JSON::PP::b })\->encode($obj); | |
| 1078 \& # is($js, q|{"a":1,"b":2,"c":3,"d":4,"e":5,"f":6,"g":7,"h":8,"i":9}|); | |
| 1079 \& | |
| 1080 \& $js = $pc\->sort_by(\*(Aqown_sort\*(Aq)\->encode($obj); | |
| 1081 \& # is($js, q|{"a":1,"b":2,"c":3,"d":4,"e":5,"f":6,"g":7,"h":8,"i":9}|); | |
| 1082 \& | |
| 1083 \& sub JSON::PP::own_sort { $JSON::PP::a cmp $JSON::PP::b } | |
| 1084 .Ve | |
| 1085 .PP | |
| 1086 As the sorting routine runs in the \s-1JSON::PP\s0 scope, the given | |
| 1087 subroutine name and the special variables \f(CW$a\fR, \f(CW$b\fR will begin | |
| 1088 \&'\s-1JSON::PP::\s0'. | |
| 1089 .PP | |
| 1090 If \f(CW$integer\fR is set, then the effect is same as \f(CW\*(C`canonical\*(C'\
fR on. | |
| 1091 .SH "INTERNAL" | |
| 1092 .IX Header "INTERNAL" | |
| 1093 For developers. | |
| 1094 .IP "PP_encode_box" 4 | |
| 1095 .IX Item "PP_encode_box" | |
| 1096 Returns | |
| 1097 .Sp | |
| 1098 .Vb 4 | |
| 1099 \& { | |
| 1100 \& depth => $depth, | |
| 1101 \& indent_count => $indent_count, | |
| 1102 \& } | |
| 1103 .Ve | |
| 1104 .IP "PP_decode_box" 4 | |
| 1105 .IX Item "PP_decode_box" | |
| 1106 Returns | |
| 1107 .Sp | |
| 1108 .Vb 9 | |
| 1109 \& { | |
| 1110 \& text => $text, | |
| 1111 \& at => $at, | |
| 1112 \& ch => $ch, | |
| 1113 \& len => $len, | |
| 1114 \& depth => $depth, | |
| 1115 \& encoding => $encoding, | |
| 1116 \& is_valid_utf8 => $is_valid_utf8, | |
| 1117 \& }; | |
| 1118 .Ve | |
| 1119 .SH "MAPPING" | |
| 1120 .IX Header "MAPPING" | |
| 1121 This section is copied from \s-1JSON::XS\s0 and modified to \f(CW\*(C`JSON::PP\*
(C'\fR. | |
| 1122 \&\s-1JSON::XS\s0 and \s-1JSON::PP\s0 mapping mechanisms are almost equivalent. | |
| 1123 .PP | |
| 1124 See to \*(L"\s-1MAPPING\s0\*(R" in \s-1JSON::XS\s0. | |
| 1125 .SS "\s-1JSON\s0 \-> \s-1PERL\s0" | |
| 1126 .IX Subsection "JSON -> PERL" | |
| 1127 .IP "object" 4 | |
| 1128 .IX Item "object" | |
| 1129 A \s-1JSON\s0 object becomes a reference to a hash in Perl. No ordering of objec
t | |
| 1130 keys is preserved (\s-1JSON\s0 does not preserver object key ordering itself). | |
| 1131 .IP "array" 4 | |
| 1132 .IX Item "array" | |
| 1133 A \s-1JSON\s0 array becomes a reference to an array in Perl. | |
| 1134 .IP "string" 4 | |
| 1135 .IX Item "string" | |
| 1136 A \s-1JSON\s0 string becomes a string scalar in Perl \- Unicode codepoints in \s
-1JSON\s0 | |
| 1137 are represented by the same codepoints in the Perl string, so no manual | |
| 1138 decoding is necessary. | |
| 1139 .IP "number" 4 | |
| 1140 .IX Item "number" | |
| 1141 A \s-1JSON\s0 number becomes either an integer, numeric (floating point) or | |
| 1142 string scalar in perl, depending on its range and any fractional parts. On | |
| 1143 the Perl level, there is no difference between those as Perl handles all | |
| 1144 the conversion details, but an integer may take slightly less memory and | |
| 1145 might represent more values exactly than floating point numbers. | |
| 1146 .Sp | |
| 1147 If the number consists of digits only, \f(CW\*(C`JSON\*(C'\fR will try to repres
ent | |
| 1148 it as an integer value. If that fails, it will try to represent it as | |
| 1149 a numeric (floating point) value if that is possible without loss of | |
| 1150 precision. Otherwise it will preserve the number as a string value (in | |
| 1151 which case you lose roundtripping ability, as the \s-1JSON\s0 number will be | |
| 1152 re-encoded to a \s-1JSON\s0 string). | |
| 1153 .Sp | |
| 1154 Numbers containing a fractional or exponential part will always be | |
| 1155 represented as numeric (floating point) values, possibly at a loss of | |
| 1156 precision (in which case you might lose perfect roundtripping ability, but | |
| 1157 the \s-1JSON\s0 number will still be re-encoded as a \s-1JSON\s0 number). | |
| 1158 .Sp | |
| 1159 Note that precision is not accuracy \- binary floating point values cannot | |
| 1160 represent most decimal fractions exactly, and when converting from and to | |
| 1161 floating point, \f(CW\*(C`JSON\*(C'\fR only guarantees precision up to but not i
ncluding | |
| 1162 the least significant bit. | |
| 1163 .Sp | |
| 1164 When \f(CW\*(C`allow_bignum\*(C'\fR is enable, the big integers | |
| 1165 and the numeric can be optionally converted into Math::BigInt and | |
| 1166 Math::BigFloat objects. | |
| 1167 .IP "true, false" 4 | |
| 1168 .IX Item "true, false" | |
| 1169 These \s-1JSON\s0 atoms become \f(CW\*(C`JSON::PP::true\*(C'\fR and \f(CW\*(C`JS
ON::PP::false\*(C'\fR, | |
| 1170 respectively. They are overloaded to act almost exactly like the numbers | |
| 1171 \&\f(CW1\fR and \f(CW0\fR. You can check whether a scalar is a \s-1JSON\s0 boole
an by using | |
| 1172 the \f(CW\*(C`JSON::is_bool\*(C'\fR function. | |
| 1173 .Sp | |
| 1174 .Vb 4 | |
| 1175 \& print JSON::PP::true . "\en"; | |
| 1176 \& => true | |
| 1177 \& print JSON::PP::true + 1; | |
| 1178 \& => 1 | |
| 1179 \& | |
| 1180 \& ok(JSON::true eq \*(Aq1\*(Aq); | |
| 1181 \& ok(JSON::true == 1); | |
| 1182 .Ve | |
| 1183 .Sp | |
| 1184 \&\f(CW\*(C`JSON\*(C'\fR will install these missing overloading features to the
backend modules. | |
| 1185 .IP "null" 4 | |
| 1186 .IX Item "null" | |
| 1187 A \s-1JSON\s0 null atom becomes \f(CW\*(C`undef\*(C'\fR in Perl. | |
| 1188 .Sp | |
| 1189 \&\f(CW\*(C`JSON::PP::null\*(C'\fR returns \f(CW\*(C`undef\*(C'\fR. | |
| 1190 .SS "\s-1PERL\s0 \-> \s-1JSON\s0" | |
| 1191 .IX Subsection "PERL -> JSON" | |
| 1192 The mapping from Perl to \s-1JSON\s0 is slightly more difficult, as Perl is a | |
| 1193 truly typeless language, so we can only guess which \s-1JSON\s0 type is meant by | |
| 1194 a Perl value. | |
| 1195 .IP "hash references" 4 | |
| 1196 .IX Item "hash references" | |
| 1197 Perl hash references become \s-1JSON\s0 objects. As there is no inherent orderin
g | |
| 1198 in hash keys (or \s-1JSON\s0 objects), they will usually be encoded in a | |
| 1199 pseudo-random order that can change between runs of the same program but | |
| 1200 stays generally the same within a single run of a program. \f(CW\*(C`JSON\*(C'\f
R | |
| 1201 optionally sort the hash keys (determined by the \fIcanonical\fR flag), so | |
| 1202 the same data structure will serialise to the same \s-1JSON\s0 text (given same | |
| 1203 settings and version of \s-1JSON::XS\s0), but this incurs a runtime overhead | |
| 1204 and is only rarely useful, e.g. when you want to compare some \s-1JSON\s0 text | |
| 1205 against another for equality. | |
| 1206 .IP "array references" 4 | |
| 1207 .IX Item "array references" | |
| 1208 Perl array references become \s-1JSON\s0 arrays. | |
| 1209 .IP "other references" 4 | |
| 1210 .IX Item "other references" | |
| 1211 Other unblessed references are generally not allowed and will cause an | |
| 1212 exception to be thrown, except for references to the integers \f(CW0\fR and | |
| 1213 \&\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 | |
| 1214 also use \f(CW\*(C`JSON::false\*(C'\fR and \f(CW\*(C`JSON::true\*(C'\fR to impro
ve readability. | |
| 1215 .Sp | |
| 1216 .Vb 1 | |
| 1217 \& to_json [\e0,JSON::PP::true] # yields [false,true] | |
| 1218 .Ve | |
| 1219 .IP "JSON::PP::true, JSON::PP::false, JSON::PP::null" 4 | |
| 1220 .IX Item "JSON::PP::true, JSON::PP::false, JSON::PP::null" | |
| 1221 These special values become \s-1JSON\s0 true and \s-1JSON\s0 false values, | |
| 1222 respectively. You can also use \f(CW\*(C`\e1\*(C'\fR and \f(CW\*(C`\e0\*(C'\fR d
irectly if you want. | |
| 1223 .Sp | |
| 1224 JSON::PP::null returns \f(CW\*(C`undef\*(C'\fR. | |
| 1225 .IP "blessed objects" 4 | |
| 1226 .IX Item "blessed objects" | |
| 1227 Blessed objects are not directly representable in \s-1JSON\s0. See the | |
| 1228 \&\f(CW\*(C`allow_blessed\*(C'\fR and \f(CW\*(C`convert_blessed\*(C'\fR methods
on various options on | |
| 1229 how to deal with this: basically, you can choose between throwing an | |
| 1230 exception, encoding the reference as if it weren't blessed, or provide | |
| 1231 your own serialiser method. | |
| 1232 .Sp | |
| 1233 See to convert_blessed. | |
| 1234 .IP "simple scalars" 4 | |
| 1235 .IX Item "simple scalars" | |
| 1236 Simple Perl scalars (any scalar that is not a reference) are the most | |
| 1237 difficult objects to encode: \s-1JSON::XS\s0 and \s-1JSON::PP\s0 will encode und
efined scalars as | |
| 1238 \&\s-1JSON\s0 \f(CW\*(C`null\*(C'\fR values, scalars that have last been used in
a string context | |
| 1239 before encoding as \s-1JSON\s0 strings, and anything else as number value: | |
| 1240 .Sp | |
| 1241 .Vb 4 | |
| 1242 \& # dump as number | |
| 1243 \& encode_json [2] # yields [2] | |
| 1244 \& encode_json [\-3.0e17] # yields [\-3e+17] | |
| 1245 \& my $value = 5; encode_json [$value] # yields [5] | |
| 1246 \& | |
| 1247 \& # used as string, so dump as string | |
| 1248 \& print $value; | |
| 1249 \& encode_json [$value] # yields ["5"] | |
| 1250 \& | |
| 1251 \& # undef becomes null | |
| 1252 \& encode_json [undef] # yields [null] | |
| 1253 .Ve | |
| 1254 .Sp | |
| 1255 You can force the type to be a string by stringifying it: | |
| 1256 .Sp | |
| 1257 .Vb 4 | |
| 1258 \& my $x = 3.1; # some variable containing a number | |
| 1259 \& "$x"; # stringified | |
| 1260 \& $x .= ""; # another, more awkward way to stringify | |
| 1261 \& print $x; # perl does it for you, too, quite often | |
| 1262 .Ve | |
| 1263 .Sp | |
| 1264 You can force the type to be a number by numifying it: | |
| 1265 .Sp | |
| 1266 .Vb 3 | |
| 1267 \& my $x = "3"; # some variable containing a string | |
| 1268 \& $x += 0; # numify it, ensuring it will be dumped as a number | |
| 1269 \& $x *= 1; # same thing, the choice is yours. | |
| 1270 .Ve | |
| 1271 .Sp | |
| 1272 You can not currently force the type in other, less obscure, ways. | |
| 1273 .Sp | |
| 1274 Note that numerical precision has the same meaning as under Perl (so | |
| 1275 binary to decimal conversion follows the same rules as in Perl, which | |
| 1276 can differ to other languages). Also, your perl interpreter might expose | |
| 1277 extensions to the floating point numbers of your platform, such as | |
| 1278 infinities or NaN's \- these cannot be represented in \s-1JSON\s0, and it is an | |
| 1279 error to pass those in. | |
| 1280 .IP "Big Number" 4 | |
| 1281 .IX Item "Big Number" | |
| 1282 When \f(CW\*(C`allow_bignum\*(C'\fR is enable, | |
| 1283 \&\f(CW\*(C`encode\*(C'\fR converts \f(CW\*(C`Math::BigInt\*(C'\fR objects and \
f(CW\*(C`Math::BigFloat\*(C'\fR | |
| 1284 objects into \s-1JSON\s0 numbers. | |
| 1285 .SH "UNICODE HANDLING ON PERLS" | |
| 1286 .IX Header "UNICODE HANDLING ON PERLS" | |
| 1287 If you do not know about Unicode on Perl well, | |
| 1288 please check \*(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. | |
| 1289 .SS "Perl 5.8 and later" | |
| 1290 .IX Subsection "Perl 5.8 and later" | |
| 1291 Perl can handle Unicode and the \s-1JSON::PP\s0 de/encode methods also work prop
erly. | |
| 1292 .PP | |
| 1293 .Vb 2 | |
| 1294 \& $json\->allow_nonref\->encode(chr hex 3042); | |
| 1295 \& $json\->allow_nonref\->encode(chr hex 12345); | |
| 1296 .Ve | |
| 1297 .PP | |
| 1298 Returns \f(CW"\eu3042"\fR and \f(CW"\eud808\eudf45"\fR respectively. | |
| 1299 .PP | |
| 1300 .Vb 2 | |
| 1301 \& $json\->allow_nonref\->decode(\*(Aq"\eu3042"\*(Aq); | |
| 1302 \& $json\->allow_nonref\->decode(\*(Aq"\eud808\eudf45"\*(Aq); | |
| 1303 .Ve | |
| 1304 .PP | |
| 1305 Returns \s-1UTF\-8\s0 encoded strings with \s-1UTF8\s0 flag, regarded as \f(CW\*
(C`U+3042\*(C'\fR and \f(CW\*(C`U+12345\*(C'\fR. | |
| 1306 .PP | |
| 1307 Note that the versions from Perl 5.8.0 to 5.8.2, Perl built-in \f(CW\*(C`join\*(
C'\fR was broken, | |
| 1308 so \s-1JSON::PP\s0 wraps the \f(CW\*(C`join\*(C'\fR with a subroutine. Thus \s-1
JSON::PP\s0 works slow in the versions. | |
| 1309 .SS "Perl 5.6" | |
| 1310 .IX Subsection "Perl 5.6" | |
| 1311 Perl can handle Unicode and the \s-1JSON::PP\s0 de/encode methods also work. | |
| 1312 .SS "Perl 5.005" | |
| 1313 .IX Subsection "Perl 5.005" | |
| 1314 Perl 5.005 is a byte semantics world \*(-- all strings are sequences of bytes. | |
| 1315 That means the unicode handling is not available. | |
| 1316 .PP | |
| 1317 In encoding, | |
| 1318 .PP | |
| 1319 .Vb 2 | |
| 1320 \& $json\->allow_nonref\->encode(chr hex 3042); # hex 3042 is 12354. | |
| 1321 \& $json\->allow_nonref\->encode(chr hex 12345); # hex 12345 is 74565. | |
| 1322 .Ve | |
| 1323 .PP | |
| 1324 Returns \f(CW\*(C`B\*(C'\fR and \f(CW\*(C`E\*(C'\fR, as \f(CW\*(C`chr\*(C'\fR ta
kes a value more than 255, it treats | |
| 1325 as \f(CW\*(C`$value % 256\*(C'\fR, so the above codes are equivalent to : | |
| 1326 .PP | |
| 1327 .Vb 2 | |
| 1328 \& $json\->allow_nonref\->encode(chr 66); | |
| 1329 \& $json\->allow_nonref\->encode(chr 69); | |
| 1330 .Ve | |
| 1331 .PP | |
| 1332 In decoding, | |
| 1333 .PP | |
| 1334 .Vb 1 | |
| 1335 \& $json\->decode(\*(Aq"\eu00e3\eu0081\eu0082"\*(Aq); | |
| 1336 .Ve | |
| 1337 .PP | |
| 1338 The returned is a byte sequence \f(CW\*(C`0xE3 0x81 0x82\*(C'\fR for \s-1UTF\-8\
s0 encoded | |
| 1339 japanese character (\f(CW\*(C`HIRAGANA LETTER A\*(C'\fR). | |
| 1340 And if it is represented in Unicode code point, \f(CW\*(C`U+3042\*(C'\fR. | |
| 1341 .PP | |
| 1342 Next, | |
| 1343 .PP | |
| 1344 .Vb 1 | |
| 1345 \& $json\->decode(\*(Aq"\eu3042"\*(Aq); | |
| 1346 .Ve | |
| 1347 .PP | |
| 1348 We ordinary expect the returned value is a Unicode character \f(CW\*(C`U+3042\*(
C'\fR. | |
| 1349 But here is 5.005 world. This is \f(CW\*(C`0xE3 0x81 0x82\*(C'\fR. | |
| 1350 .PP | |
| 1351 .Vb 1 | |
| 1352 \& $json\->decode(\*(Aq"\eud808\eudf45"\*(Aq); | |
| 1353 .Ve | |
| 1354 .PP | |
| 1355 This is not a character \f(CW\*(C`U+12345\*(C'\fR but bytes \- \f(CW\*(C`0xf0 0x
92 0x8d 0x85\*(C'\fR. | |
| 1356 .SH "TODO" | |
| 1357 .IX Header "TODO" | |
| 1358 .IP "speed" 4 | |
| 1359 .IX Item "speed" | |
| 1360 .PD 0 | |
| 1361 .IP "memory saving" 4 | |
| 1362 .IX Item "memory saving" | |
| 1363 .PD | |
| 1364 .SH "SEE ALSO" | |
| 1365 .IX Header "SEE ALSO" | |
| 1366 Most of the document are copied and modified from \s-1JSON::XS\s0 doc. | |
| 1367 .PP | |
| 1368 \&\s-1JSON::XS\s0 | |
| 1369 .PP | |
| 1370 \&\s-1RFC4627\s0 (<http://www.ietf.org/rfc/rfc4627.txt>) | |
| 1371 .SH "AUTHOR" | |
| 1372 .IX Header "AUTHOR" | |
| 1373 Makamaka Hannyaharamitu, <makamaka[at]cpan.org> | |
| 1374 .SH "COPYRIGHT AND LICENSE" | |
| 1375 .IX Header "COPYRIGHT AND LICENSE" | |
| 1376 Copyright 2007\-2012 by Makamaka Hannyaharamitu | |
| 1377 .PP | |
| 1378 This library is free software; you can redistribute it and/or modify | |
| 1379 it under the same terms as Perl itself. | |
| OLD | NEW |
|---|
Chromium Code Reviews
