| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "JSON::PP 3perl" |
| 58 |
.TH JSON::PP 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
JSON::PP \- JSON::XS compatible pure\-Perl module. |
| 65 |
.SH SYNOPSIS |
| 66 |
.IX Header "SYNOPSIS" |
| 67 |
.Vb 1 |
| 68 |
\& use JSON::PP; |
| 69 |
\& |
| 70 |
\& # exported functions, they croak on error |
| 71 |
\& # and expect/generate UTF\-8 |
| 72 |
\& |
| 73 |
\& $utf8_encoded_json_text = encode_json $perl_hash_or_arrayref; |
| 74 |
\& $perl_hash_or_arrayref = decode_json $utf8_encoded_json_text; |
| 75 |
\& |
| 76 |
\& # OO\-interface |
| 77 |
\& |
| 78 |
\& $json = JSON::PP\->new\->ascii\->pretty\->allow_nonref; |
| 79 |
\& |
| 80 |
\& $pretty_printed_json_text = $json\->encode( $perl_scalar ); |
| 81 |
\& $perl_scalar = $json\->decode( $json_text ); |
| 82 |
\& |
| 83 |
\& # Note that JSON version 2.0 and above will automatically use |
| 84 |
\& # JSON::XS or JSON::PP, so you should be able to just: |
| 85 |
\& |
| 86 |
\& use JSON; |
| 87 |
.Ve |
| 88 |
.SH DESCRIPTION |
| 89 |
.IX Header "DESCRIPTION" |
| 90 |
JSON::PP is a pure perl JSON decoder/encoder, and (almost) compatible to much |
| 91 |
faster JSON::XS written by Marc Lehmann in C. JSON::PP works as |
| 92 |
a fallback module when you use JSON module without having |
| 93 |
installed JSON::XS. |
| 94 |
.PP |
| 95 |
Because of this fallback feature of JSON.pm, JSON::PP tries not to |
| 96 |
be more JavaScript-friendly than JSON::XS (i.e. not to escape extra |
| 97 |
characters such as U+2028 and U+2029, etc), |
| 98 |
in order for you not to lose such JavaScript-friendliness silently |
| 99 |
when you use JSON.pm and install JSON::XS for speed or by accident. |
| 100 |
If you need JavaScript-friendly RFC7159\-compliant pure perl module, |
| 101 |
try JSON::Tiny, which is derived from Mojolicious web |
| 102 |
framework and is also smaller and faster than JSON::PP. |
| 103 |
.PP |
| 104 |
JSON::PP has been in the Perl core since Perl 5.14, mainly for |
| 105 |
CPAN toolchain modules to parse META.json. |
| 106 |
.SH "FUNCTIONAL INTERFACE" |
| 107 |
.IX Header "FUNCTIONAL INTERFACE" |
| 108 |
This section is taken from JSON::XS almost verbatim. \f(CW\*(C`encode_json\*(C'\fR |
| 109 |
and \f(CW\*(C`decode_json\*(C'\fR are exported by default. |
| 110 |
.SS encode_json |
| 111 |
.IX Subsection "encode_json" |
| 112 |
.Vb 1 |
| 113 |
\& $json_text = encode_json $perl_scalar |
| 114 |
.Ve |
| 115 |
.PP |
| 116 |
Converts the given Perl data structure to a UTF\-8 encoded, binary string |
| 117 |
(that is, the string contains octets only). Croaks on error. |
| 118 |
.PP |
| 119 |
This function call is functionally identical to: |
| 120 |
.PP |
| 121 |
.Vb 1 |
| 122 |
\& $json_text = JSON::PP\->new\->utf8\->encode($perl_scalar) |
| 123 |
.Ve |
| 124 |
.PP |
| 125 |
Except being faster. |
| 126 |
.SS decode_json |
| 127 |
.IX Subsection "decode_json" |
| 128 |
.Vb 1 |
| 129 |
\& $perl_scalar = decode_json $json_text |
| 130 |
.Ve |
| 131 |
.PP |
| 132 |
The opposite of \f(CW\*(C`encode_json\*(C'\fR: expects an UTF\-8 (binary) string and tries |
| 133 |
to parse that as an UTF\-8 encoded JSON text, returning the resulting |
| 134 |
reference. Croaks on error. |
| 135 |
.PP |
| 136 |
This function call is functionally identical to: |
| 137 |
.PP |
| 138 |
.Vb 1 |
| 139 |
\& $perl_scalar = JSON::PP\->new\->utf8\->decode($json_text) |
| 140 |
.Ve |
| 141 |
.PP |
| 142 |
Except being faster. |
| 143 |
.SS JSON::PP::is_bool |
| 144 |
.IX Subsection "JSON::PP::is_bool" |
| 145 |
.Vb 1 |
| 146 |
\& $is_boolean = JSON::PP::is_bool($scalar) |
| 147 |
.Ve |
| 148 |
.PP |
| 149 |
Returns true if the passed scalar represents either JSON::PP::true or |
| 150 |
JSON::PP::false, two constants that act like \f(CW1\fR and \f(CW0\fR respectively |
| 151 |
and are also used to represent JSON \f(CW\*(C`true\*(C'\fR and \f(CW\*(C`false\*(C'\fR in Perl strings. |
| 152 |
.PP |
| 153 |
On perl 5.36 and above, will also return true when given one of perl's |
| 154 |
standard boolean values, such as the result of a comparison. |
| 155 |
.PP |
| 156 |
See MAPPING, below, for more information on how JSON values are mapped to |
| 157 |
Perl. |
| 158 |
.SH "OBJECT-ORIENTED INTERFACE" |
| 159 |
.IX Header "OBJECT-ORIENTED INTERFACE" |
| 160 |
This section is also taken from JSON::XS. |
| 161 |
.PP |
| 162 |
The object oriented interface lets you configure your own encoding or |
| 163 |
decoding style, within the limits of supported formats. |
| 164 |
.SS new |
| 165 |
.IX Subsection "new" |
| 166 |
.Vb 1 |
| 167 |
\& $json = JSON::PP\->new |
| 168 |
.Ve |
| 169 |
.PP |
| 170 |
Creates a new JSON::PP object that can be used to de/encode JSON |
| 171 |
strings. All boolean flags described below are by default \fIdisabled\fR |
| 172 |
(with the exception of \f(CW\*(C`allow_nonref\*(C'\fR, which defaults to \fIenabled\fR since |
| 173 |
version \f(CW4.0\fR). |
| 174 |
.PP |
| 175 |
The mutators for flags all return the JSON::PP object again and thus calls can |
| 176 |
be chained: |
| 177 |
.PP |
| 178 |
.Vb 2 |
| 179 |
\& my $json = JSON::PP\->new\->utf8\->space_after\->encode({a => [1,2]}) |
| 180 |
\& => {"a": [1, 2]} |
| 181 |
.Ve |
| 182 |
.SS ascii |
| 183 |
.IX Subsection "ascii" |
| 184 |
.Vb 1 |
| 185 |
\& $json = $json\->ascii([$enable]) |
| 186 |
\& |
| 187 |
\& $enabled = $json\->get_ascii |
| 188 |
.Ve |
| 189 |
.PP |
| 190 |
If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will not |
| 191 |
generate characters outside the code range \f(CW0..127\fR (which is ASCII). Any |
| 192 |
Unicode characters outside that range will be escaped using either a |
| 193 |
single \euXXXX (BMP characters) or a double \euHHHH\euLLLLL escape sequence, |
| 194 |
as per RFC4627. The resulting encoded JSON text can be treated as a native |
| 195 |
Unicode string, an ascii-encoded, latin1\-encoded or UTF\-8 encoded string, |
| 196 |
or any other superset of ASCII. |
| 197 |
.PP |
| 198 |
If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will not escape Unicode |
| 199 |
characters unless required by the JSON syntax or other flags. This results |
| 200 |
in a faster and more compact format. |
| 201 |
.PP |
| 202 |
See also the section \fIENCODING/CODESET FLAG NOTES\fR later in this document. |
| 203 |
.PP |
| 204 |
The main use for this flag is to produce JSON texts that can be |
| 205 |
transmitted over a 7\-bit channel, as the encoded JSON texts will not |
| 206 |
contain any 8 bit characters. |
| 207 |
.PP |
| 208 |
.Vb 2 |
| 209 |
\& JSON::PP\->new\->ascii(1)\->encode([chr 0x10401]) |
| 210 |
\& => ["\eud801\eudc01"] |
| 211 |
.Ve |
| 212 |
.SS latin1 |
| 213 |
.IX Subsection "latin1" |
| 214 |
.Vb 1 |
| 215 |
\& $json = $json\->latin1([$enable]) |
| 216 |
\& |
| 217 |
\& $enabled = $json\->get_latin1 |
| 218 |
.Ve |
| 219 |
.PP |
| 220 |
If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will encode |
| 221 |
the resulting JSON text as latin1 (or iso\-8859\-1), escaping any characters |
| 222 |
outside the code range \f(CW0..255\fR. The resulting string can be treated as a |
| 223 |
latin1\-encoded JSON text or a native Unicode string. The \f(CW\*(C`decode\*(C'\fR method |
| 224 |
will not be affected in any way by this flag, as \f(CW\*(C`decode\*(C'\fR by default |
| 225 |
expects Unicode, which is a strict superset of latin1. |
| 226 |
.PP |
| 227 |
If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will not escape Unicode |
| 228 |
characters unless required by the JSON syntax or other flags. |
| 229 |
.PP |
| 230 |
See also the section \fIENCODING/CODESET FLAG NOTES\fR later in this document. |
| 231 |
.PP |
| 232 |
The main use for this flag is efficiently encoding binary data as JSON |
| 233 |
text, as most octets will not be escaped, resulting in a smaller encoded |
| 234 |
size. The disadvantage is that the resulting JSON text is encoded |
| 235 |
in latin1 (and must correctly be treated as such when storing and |
| 236 |
transferring), a rare encoding for JSON. It is therefore most useful when |
| 237 |
you want to store data structures known to contain binary data efficiently |
| 238 |
in files or databases, not when talking to other JSON encoders/decoders. |
| 239 |
.PP |
| 240 |
.Vb 2 |
| 241 |
\& JSON::PP\->new\->latin1\->encode (["\ex{89}\ex{abc}"] |
| 242 |
\& => ["\ex{89}\e\eu0abc"] # (perl syntax, U+abc escaped, U+89 not) |
| 243 |
.Ve |
| 244 |
.SS utf8 |
| 245 |
.IX Subsection "utf8" |
| 246 |
.Vb 1 |
| 247 |
\& $json = $json\->utf8([$enable]) |
| 248 |
\& |
| 249 |
\& $enabled = $json\->get_utf8 |
| 250 |
.Ve |
| 251 |
.PP |
| 252 |
If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will encode |
| 253 |
the JSON result into UTF\-8, as required by many protocols, while the |
| 254 |
\&\f(CW\*(C`decode\*(C'\fR method expects to be handled an UTF\-8\-encoded string. Please |
| 255 |
note that UTF\-8\-encoded strings do not contain any characters outside the |
| 256 |
range \f(CW0..255\fR, they are thus useful for bytewise/binary I/O. In future |
| 257 |
versions, enabling this option might enable autodetection of the UTF\-16 |
| 258 |
and UTF\-32 encoding families, as described in RFC4627. |
| 259 |
.PP |
| 260 |
If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will return the JSON |
| 261 |
string as a (non-encoded) Unicode string, while \f(CW\*(C`decode\*(C'\fR expects thus a |
| 262 |
Unicode string. Any decoding or encoding (e.g. to UTF\-8 or UTF\-16) needs |
| 263 |
to be done yourself, e.g. using the Encode module. |
| 264 |
.PP |
| 265 |
See also the section \fIENCODING/CODESET FLAG NOTES\fR later in this document. |
| 266 |
.PP |
| 267 |
Example, output UTF\-16BE\-encoded JSON: |
| 268 |
.PP |
| 269 |
.Vb 2 |
| 270 |
\& use Encode; |
| 271 |
\& $jsontext = encode "UTF\-16BE", JSON::PP\->new\->encode ($object); |
| 272 |
.Ve |
| 273 |
.PP |
| 274 |
Example, decode UTF\-32LE\-encoded JSON: |
| 275 |
.PP |
| 276 |
.Vb 2 |
| 277 |
\& use Encode; |
| 278 |
\& $object = JSON::PP\->new\->decode (decode "UTF\-32LE", $jsontext); |
| 279 |
.Ve |
| 280 |
.SS pretty |
| 281 |
.IX Subsection "pretty" |
| 282 |
.Vb 1 |
| 283 |
\& $json = $json\->pretty([$enable]) |
| 284 |
.Ve |
| 285 |
.PP |
| 286 |
This enables (or disables) all of the \f(CW\*(C`indent\*(C'\fR, \f(CW\*(C`space_before\*(C'\fR and |
| 287 |
\&\f(CW\*(C`space_after\*(C'\fR (and in the future possibly more) flags in one call to |
| 288 |
generate the most readable (or most compact) form possible. |
| 289 |
.SS indent |
| 290 |
.IX Subsection "indent" |
| 291 |
.Vb 1 |
| 292 |
\& $json = $json\->indent([$enable]) |
| 293 |
\& |
| 294 |
\& $enabled = $json\->get_indent |
| 295 |
.Ve |
| 296 |
.PP |
| 297 |
If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will use a multiline |
| 298 |
format as output, putting every array member or object/hash key-value pair |
| 299 |
into its own line, indenting them properly. |
| 300 |
.PP |
| 301 |
If \f(CW$enable\fR is false, no newlines or indenting will be produced, and the |
| 302 |
resulting JSON text is guaranteed not to contain any \f(CW\*(C`newlines\*(C'\fR. |
| 303 |
.PP |
| 304 |
This setting has no effect when decoding JSON texts. |
| 305 |
.PP |
| 306 |
The default indent space length is three. |
| 307 |
You can use \f(CW\*(C`indent_length\*(C'\fR to change the length. |
| 308 |
.SS space_before |
| 309 |
.IX Subsection "space_before" |
| 310 |
.Vb 1 |
| 311 |
\& $json = $json\->space_before([$enable]) |
| 312 |
\& |
| 313 |
\& $enabled = $json\->get_space_before |
| 314 |
.Ve |
| 315 |
.PP |
| 316 |
If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will add an extra |
| 317 |
optional space before the \f(CW\*(C`:\*(C'\fR separating keys from values in JSON objects. |
| 318 |
.PP |
| 319 |
If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will not add any extra |
| 320 |
space at those places. |
| 321 |
.PP |
| 322 |
This setting has no effect when decoding JSON texts. You will also |
| 323 |
most likely combine this setting with \f(CW\*(C`space_after\*(C'\fR. |
| 324 |
.PP |
| 325 |
Example, space_before enabled, space_after and indent disabled: |
| 326 |
.PP |
| 327 |
.Vb 1 |
| 328 |
\& {"key" :"value"} |
| 329 |
.Ve |
| 330 |
.SS space_after |
| 331 |
.IX Subsection "space_after" |
| 332 |
.Vb 1 |
| 333 |
\& $json = $json\->space_after([$enable]) |
| 334 |
\& |
| 335 |
\& $enabled = $json\->get_space_after |
| 336 |
.Ve |
| 337 |
.PP |
| 338 |
If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will add an extra |
| 339 |
optional space after the \f(CW\*(C`:\*(C'\fR separating keys from values in JSON objects |
| 340 |
and extra whitespace after the \f(CW\*(C`,\*(C'\fR separating key-value pairs and array |
| 341 |
members. |
| 342 |
.PP |
| 343 |
If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will not add any extra |
| 344 |
space at those places. |
| 345 |
.PP |
| 346 |
This setting has no effect when decoding JSON texts. |
| 347 |
.PP |
| 348 |
Example, space_before and indent disabled, space_after enabled: |
| 349 |
.PP |
| 350 |
.Vb 1 |
| 351 |
\& {"key": "value"} |
| 352 |
.Ve |
| 353 |
.SS relaxed |
| 354 |
.IX Subsection "relaxed" |
| 355 |
.Vb 1 |
| 356 |
\& $json = $json\->relaxed([$enable]) |
| 357 |
\& |
| 358 |
\& $enabled = $json\->get_relaxed |
| 359 |
.Ve |
| 360 |
.PP |
| 361 |
If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will accept some |
| 362 |
extensions to normal JSON syntax (see below). \f(CW\*(C`encode\*(C'\fR will not be |
| 363 |
affected in anyway. \fIBe aware that this option makes you accept invalid |
| 364 |
JSON texts as if they were valid!\fR. I suggest only to use this option to |
| 365 |
parse application-specific files written by humans (configuration files, |
| 366 |
resource files etc.) |
| 367 |
.PP |
| 368 |
If \f(CW$enable\fR is false (the default), then \f(CW\*(C`decode\*(C'\fR will only accept |
| 369 |
valid JSON texts. |
| 370 |
.PP |
| 371 |
Currently accepted extensions are: |
| 372 |
.IP \(bu 4 |
| 373 |
list items can have an end-comma |
| 374 |
.Sp |
| 375 |
JSON \fIseparates\fR array elements and key-value pairs with commas. This |
| 376 |
can be annoying if you write JSON texts manually and want to be able to |
| 377 |
quickly append elements, so this extension accepts comma at the end of |
| 378 |
such items not just between them: |
| 379 |
.Sp |
| 380 |
.Vb 8 |
| 381 |
\& [ |
| 382 |
\& 1, |
| 383 |
\& 2, <\- this comma not normally allowed |
| 384 |
\& ] |
| 385 |
\& { |
| 386 |
\& "k1": "v1", |
| 387 |
\& "k2": "v2", <\- this comma not normally allowed |
| 388 |
\& } |
| 389 |
.Ve |
| 390 |
.IP \(bu 4 |
| 391 |
shell-style '#'\-comments |
| 392 |
.Sp |
| 393 |
Whenever JSON allows whitespace, shell-style comments are additionally |
| 394 |
allowed. They are terminated by the first carriage-return or line-feed |
| 395 |
character, after which more white-space and comments are allowed. |
| 396 |
.Sp |
| 397 |
.Vb 4 |
| 398 |
\& [ |
| 399 |
\& 1, # this comment not allowed in JSON |
| 400 |
\& # neither this one... |
| 401 |
\& ] |
| 402 |
.Ve |
| 403 |
.IP \(bu 4 |
| 404 |
C\-style multiple-line '/* */'\-comments (JSON::PP only) |
| 405 |
.Sp |
| 406 |
Whenever JSON allows whitespace, C\-style multiple-line comments are additionally |
| 407 |
allowed. Everything between \f(CW\*(C`/*\*(C'\fR and \f(CW\*(C`*/\*(C'\fR is a comment, after which |
| 408 |
more white-space and comments are allowed. |
| 409 |
.Sp |
| 410 |
.Vb 4 |
| 411 |
\& [ |
| 412 |
\& 1, /* this comment not allowed in JSON */ |
| 413 |
\& /* neither this one... */ |
| 414 |
\& ] |
| 415 |
.Ve |
| 416 |
.IP \(bu 4 |
| 417 |
C++\-style one-line '//'\-comments (JSON::PP only) |
| 418 |
.Sp |
| 419 |
Whenever JSON allows whitespace, C++\-style one-line comments are additionally |
| 420 |
allowed. They are terminated by the first carriage-return or line-feed |
| 421 |
character, after which more white-space and comments are allowed. |
| 422 |
.Sp |
| 423 |
.Vb 4 |
| 424 |
\& [ |
| 425 |
\& 1, // this comment not allowed in JSON |
| 426 |
\& // neither this one... |
| 427 |
\& ] |
| 428 |
.Ve |
| 429 |
.IP \(bu 4 |
| 430 |
literal ASCII TAB characters in strings |
| 431 |
.Sp |
| 432 |
Literal ASCII TAB characters are now allowed in strings (and treated as |
| 433 |
\&\f(CW\*(C`\et\*(C'\fR). |
| 434 |
.Sp |
| 435 |
.Vb 4 |
| 436 |
\& [ |
| 437 |
\& "Hello\etWorld", |
| 438 |
\& "Hello<TAB>World", # literal <TAB> would not normally be allowed |
| 439 |
\& ] |
| 440 |
.Ve |
| 441 |
.SS canonical |
| 442 |
.IX Subsection "canonical" |
| 443 |
.Vb 1 |
| 444 |
\& $json = $json\->canonical([$enable]) |
| 445 |
\& |
| 446 |
\& $enabled = $json\->get_canonical |
| 447 |
.Ve |
| 448 |
.PP |
| 449 |
If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will output JSON objects |
| 450 |
by sorting their keys. This is adding a comparatively high overhead. |
| 451 |
.PP |
| 452 |
If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will output key-value |
| 453 |
pairs in the order Perl stores them (which will likely change between runs |
| 454 |
of the same script, and can change even within the same run from 5.18 |
| 455 |
onwards). |
| 456 |
.PP |
| 457 |
This option is useful if you want the same data structure to be encoded as |
| 458 |
the same JSON text (given the same overall settings). If it is disabled, |
| 459 |
the same hash might be encoded differently even if contains the same data, |
| 460 |
as key-value pairs have no inherent ordering in Perl. |
| 461 |
.PP |
| 462 |
This setting has no effect when decoding JSON texts. |
| 463 |
.PP |
| 464 |
This setting has currently no effect on tied hashes. |
| 465 |
.SS allow_nonref |
| 466 |
.IX Subsection "allow_nonref" |
| 467 |
.Vb 1 |
| 468 |
\& $json = $json\->allow_nonref([$enable]) |
| 469 |
\& |
| 470 |
\& $enabled = $json\->get_allow_nonref |
| 471 |
.Ve |
| 472 |
.PP |
| 473 |
Unlike other boolean options, this opotion is enabled by default beginning |
| 474 |
with version \f(CW4.0\fR. |
| 475 |
.PP |
| 476 |
If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method can convert a |
| 477 |
non-reference into its corresponding string, number or null JSON value, |
| 478 |
which is an extension to RFC4627. Likewise, \f(CW\*(C`decode\*(C'\fR will accept those JSON |
| 479 |
values instead of croaking. |
| 480 |
.PP |
| 481 |
If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will croak if it isn't |
| 482 |
passed an arrayref or hashref, as JSON texts must either be an object |
| 483 |
or array. Likewise, \f(CW\*(C`decode\*(C'\fR will croak if given something that is not a |
| 484 |
JSON object or array. |
| 485 |
.PP |
| 486 |
Example, encode a Perl scalar as JSON value without enabled \f(CW\*(C`allow_nonref\*(C'\fR, |
| 487 |
resulting in an error: |
| 488 |
.PP |
| 489 |
.Vb 2 |
| 490 |
\& JSON::PP\->new\->allow_nonref(0)\->encode ("Hello, World!") |
| 491 |
\& => hash\- or arrayref expected... |
| 492 |
.Ve |
| 493 |
.SS allow_unknown |
| 494 |
.IX Subsection "allow_unknown" |
| 495 |
.Vb 1 |
| 496 |
\& $json = $json\->allow_unknown([$enable]) |
| 497 |
\& |
| 498 |
\& $enabled = $json\->get_allow_unknown |
| 499 |
.Ve |
| 500 |
.PP |
| 501 |
If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`encode\*(C'\fR will \fInot\fR throw an |
| 502 |
exception when it encounters values it cannot represent in JSON (for |
| 503 |
example, filehandles) but instead will encode a JSON \f(CW\*(C`null\*(C'\fR value. Note |
| 504 |
that blessed objects are not included here and are handled separately by |
| 505 |
c<allow_blessed>. |
| 506 |
.PP |
| 507 |
If \f(CW$enable\fR is false (the default), then \f(CW\*(C`encode\*(C'\fR will throw an |
| 508 |
exception when it encounters anything it cannot encode as JSON. |
| 509 |
.PP |
| 510 |
This option does not affect \f(CW\*(C`decode\*(C'\fR in any way, and it is recommended to |
| 511 |
leave it off unless you know your communications partner. |
| 512 |
.SS allow_blessed |
| 513 |
.IX Subsection "allow_blessed" |
| 514 |
.Vb 1 |
| 515 |
\& $json = $json\->allow_blessed([$enable]) |
| 516 |
\& |
| 517 |
\& $enabled = $json\->get_allow_blessed |
| 518 |
.Ve |
| 519 |
.PP |
| 520 |
See "OBJECT SERIALISATION" for details. |
| 521 |
.PP |
| 522 |
If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will not |
| 523 |
barf when it encounters a blessed reference that it cannot convert |
| 524 |
otherwise. Instead, a JSON \f(CW\*(C`null\*(C'\fR value is encoded instead of the object. |
| 525 |
.PP |
| 526 |
If \f(CW$enable\fR is false (the default), then \f(CW\*(C`encode\*(C'\fR will throw an |
| 527 |
exception when it encounters a blessed object that it cannot convert |
| 528 |
otherwise. |
| 529 |
.PP |
| 530 |
This setting has no effect on \f(CW\*(C`decode\*(C'\fR. |
| 531 |
.SS convert_blessed |
| 532 |
.IX Subsection "convert_blessed" |
| 533 |
.Vb 1 |
| 534 |
\& $json = $json\->convert_blessed([$enable]) |
| 535 |
\& |
| 536 |
\& $enabled = $json\->get_convert_blessed |
| 537 |
.Ve |
| 538 |
.PP |
| 539 |
See "OBJECT SERIALISATION" for details. |
| 540 |
.PP |
| 541 |
If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`encode\*(C'\fR, upon encountering a |
| 542 |
blessed object, will check for the availability of the \f(CW\*(C`TO_JSON\*(C'\fR method |
| 543 |
on the object's class. If found, it will be called in scalar context and |
| 544 |
the resulting scalar will be encoded instead of the object. |
| 545 |
.PP |
| 546 |
The \f(CW\*(C`TO_JSON\*(C'\fR method may safely call die if it wants. If \f(CW\*(C`TO_JSON\*(C'\fR |
| 547 |
returns other blessed objects, those will be handled in the same |
| 548 |
way. \f(CW\*(C`TO_JSON\*(C'\fR must take care of not causing an endless recursion cycle |
| 549 |
(== crash) in this case. The name of \f(CW\*(C`TO_JSON\*(C'\fR was chosen because other |
| 550 |
methods called by the Perl core (== not by the user of the object) are |
| 551 |
usually in upper case letters and to avoid collisions with any \f(CW\*(C`to_json\*(C'\fR |
| 552 |
function or method. |
| 553 |
.PP |
| 554 |
If \f(CW$enable\fR is false (the default), then \f(CW\*(C`encode\*(C'\fR will not consider |
| 555 |
this type of conversion. |
| 556 |
.PP |
| 557 |
This setting has no effect on \f(CW\*(C`decode\*(C'\fR. |
| 558 |
.SS allow_tags |
| 559 |
.IX Subsection "allow_tags" |
| 560 |
.Vb 1 |
| 561 |
\& $json = $json\->allow_tags([$enable]) |
| 562 |
\& |
| 563 |
\& $enabled = $json\->get_allow_tags |
| 564 |
.Ve |
| 565 |
.PP |
| 566 |
See "OBJECT SERIALISATION" for details. |
| 567 |
.PP |
| 568 |
If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`encode\*(C'\fR, upon encountering a |
| 569 |
blessed object, will check for the availability of the \f(CW\*(C`FREEZE\*(C'\fR method on |
| 570 |
the object's class. If found, it will be used to serialise the object into |
| 571 |
a nonstandard tagged JSON value (that JSON decoders cannot decode). |
| 572 |
.PP |
| 573 |
It also causes \f(CW\*(C`decode\*(C'\fR to parse such tagged JSON values and deserialise |
| 574 |
them via a call to the \f(CW\*(C`THAW\*(C'\fR method. |
| 575 |
.PP |
| 576 |
If \f(CW$enable\fR is false (the default), then \f(CW\*(C`encode\*(C'\fR will not consider |
| 577 |
this type of conversion, and tagged JSON values will cause a parse error |
| 578 |
in \f(CW\*(C`decode\*(C'\fR, as if tags were not part of the grammar. |
| 579 |
.SS boolean_values |
| 580 |
.IX Subsection "boolean_values" |
| 581 |
.Vb 1 |
| 582 |
\& $json\->boolean_values([$false, $true]) |
| 583 |
\& |
| 584 |
\& ($false, $true) = $json\->get_boolean_values |
| 585 |
.Ve |
| 586 |
.PP |
| 587 |
By default, JSON booleans will be decoded as overloaded |
| 588 |
\&\f(CW$JSON::PP::false\fR and \f(CW$JSON::PP::true\fR objects. |
| 589 |
.PP |
| 590 |
With this method you can specify your own boolean values for decoding \- |
| 591 |
on decode, JSON \f(CW\*(C`false\*(C'\fR will be decoded as a copy of \f(CW$false\fR, and JSON |
| 592 |
\&\f(CW\*(C`true\*(C'\fR will be decoded as \f(CW$true\fR ("copy" here is the same thing as |
| 593 |
assigning a value to another variable, i.e. \f(CW\*(C`$copy = $false\*(C'\fR). |
| 594 |
.PP |
| 595 |
This is useful when you want to pass a decoded data structure directly |
| 596 |
to other serialisers like YAML, Data::MessagePack and so on. |
| 597 |
.PP |
| 598 |
Note that this works only when you \f(CW\*(C`decode\*(C'\fR. You can set incompatible |
| 599 |
boolean objects (like boolean), but when you \f(CW\*(C`encode\*(C'\fR a data structure |
| 600 |
with such boolean objects, you still need to enable \f(CW\*(C`convert_blessed\*(C'\fR |
| 601 |
(and add a \f(CW\*(C`TO_JSON\*(C'\fR method if necessary). |
| 602 |
.PP |
| 603 |
Calling this method without any arguments will reset the booleans |
| 604 |
to their default values. |
| 605 |
.PP |
| 606 |
\&\f(CW\*(C`get_boolean_values\*(C'\fR will return both \f(CW$false\fR and \f(CW$true\fR values, or |
| 607 |
the empty list when they are set to the default. |
| 608 |
.SS core_bools |
| 609 |
.IX Subsection "core_bools" |
| 610 |
.Vb 1 |
| 611 |
\& $json\->core_bools([$enable]); |
| 612 |
.Ve |
| 613 |
.PP |
| 614 |
If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR, will produce standard |
| 615 |
perl boolean values. Equivalent to calling: |
| 616 |
.PP |
| 617 |
.Vb 1 |
| 618 |
\& $json\->boolean_values(!!1, !!0) |
| 619 |
.Ve |
| 620 |
.PP |
| 621 |
\&\f(CW\*(C`get_core_bools\*(C'\fR will return true if this has been set. On perl 5.36, it will |
| 622 |
also return true if the boolean values have been set to perl's core booleans |
| 623 |
using the \f(CW\*(C`boolean_values\*(C'\fR method. |
| 624 |
.PP |
| 625 |
The methods \f(CW\*(C`unblessed_bool\*(C'\fR and \f(CW\*(C`get_unblessed_bool\*(C'\fR are provided as aliases |
| 626 |
for compatibility with Cpanel::JSON::XS. |
| 627 |
.SS filter_json_object |
| 628 |
.IX Subsection "filter_json_object" |
| 629 |
.Vb 1 |
| 630 |
\& $json = $json\->filter_json_object([$coderef]) |
| 631 |
.Ve |
| 632 |
.PP |
| 633 |
When \f(CW$coderef\fR is specified, it will be called from \f(CW\*(C`decode\*(C'\fR each |
| 634 |
time it decodes a JSON object. The only argument is a reference to |
| 635 |
the newly-created hash. If the code references returns a single scalar |
| 636 |
(which need not be a reference), this value (or rather a copy of it) is |
| 637 |
inserted into the deserialised data structure. If it returns an empty |
| 638 |
list (NOTE: \fInot\fR \f(CW\*(C`undef\*(C'\fR, which is a valid scalar), the original |
| 639 |
deserialised hash will be inserted. This setting can slow down decoding |
| 640 |
considerably. |
| 641 |
.PP |
| 642 |
When \f(CW$coderef\fR is omitted or undefined, any existing callback will |
| 643 |
be removed and \f(CW\*(C`decode\*(C'\fR will not change the deserialised hash in any |
| 644 |
way. |
| 645 |
.PP |
| 646 |
Example, convert all JSON objects into the integer 5: |
| 647 |
.PP |
| 648 |
.Vb 5 |
| 649 |
\& my $js = JSON::PP\->new\->filter_json_object(sub { 5 }); |
| 650 |
\& # returns [5] |
| 651 |
\& $js\->decode(\*(Aq[{}]\*(Aq); |
| 652 |
\& # returns 5 |
| 653 |
\& $js\->decode(\*(Aq{"a":1, "b":2}\*(Aq); |
| 654 |
.Ve |
| 655 |
.SS filter_json_single_key_object |
| 656 |
.IX Subsection "filter_json_single_key_object" |
| 657 |
.Vb 1 |
| 658 |
\& $json = $json\->filter_json_single_key_object($key [=> $coderef]) |
| 659 |
.Ve |
| 660 |
.PP |
| 661 |
Works remotely similar to \f(CW\*(C`filter_json_object\*(C'\fR, but is only called for |
| 662 |
JSON objects having a single key named \f(CW$key\fR. |
| 663 |
.PP |
| 664 |
This \f(CW$coderef\fR is called before the one specified via |
| 665 |
\&\f(CW\*(C`filter_json_object\*(C'\fR, if any. It gets passed the single value in the JSON |
| 666 |
object. If it returns a single value, it will be inserted into the data |
| 667 |
structure. If it returns nothing (not even \f(CW\*(C`undef\*(C'\fR but the empty list), |
| 668 |
the callback from \f(CW\*(C`filter_json_object\*(C'\fR will be called next, as if no |
| 669 |
single-key callback were specified. |
| 670 |
.PP |
| 671 |
If \f(CW$coderef\fR is omitted or undefined, the corresponding callback will be |
| 672 |
disabled. There can only ever be one callback for a given key. |
| 673 |
.PP |
| 674 |
As this callback gets called less often then the \f(CW\*(C`filter_json_object\*(C'\fR |
| 675 |
one, decoding speed will not usually suffer as much. Therefore, single-key |
| 676 |
objects make excellent targets to serialise Perl objects into, especially |
| 677 |
as single-key JSON objects are as close to the type-tagged value concept |
| 678 |
as JSON gets (it's basically an ID/VALUE tuple). Of course, JSON does not |
| 679 |
support this in any way, so you need to make sure your data never looks |
| 680 |
like a serialised Perl hash. |
| 681 |
.PP |
| 682 |
Typical names for the single object key are \f(CW\*(C`_\|_class_whatever_\|_\*(C'\fR, or |
| 683 |
\&\f(CW\*(C`$_\|_dollars_are_rarely_used_\|_$\*(C'\fR or \f(CW\*(C`}ugly_brace_placement\*(C'\fR, or even |
| 684 |
things like \f(CW\*(C`_\|_class_md5sum(classname)_\|_\*(C'\fR, to reduce the risk of clashing |
| 685 |
with real hashes. |
| 686 |
.PP |
| 687 |
Example, decode JSON objects of the form \f(CW\*(C`{ "_\|_widget_\|_" => <id> }\*(C'\fR |
| 688 |
into the corresponding \f(CW$WIDGET{<id>}\fR object: |
| 689 |
.PP |
| 690 |
.Vb 7 |
| 691 |
\& # return whatever is in $WIDGET{5}: |
| 692 |
\& JSON::PP |
| 693 |
\& \->new |
| 694 |
\& \->filter_json_single_key_object (_\|_widget_\|_ => sub { |
| 695 |
\& $WIDGET{ $_[0] } |
| 696 |
\& }) |
| 697 |
\& \->decode (\*(Aq{"_\|_widget_\|_": 5\*(Aq) |
| 698 |
\& |
| 699 |
\& # this can be used with a TO_JSON method in some "widget" class |
| 700 |
\& # for serialisation to json: |
| 701 |
\& sub WidgetBase::TO_JSON { |
| 702 |
\& my ($self) = @_; |
| 703 |
\& |
| 704 |
\& unless ($self\->{id}) { |
| 705 |
\& $self\->{id} = ..get..some..id..; |
| 706 |
\& $WIDGET{$self\->{id}} = $self; |
| 707 |
\& } |
| 708 |
\& |
| 709 |
\& { _\|_widget_\|_ => $self\->{id} } |
| 710 |
\& } |
| 711 |
.Ve |
| 712 |
.SS shrink |
| 713 |
.IX Subsection "shrink" |
| 714 |
.Vb 1 |
| 715 |
\& $json = $json\->shrink([$enable]) |
| 716 |
\& |
| 717 |
\& $enabled = $json\->get_shrink |
| 718 |
.Ve |
| 719 |
.PP |
| 720 |
If \f(CW$enable\fR is true (or missing), the string returned by \f(CW\*(C`encode\*(C'\fR will |
| 721 |
be shrunk (i.e. downgraded if possible). |
| 722 |
.PP |
| 723 |
The actual definition of what shrink does might change in future versions, |
| 724 |
but it will always try to save space at the expense of time. |
| 725 |
.PP |
| 726 |
If \f(CW$enable\fR is false, then JSON::PP does nothing. |
| 727 |
.SS max_depth |
| 728 |
.IX Subsection "max_depth" |
| 729 |
.Vb 1 |
| 730 |
\& $json = $json\->max_depth([$maximum_nesting_depth]) |
| 731 |
\& |
| 732 |
\& $max_depth = $json\->get_max_depth |
| 733 |
.Ve |
| 734 |
.PP |
| 735 |
Sets the maximum nesting level (default \f(CW512\fR) accepted while encoding |
| 736 |
or decoding. If a higher nesting level is detected in JSON text or a Perl |
| 737 |
data structure, then the encoder and decoder will stop and croak at that |
| 738 |
point. |
| 739 |
.PP |
| 740 |
Nesting level is defined by number of hash\- or arrayrefs that the encoder |
| 741 |
needs to traverse to reach a given point or the number of \f(CW\*(C`{\*(C'\fR or \f(CW\*(C`[\*(C'\fR |
| 742 |
characters without their matching closing parenthesis crossed to reach a |
| 743 |
given character in a string. |
| 744 |
.PP |
| 745 |
Setting the maximum depth to one disallows any nesting, so that ensures |
| 746 |
that the object is only a single hash/object or array. |
| 747 |
.PP |
| 748 |
If no argument is given, the highest possible setting will be used, which |
| 749 |
is rarely useful. |
| 750 |
.PP |
| 751 |
See "SECURITY CONSIDERATIONS" in JSON::XS for more info on why this is useful. |
| 752 |
.SS max_size |
| 753 |
.IX Subsection "max_size" |
| 754 |
.Vb 1 |
| 755 |
\& $json = $json\->max_size([$maximum_string_size]) |
| 756 |
\& |
| 757 |
\& $max_size = $json\->get_max_size |
| 758 |
.Ve |
| 759 |
.PP |
| 760 |
Set the maximum length a JSON text may have (in bytes) where decoding is |
| 761 |
being attempted. The default is \f(CW0\fR, meaning no limit. When \f(CW\*(C`decode\*(C'\fR |
| 762 |
is called on a string that is longer then this many bytes, it will not |
| 763 |
attempt to decode the string but throw an exception. This setting has no |
| 764 |
effect on \f(CW\*(C`encode\*(C'\fR (yet). |
| 765 |
.PP |
| 766 |
If no argument is given, the limit check will be deactivated (same as when |
| 767 |
\&\f(CW0\fR is specified). |
| 768 |
.PP |
| 769 |
See "SECURITY CONSIDERATIONS" in JSON::XS for more info on why this is useful. |
| 770 |
.SS encode |
| 771 |
.IX Subsection "encode" |
| 772 |
.Vb 1 |
| 773 |
\& $json_text = $json\->encode($perl_scalar) |
| 774 |
.Ve |
| 775 |
.PP |
| 776 |
Converts the given Perl value or data structure to its JSON |
| 777 |
representation. Croaks on error. |
| 778 |
.SS decode |
| 779 |
.IX Subsection "decode" |
| 780 |
.Vb 1 |
| 781 |
\& $perl_scalar = $json\->decode($json_text) |
| 782 |
.Ve |
| 783 |
.PP |
| 784 |
The opposite of \f(CW\*(C`encode\*(C'\fR: expects a JSON text and tries to parse it, |
| 785 |
returning the resulting simple scalar or reference. Croaks on error. |
| 786 |
.SS decode_prefix |
| 787 |
.IX Subsection "decode_prefix" |
| 788 |
.Vb 1 |
| 789 |
\& ($perl_scalar, $characters) = $json\->decode_prefix($json_text) |
| 790 |
.Ve |
| 791 |
.PP |
| 792 |
This works like the \f(CW\*(C`decode\*(C'\fR method, but instead of raising an exception |
| 793 |
when there is trailing garbage after the first JSON object, it will |
| 794 |
silently stop parsing there and return the number of characters consumed |
| 795 |
so far. |
| 796 |
.PP |
| 797 |
This is useful if your JSON texts are not delimited by an outer protocol |
| 798 |
and you need to know where the JSON text ends. |
| 799 |
.PP |
| 800 |
.Vb 2 |
| 801 |
\& JSON::PP\->new\->decode_prefix ("[1] the tail") |
| 802 |
\& => ([1], 3) |
| 803 |
.Ve |
| 804 |
.SH "FLAGS FOR JSON::PP ONLY" |
| 805 |
.IX Header "FLAGS FOR JSON::PP ONLY" |
| 806 |
The following flags and properties are for JSON::PP only. If you use |
| 807 |
any of these, you can't make your application run faster by replacing |
| 808 |
JSON::PP with JSON::XS. If you need these and also speed boost, |
| 809 |
you might want to try Cpanel::JSON::XS, a fork of JSON::XS by |
| 810 |
Reini Urban, which supports some of these (with a different set of |
| 811 |
incompatibilities). Most of these historical flags are only kept |
| 812 |
for backward compatibility, and should not be used in a new application. |
| 813 |
.SS allow_singlequote |
| 814 |
.IX Subsection "allow_singlequote" |
| 815 |
.Vb 2 |
| 816 |
\& $json = $json\->allow_singlequote([$enable]) |
| 817 |
\& $enabled = $json\->get_allow_singlequote |
| 818 |
.Ve |
| 819 |
.PP |
| 820 |
If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will accept |
| 821 |
invalid JSON texts that contain strings that begin and end with |
| 822 |
single quotation marks. \f(CW\*(C`encode\*(C'\fR will not be affected in any way. |
| 823 |
\&\fIBe aware that this option makes you accept invalid JSON texts |
| 824 |
as if they were valid!\fR. I suggest only to use this option to |
| 825 |
parse application-specific files written by humans (configuration |
| 826 |
files, resource files etc.) |
| 827 |
.PP |
| 828 |
If \f(CW$enable\fR is false (the default), then \f(CW\*(C`decode\*(C'\fR will only accept |
| 829 |
valid JSON texts. |
| 830 |
.PP |
| 831 |
.Vb 3 |
| 832 |
\& $json\->allow_singlequote\->decode(qq|{"foo":\*(Aqbar\*(Aq}|); |
| 833 |
\& $json\->allow_singlequote\->decode(qq|{\*(Aqfoo\*(Aq:"bar"}|); |
| 834 |
\& $json\->allow_singlequote\->decode(qq|{\*(Aqfoo\*(Aq:\*(Aqbar\*(Aq}|); |
| 835 |
.Ve |
| 836 |
.SS allow_barekey |
| 837 |
.IX Subsection "allow_barekey" |
| 838 |
.Vb 2 |
| 839 |
\& $json = $json\->allow_barekey([$enable]) |
| 840 |
\& $enabled = $json\->get_allow_barekey |
| 841 |
.Ve |
| 842 |
.PP |
| 843 |
If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will accept |
| 844 |
invalid JSON texts that contain JSON objects whose names don't |
| 845 |
begin and end with quotation marks. \f(CW\*(C`encode\*(C'\fR will not be affected |
| 846 |
in any way. \fIBe aware that this option makes you accept invalid JSON |
| 847 |
texts as if they were valid!\fR. I suggest only to use this option to |
| 848 |
parse application-specific files written by humans (configuration |
| 849 |
files, resource files etc.) |
| 850 |
.PP |
| 851 |
If \f(CW$enable\fR is false (the default), then \f(CW\*(C`decode\*(C'\fR will only accept |
| 852 |
valid JSON texts. |
| 853 |
.PP |
| 854 |
.Vb 1 |
| 855 |
\& $json\->allow_barekey\->decode(qq|{foo:"bar"}|); |
| 856 |
.Ve |
| 857 |
.SS allow_bignum |
| 858 |
.IX Subsection "allow_bignum" |
| 859 |
.Vb 2 |
| 860 |
\& $json = $json\->allow_bignum([$enable]) |
| 861 |
\& $enabled = $json\->get_allow_bignum |
| 862 |
.Ve |
| 863 |
.PP |
| 864 |
If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will convert |
| 865 |
big integers Perl cannot handle as integer into Math::BigInt |
| 866 |
objects and convert floating numbers into Math::BigFloat |
| 867 |
objects. \f(CW\*(C`encode\*(C'\fR will convert \f(CW\*(C`Math::BigInt\*(C'\fR and \f(CW\*(C`Math::BigFloat\*(C'\fR |
| 868 |
objects into JSON numbers. |
| 869 |
.PP |
| 870 |
.Vb 4 |
| 871 |
\& $json\->allow_nonref\->allow_bignum; |
| 872 |
\& $bigfloat = $json\->decode(\*(Aq2.000000000000000000000000001\*(Aq); |
| 873 |
\& print $json\->encode($bigfloat); |
| 874 |
\& # => 2.000000000000000000000000001 |
| 875 |
.Ve |
| 876 |
.PP |
| 877 |
See also MAPPING. |
| 878 |
.SS loose |
| 879 |
.IX Subsection "loose" |
| 880 |
.Vb 2 |
| 881 |
\& $json = $json\->loose([$enable]) |
| 882 |
\& $enabled = $json\->get_loose |
| 883 |
.Ve |
| 884 |
.PP |
| 885 |
If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will accept |
| 886 |
invalid JSON texts that contain unescaped [\ex00\-\ex1f\ex22\ex5c] |
| 887 |
characters. \f(CW\*(C`encode\*(C'\fR will not be affected in any way. |
| 888 |
\&\fIBe aware that this option makes you accept invalid JSON texts |
| 889 |
as if they were valid!\fR. I suggest only to use this option to |
| 890 |
parse application-specific files written by humans (configuration |
| 891 |
files, resource files etc.) |
| 892 |
.PP |
| 893 |
If \f(CW$enable\fR is false (the default), then \f(CW\*(C`decode\*(C'\fR will only accept |
| 894 |
valid JSON texts. |
| 895 |
.PP |
| 896 |
.Vb 2 |
| 897 |
\& $json\->loose\->decode(qq|["abc |
| 898 |
\& def"]|); |
| 899 |
.Ve |
| 900 |
.SS escape_slash |
| 901 |
.IX Subsection "escape_slash" |
| 902 |
.Vb 2 |
| 903 |
\& $json = $json\->escape_slash([$enable]) |
| 904 |
\& $enabled = $json\->get_escape_slash |
| 905 |
.Ve |
| 906 |
.PP |
| 907 |
If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`encode\*(C'\fR will explicitly |
| 908 |
escape \fIslash\fR (solidus; \f(CW\*(C`U+002F\*(C'\fR) characters to reduce the risk of |
| 909 |
XSS (cross site scripting) that may be caused by \f(CW\*(C`</script>\*(C'\fR |
| 910 |
in a JSON text, with the cost of bloating the size of JSON texts. |
| 911 |
.PP |
| 912 |
This option may be useful when you embed JSON in HTML, but embedding |
| 913 |
arbitrary JSON in HTML (by some HTML template toolkit or by string |
| 914 |
interpolation) is risky in general. You must escape necessary |
| 915 |
characters in correct order, depending on the context. |
| 916 |
.PP |
| 917 |
\&\f(CW\*(C`decode\*(C'\fR will not be affected in any way. |
| 918 |
.SS indent_length |
| 919 |
.IX Subsection "indent_length" |
| 920 |
.Vb 2 |
| 921 |
\& $json = $json\->indent_length($number_of_spaces) |
| 922 |
\& $length = $json\->get_indent_length |
| 923 |
.Ve |
| 924 |
.PP |
| 925 |
This option is only useful when you also enable \f(CW\*(C`indent\*(C'\fR or \f(CW\*(C`pretty\*(C'\fR. |
| 926 |
.PP |
| 927 |
JSON::XS indents with three spaces when you \f(CW\*(C`encode\*(C'\fR (if requested |
| 928 |
by \f(CW\*(C`indent\*(C'\fR or \f(CW\*(C`pretty\*(C'\fR), and the number cannot be changed. |
| 929 |
JSON::PP allows you to change/get the number of indent spaces with these |
| 930 |
mutator/accessor. The default number of spaces is three (the same as |
| 931 |
JSON::XS), and the acceptable range is from \f(CW0\fR (no indentation; |
| 932 |
it'd be better to disable indentation by \f(CWindent(0)\fR) to \f(CW15\fR. |
| 933 |
.SS sort_by |
| 934 |
.IX Subsection "sort_by" |
| 935 |
.Vb 2 |
| 936 |
\& $json = $json\->sort_by($code_ref) |
| 937 |
\& $json = $json\->sort_by($subroutine_name) |
| 938 |
.Ve |
| 939 |
.PP |
| 940 |
If you just want to sort keys (names) in JSON objects when you |
| 941 |
\&\f(CW\*(C`encode\*(C'\fR, enable \f(CW\*(C`canonical\*(C'\fR option (see above) that allows you to |
| 942 |
sort object keys alphabetically. |
| 943 |
.PP |
| 944 |
If you do need to sort non-alphabetically for whatever reasons, |
| 945 |
you can give a code reference (or a subroutine name) to \f(CW\*(C`sort_by\*(C'\fR, |
| 946 |
then the argument will be passed to Perl's \f(CW\*(C`sort\*(C'\fR built-in function. |
| 947 |
.PP |
| 948 |
As the sorting is done in the JSON::PP scope, you usually need to |
| 949 |
prepend \f(CW\*(C`JSON::PP::\*(C'\fR to the subroutine name, and the special variables |
| 950 |
\&\f(CW$a\fR and \f(CW$b\fR used in the subrontine used by \f(CW\*(C`sort\*(C'\fR function. |
| 951 |
.PP |
| 952 |
Example: |
| 953 |
.PP |
| 954 |
.Vb 9 |
| 955 |
\& my %ORDER = (id => 1, class => 2, name => 3); |
| 956 |
\& $json\->sort_by(sub { |
| 957 |
\& ($ORDER{$JSON::PP::a} // 999) <=> ($ORDER{$JSON::PP::b} // 999) |
| 958 |
\& or $JSON::PP::a cmp $JSON::PP::b |
| 959 |
\& }); |
| 960 |
\& print $json\->encode([ |
| 961 |
\& {name => \*(AqCPAN\*(Aq, id => 1, href => \*(Aqhttp://cpan.org\*(Aq} |
| 962 |
\& ]); |
| 963 |
\& # [{"id":1,"name":"CPAN","href":"http://cpan.org"}] |
| 964 |
.Ve |
| 965 |
.PP |
| 966 |
Note that \f(CW\*(C`sort_by\*(C'\fR affects all the plain hashes in the data structure. |
| 967 |
If you need finer control, \f(CW\*(C`tie\*(C'\fR necessary hashes with a module that |
| 968 |
implements ordered hash (such as Hash::Ordered and Tie::IxHash). |
| 969 |
\&\f(CW\*(C`canonical\*(C'\fR and \f(CW\*(C`sort_by\*(C'\fR don't affect the key order in \f(CW\*(C`tie\*(C'\fRd |
| 970 |
hashes. |
| 971 |
.PP |
| 972 |
.Vb 5 |
| 973 |
\& use Hash::Ordered; |
| 974 |
\& tie my %hash, \*(AqHash::Ordered\*(Aq, |
| 975 |
\& (name => \*(AqCPAN\*(Aq, id => 1, href => \*(Aqhttp://cpan.org\*(Aq); |
| 976 |
\& print $json\->encode([\e%hash]); |
| 977 |
\& # [{"name":"CPAN","id":1,"href":"http://cpan.org"}] # order is kept |
| 978 |
.Ve |
| 979 |
.SH "INCREMENTAL PARSING" |
| 980 |
.IX Header "INCREMENTAL PARSING" |
| 981 |
This section is also taken from JSON::XS. |
| 982 |
.PP |
| 983 |
In some cases, there is the need for incremental parsing of JSON |
| 984 |
texts. While this module always has to keep both JSON text and resulting |
| 985 |
Perl data structure in memory at one time, it does allow you to parse a |
| 986 |
JSON stream incrementally. It does so by accumulating text until it has |
| 987 |
a full JSON object, which it then can decode. This process is similar to |
| 988 |
using \f(CW\*(C`decode_prefix\*(C'\fR to see if a full JSON object is available, but |
| 989 |
is much more efficient (and can be implemented with a minimum of method |
| 990 |
calls). |
| 991 |
.PP |
| 992 |
JSON::PP will only attempt to parse the JSON text once it is sure it |
| 993 |
has enough text to get a decisive result, using a very simple but |
| 994 |
truly incremental parser. This means that it sometimes won't stop as |
| 995 |
early as the full parser, for example, it doesn't detect mismatched |
| 996 |
parentheses. The only thing it guarantees is that it starts decoding as |
| 997 |
soon as a syntactically valid JSON text has been seen. This means you need |
| 998 |
to set resource limits (e.g. \f(CW\*(C`max_size\*(C'\fR) to ensure the parser will stop |
| 999 |
parsing in the presence if syntax errors. |
| 1000 |
.PP |
| 1001 |
The following methods implement this incremental parser. |
| 1002 |
.SS incr_parse |
| 1003 |
.IX Subsection "incr_parse" |
| 1004 |
.Vb 1 |
| 1005 |
\& $json\->incr_parse( [$string] ) # void context |
| 1006 |
\& |
| 1007 |
\& $obj_or_undef = $json\->incr_parse( [$string] ) # scalar context |
| 1008 |
\& |
| 1009 |
\& @obj_or_empty = $json\->incr_parse( [$string] ) # list context |
| 1010 |
.Ve |
| 1011 |
.PP |
| 1012 |
This is the central parsing function. It can both append new text and |
| 1013 |
extract objects from the stream accumulated so far (both of these |
| 1014 |
functions are optional). |
| 1015 |
.PP |
| 1016 |
If \f(CW$string\fR is given, then this string is appended to the already |
| 1017 |
existing JSON fragment stored in the \f(CW$json\fR object. |
| 1018 |
.PP |
| 1019 |
After that, if the function is called in void context, it will simply |
| 1020 |
return without doing anything further. This can be used to add more text |
| 1021 |
in as many chunks as you want. |
| 1022 |
.PP |
| 1023 |
If the method is called in scalar context, then it will try to extract |
| 1024 |
exactly \fIone\fR JSON object. If that is successful, it will return this |
| 1025 |
object, otherwise it will return \f(CW\*(C`undef\*(C'\fR. If there is a parse error, |
| 1026 |
this method will croak just as \f(CW\*(C`decode\*(C'\fR would do (one can then use |
| 1027 |
\&\f(CW\*(C`incr_skip\*(C'\fR to skip the erroneous part). This is the most common way of |
| 1028 |
using the method. |
| 1029 |
.PP |
| 1030 |
And finally, in list context, it will try to extract as many objects |
| 1031 |
from the stream as it can find and return them, or the empty list |
| 1032 |
otherwise. For this to work, there must be no separators (other than |
| 1033 |
whitespace) between the JSON objects or arrays, instead they must be |
| 1034 |
concatenated back-to-back. If an error occurs, an exception will be |
| 1035 |
raised as in the scalar context case. Note that in this case, any |
| 1036 |
previously-parsed JSON texts will be lost. |
| 1037 |
.PP |
| 1038 |
Example: Parse some JSON arrays/objects in a given string and return |
| 1039 |
them. |
| 1040 |
.PP |
| 1041 |
.Vb 1 |
| 1042 |
\& my @objs = JSON::PP\->new\->incr_parse ("[5][7][1,2]"); |
| 1043 |
.Ve |
| 1044 |
.SS incr_text |
| 1045 |
.IX Subsection "incr_text" |
| 1046 |
.Vb 1 |
| 1047 |
\& $lvalue_string = $json\->incr_text |
| 1048 |
.Ve |
| 1049 |
.PP |
| 1050 |
This method returns the currently stored JSON fragment as an lvalue, that |
| 1051 |
is, you can manipulate it. This \fIonly\fR works when a preceding call to |
| 1052 |
\&\f(CW\*(C`incr_parse\*(C'\fR in \fIscalar context\fR successfully returned an object. Under |
| 1053 |
all other circumstances you must not call this function (I mean it. |
| 1054 |
although in simple tests it might actually work, it \fIwill\fR fail under |
| 1055 |
real world conditions). As a special exception, you can also call this |
| 1056 |
method before having parsed anything. |
| 1057 |
.PP |
| 1058 |
That means you can only use this function to look at or manipulate text |
| 1059 |
before or after complete JSON objects, not while the parser is in the |
| 1060 |
middle of parsing a JSON object. |
| 1061 |
.PP |
| 1062 |
This function is useful in two cases: a) finding the trailing text after a |
| 1063 |
JSON object or b) parsing multiple JSON objects separated by non-JSON text |
| 1064 |
(such as commas). |
| 1065 |
.SS incr_skip |
| 1066 |
.IX Subsection "incr_skip" |
| 1067 |
.Vb 1 |
| 1068 |
\& $json\->incr_skip |
| 1069 |
.Ve |
| 1070 |
.PP |
| 1071 |
This will reset the state of the incremental parser and will remove |
| 1072 |
the parsed text from the input buffer so far. This is useful after |
| 1073 |
\&\f(CW\*(C`incr_parse\*(C'\fR died, in which case the input buffer and incremental parser |
| 1074 |
state is left unchanged, to skip the text parsed so far and to reset the |
| 1075 |
parse state. |
| 1076 |
.PP |
| 1077 |
The difference to \f(CW\*(C`incr_reset\*(C'\fR is that only text until the parse error |
| 1078 |
occurred is removed. |
| 1079 |
.SS incr_reset |
| 1080 |
.IX Subsection "incr_reset" |
| 1081 |
.Vb 1 |
| 1082 |
\& $json\->incr_reset |
| 1083 |
.Ve |
| 1084 |
.PP |
| 1085 |
This completely resets the incremental parser, that is, after this call, |
| 1086 |
it will be as if the parser had never parsed anything. |
| 1087 |
.PP |
| 1088 |
This is useful if you want to repeatedly parse JSON objects and want to |
| 1089 |
ignore any trailing data, which means you have to reset the parser after |
| 1090 |
each successful decode. |
| 1091 |
.SH MAPPING |
| 1092 |
.IX Header "MAPPING" |
| 1093 |
Most of this section is also taken from JSON::XS. |
| 1094 |
.PP |
| 1095 |
This section describes how JSON::PP maps Perl values to JSON values and |
| 1096 |
vice versa. These mappings are designed to "do the right thing" in most |
| 1097 |
circumstances automatically, preserving round-tripping characteristics |
| 1098 |
(what you put in comes out as something equivalent). |
| 1099 |
.PP |
| 1100 |
For the more enlightened: note that in the following descriptions, |
| 1101 |
lowercase \fIperl\fR refers to the Perl interpreter, while uppercase \fIPerl\fR |
| 1102 |
refers to the abstract Perl language itself. |
| 1103 |
.SS "JSON \-> PERL" |
| 1104 |
.IX Subsection "JSON -> PERL" |
| 1105 |
.IP object 4 |
| 1106 |
.IX Item "object" |
| 1107 |
A JSON object becomes a reference to a hash in Perl. No ordering of object |
| 1108 |
keys is preserved (JSON does not preserve object key ordering itself). |
| 1109 |
.IP array 4 |
| 1110 |
.IX Item "array" |
| 1111 |
A JSON array becomes a reference to an array in Perl. |
| 1112 |
.IP string 4 |
| 1113 |
.IX Item "string" |
| 1114 |
A JSON string becomes a string scalar in Perl \- Unicode codepoints in JSON |
| 1115 |
are represented by the same codepoints in the Perl string, so no manual |
| 1116 |
decoding is necessary. |
| 1117 |
.IP number 4 |
| 1118 |
.IX Item "number" |
| 1119 |
A JSON number becomes either an integer, numeric (floating point) or |
| 1120 |
string scalar in perl, depending on its range and any fractional parts. On |
| 1121 |
the Perl level, there is no difference between those as Perl handles all |
| 1122 |
the conversion details, but an integer may take slightly less memory and |
| 1123 |
might represent more values exactly than floating point numbers. |
| 1124 |
.Sp |
| 1125 |
If the number consists of digits only, JSON::PP will try to represent |
| 1126 |
it as an integer value. If that fails, it will try to represent it as |
| 1127 |
a numeric (floating point) value if that is possible without loss of |
| 1128 |
precision. Otherwise it will preserve the number as a string value (in |
| 1129 |
which case you lose roundtripping ability, as the JSON number will be |
| 1130 |
re-encoded to a JSON string). |
| 1131 |
.Sp |
| 1132 |
Numbers containing a fractional or exponential part will always be |
| 1133 |
represented as numeric (floating point) values, possibly at a loss of |
| 1134 |
precision (in which case you might lose perfect roundtripping ability, but |
| 1135 |
the JSON number will still be re-encoded as a JSON number). |
| 1136 |
.Sp |
| 1137 |
Note that precision is not accuracy \- binary floating point values cannot |
| 1138 |
represent most decimal fractions exactly, and when converting from and to |
| 1139 |
floating point, JSON::PP only guarantees precision up to but not including |
| 1140 |
the least significant bit. |
| 1141 |
.Sp |
| 1142 |
When \f(CW\*(C`allow_bignum\*(C'\fR is enabled, big integer values and any numeric |
| 1143 |
values will be converted into Math::BigInt and Math::BigFloat |
| 1144 |
objects respectively, without becoming string scalars or losing |
| 1145 |
precision. |
| 1146 |
.IP "true, false" 4 |
| 1147 |
.IX Item "true, false" |
| 1148 |
These JSON atoms become \f(CW\*(C`JSON::PP::true\*(C'\fR and \f(CW\*(C`JSON::PP::false\*(C'\fR, |
| 1149 |
respectively. They are overloaded to act almost exactly like the numbers |
| 1150 |
\&\f(CW1\fR and \f(CW0\fR. You can check whether a scalar is a JSON boolean by using |
| 1151 |
the \f(CW\*(C`JSON::PP::is_bool\*(C'\fR function. |
| 1152 |
.IP null 4 |
| 1153 |
.IX Item "null" |
| 1154 |
A JSON null atom becomes \f(CW\*(C`undef\*(C'\fR in Perl. |
| 1155 |
.ie n .IP "shell-style comments (""# \fItext\fR"")" 4 |
| 1156 |
.el .IP "shell-style comments (\f(CW# \fR\f(CItext\fR\f(CW\fR)" 4 |
| 1157 |
.IX Item "shell-style comments (# text)" |
| 1158 |
As a nonstandard extension to the JSON syntax that is enabled by the |
| 1159 |
\&\f(CW\*(C`relaxed\*(C'\fR setting, shell-style comments are allowed. They can start |
| 1160 |
anywhere outside strings and go till the end of the line. |
| 1161 |
.ie n .IP "tagged values (""(\fItag\fR)\fIvalue\fR"")." 4 |
| 1162 |
.el .IP "tagged values (\f(CW(\fR\f(CItag\fR\f(CW)\fR\f(CIvalue\fR\f(CW\fR)." 4 |
| 1163 |
.IX Item "tagged values ((tag)value)." |
| 1164 |
Another nonstandard extension to the JSON syntax, enabled with the |
| 1165 |
\&\f(CW\*(C`allow_tags\*(C'\fR setting, are tagged values. In this implementation, the |
| 1166 |
\&\fItag\fR must be a perl package/class name encoded as a JSON string, and the |
| 1167 |
\&\fIvalue\fR must be a JSON array encoding optional constructor arguments. |
| 1168 |
.Sp |
| 1169 |
See "OBJECT SERIALISATION", below, for details. |
| 1170 |
.SS "PERL \-> JSON" |
| 1171 |
.IX Subsection "PERL -> JSON" |
| 1172 |
The mapping from Perl to JSON is slightly more difficult, as Perl is a |
| 1173 |
truly typeless language, so we can only guess which JSON type is meant by |
| 1174 |
a Perl value. |
| 1175 |
.IP "hash references" 4 |
| 1176 |
.IX Item "hash references" |
| 1177 |
Perl hash references become JSON objects. As there is no inherent |
| 1178 |
ordering in hash keys (or JSON objects), they will usually be encoded |
| 1179 |
in a pseudo-random order. JSON::PP can optionally sort the hash keys |
| 1180 |
(determined by the \fIcanonical\fR flag and/or \fIsort_by\fR property), so |
| 1181 |
the same data structure will serialise to the same JSON text (given |
| 1182 |
same settings and version of JSON::PP), but this incurs a runtime |
| 1183 |
overhead and is only rarely useful, e.g. when you want to compare some |
| 1184 |
JSON text against another for equality. |
| 1185 |
.IP "array references" 4 |
| 1186 |
.IX Item "array references" |
| 1187 |
Perl array references become JSON arrays. |
| 1188 |
.IP "other references" 4 |
| 1189 |
.IX Item "other references" |
| 1190 |
Other unblessed references are generally not allowed and will cause an |
| 1191 |
exception to be thrown, except for references to the integers \f(CW0\fR and |
| 1192 |
\&\f(CW1\fR, which get turned into \f(CW\*(C`false\*(C'\fR and \f(CW\*(C`true\*(C'\fR atoms in JSON. You can |
| 1193 |
also use \f(CW\*(C`JSON::PP::false\*(C'\fR and \f(CW\*(C`JSON::PP::true\*(C'\fR to improve |
| 1194 |
readability. |
| 1195 |
.Sp |
| 1196 |
.Vb 1 |
| 1197 |
\& to_json [\e0, JSON::PP::true] # yields [false,true] |
| 1198 |
.Ve |
| 1199 |
.IP "JSON::PP::true, JSON::PP::false" 4 |
| 1200 |
.IX Item "JSON::PP::true, JSON::PP::false" |
| 1201 |
These special values become JSON true and JSON false values, |
| 1202 |
respectively. You can also use \f(CW\*(C`\e1\*(C'\fR and \f(CW\*(C`\e0\*(C'\fR directly if you want. |
| 1203 |
.IP JSON::PP::null 4 |
| 1204 |
.IX Item "JSON::PP::null" |
| 1205 |
This special value becomes JSON null. |
| 1206 |
.IP "blessed objects" 4 |
| 1207 |
.IX Item "blessed objects" |
| 1208 |
Blessed objects are not directly representable in JSON, but \f(CW\*(C`JSON::PP\*(C'\fR |
| 1209 |
allows various ways of handling objects. See "OBJECT SERIALISATION", |
| 1210 |
below, for details. |
| 1211 |
.IP "simple scalars" 4 |
| 1212 |
.IX Item "simple scalars" |
| 1213 |
Simple Perl scalars (any scalar that is not a reference) are the most |
| 1214 |
difficult objects to encode: JSON::PP will encode undefined scalars as |
| 1215 |
JSON \f(CW\*(C`null\*(C'\fR values, scalars that have last been used in a string context |
| 1216 |
before encoding as JSON strings, and anything else as number value: |
| 1217 |
.Sp |
| 1218 |
.Vb 4 |
| 1219 |
\& # dump as number |
| 1220 |
\& encode_json [2] # yields [2] |
| 1221 |
\& encode_json [\-3.0e17] # yields [\-3e+17] |
| 1222 |
\& my $value = 5; encode_json [$value] # yields [5] |
| 1223 |
\& |
| 1224 |
\& # used as string, so dump as string |
| 1225 |
\& print $value; |
| 1226 |
\& encode_json [$value] # yields ["5"] |
| 1227 |
\& |
| 1228 |
\& # undef becomes null |
| 1229 |
\& encode_json [undef] # yields [null] |
| 1230 |
.Ve |
| 1231 |
.Sp |
| 1232 |
You can force the type to be a JSON string by stringifying it: |
| 1233 |
.Sp |
| 1234 |
.Vb 5 |
| 1235 |
\& my $x = 3.1; # some variable containing a number |
| 1236 |
\& "$x"; # stringified |
| 1237 |
\& $x .= ""; # another, more awkward way to stringify |
| 1238 |
\& print $x; # perl does it for you, too, quite often |
| 1239 |
\& # (but for older perls) |
| 1240 |
.Ve |
| 1241 |
.Sp |
| 1242 |
You can force the type to be a JSON number by numifying it: |
| 1243 |
.Sp |
| 1244 |
.Vb 3 |
| 1245 |
\& my $x = "3"; # some variable containing a string |
| 1246 |
\& $x += 0; # numify it, ensuring it will be dumped as a number |
| 1247 |
\& $x *= 1; # same thing, the choice is yours. |
| 1248 |
.Ve |
| 1249 |
.Sp |
| 1250 |
You can not currently force the type in other, less obscure, ways. |
| 1251 |
.Sp |
| 1252 |
Since version 2.91_01, JSON::PP uses a different number detection logic |
| 1253 |
that converts a scalar that is possible to turn into a number safely. |
| 1254 |
The new logic is slightly faster, and tends to help people who use older |
| 1255 |
perl or who want to encode complicated data structure. However, this may |
| 1256 |
results in a different JSON text from the one JSON::XS encodes (and |
| 1257 |
thus may break tests that compare entire JSON texts). If you do |
| 1258 |
need the previous behavior for compatibility or for finer control, |
| 1259 |
set PERL_JSON_PP_USE_B environmental variable to true before you |
| 1260 |
\&\f(CW\*(C`use\*(C'\fR JSON::PP (or JSON.pm). |
| 1261 |
.Sp |
| 1262 |
Note that numerical precision has the same meaning as under Perl (so |
| 1263 |
binary to decimal conversion follows the same rules as in Perl, which |
| 1264 |
can differ to other languages). Also, your perl interpreter might expose |
| 1265 |
extensions to the floating point numbers of your platform, such as |
| 1266 |
infinities or NaN's \- these cannot be represented in JSON, and it is an |
| 1267 |
error to pass those in. |
| 1268 |
.Sp |
| 1269 |
JSON::PP (and JSON::XS) trusts what you pass to \f(CW\*(C`encode\*(C'\fR method |
| 1270 |
(or \f(CW\*(C`encode_json\*(C'\fR function) is a clean, validated data structure with |
| 1271 |
values that can be represented as valid JSON values only, because it's |
| 1272 |
not from an external data source (as opposed to JSON texts you pass to |
| 1273 |
\&\f(CW\*(C`decode\*(C'\fR or \f(CW\*(C`decode_json\*(C'\fR, which JSON::PP considers tainted and |
| 1274 |
doesn't trust). As JSON::PP doesn't know exactly what you and consumers |
| 1275 |
of your JSON texts want the unexpected values to be (you may want to |
| 1276 |
convert them into null, or to stringify them with or without |
| 1277 |
normalisation (string representation of infinities/NaN may vary |
| 1278 |
depending on platforms), or to croak without conversion), you're advised |
| 1279 |
to do what you and your consumers need before you encode, and also not |
| 1280 |
to numify values that may start with values that look like a number |
| 1281 |
(including infinities/NaN), without validating. |
| 1282 |
.SS "OBJECT SERIALISATION" |
| 1283 |
.IX Subsection "OBJECT SERIALISATION" |
| 1284 |
As JSON cannot directly represent Perl objects, you have to choose between |
| 1285 |
a pure JSON representation (without the ability to deserialise the object |
| 1286 |
automatically again), and a nonstandard extension to the JSON syntax, |
| 1287 |
tagged values. |
| 1288 |
.PP |
| 1289 |
\fISERIALISATION\fR |
| 1290 |
.IX Subsection "SERIALISATION" |
| 1291 |
.PP |
| 1292 |
What happens when \f(CW\*(C`JSON::PP\*(C'\fR encounters a Perl object depends on the |
| 1293 |
\&\f(CW\*(C`allow_blessed\*(C'\fR, \f(CW\*(C`convert_blessed\*(C'\fR, \f(CW\*(C`allow_tags\*(C'\fR and \f(CW\*(C`allow_bignum\*(C'\fR |
| 1294 |
settings, which are used in this order: |
| 1295 |
.ie n .IP "1. ""allow_tags"" is enabled and the object has a ""FREEZE"" method." 4 |
| 1296 |
.el .IP "1. \f(CWallow_tags\fR is enabled and the object has a \f(CWFREEZE\fR method." 4 |
| 1297 |
.IX Item "1. allow_tags is enabled and the object has a FREEZE method." |
| 1298 |
In this case, \f(CW\*(C`JSON::PP\*(C'\fR creates a tagged JSON value, using a nonstandard |
| 1299 |
extension to the JSON syntax. |
| 1300 |
.Sp |
| 1301 |
This works by invoking the \f(CW\*(C`FREEZE\*(C'\fR method on the object, with the first |
| 1302 |
argument being the object to serialise, and the second argument being the |
| 1303 |
constant string \f(CW\*(C`JSON\*(C'\fR to distinguish it from other serialisers. |
| 1304 |
.Sp |
| 1305 |
The \f(CW\*(C`FREEZE\*(C'\fR method can return any number of values (i.e. zero or |
| 1306 |
more). These values and the paclkage/classname of the object will then be |
| 1307 |
encoded as a tagged JSON value in the following format: |
| 1308 |
.Sp |
| 1309 |
.Vb 1 |
| 1310 |
\& ("classname")[FREEZE return values...] |
| 1311 |
.Ve |
| 1312 |
.Sp |
| 1313 |
e.g.: |
| 1314 |
.Sp |
| 1315 |
.Vb 3 |
| 1316 |
\& ("URI")["http://www.google.com/"] |
| 1317 |
\& ("MyDate")[2013,10,29] |
| 1318 |
\& ("ImageData::JPEG")["Z3...VlCg=="] |
| 1319 |
.Ve |
| 1320 |
.Sp |
| 1321 |
For example, the hypothetical \f(CW\*(C`My::Object\*(C'\fR \f(CW\*(C`FREEZE\*(C'\fR method might use the |
| 1322 |
objects \f(CW\*(C`type\*(C'\fR and \f(CW\*(C`id\*(C'\fR members to encode the object: |
| 1323 |
.Sp |
| 1324 |
.Vb 2 |
| 1325 |
\& sub My::Object::FREEZE { |
| 1326 |
\& my ($self, $serialiser) = @_; |
| 1327 |
\& |
| 1328 |
\& ($self\->{type}, $self\->{id}) |
| 1329 |
\& } |
| 1330 |
.Ve |
| 1331 |
.ie n .IP "2. ""convert_blessed"" is enabled and the object has a ""TO_JSON"" method." 4 |
| 1332 |
.el .IP "2. \f(CWconvert_blessed\fR is enabled and the object has a \f(CWTO_JSON\fR method." 4 |
| 1333 |
.IX Item "2. convert_blessed is enabled and the object has a TO_JSON method." |
| 1334 |
In this case, the \f(CW\*(C`TO_JSON\*(C'\fR method of the object is invoked in scalar |
| 1335 |
context. It must return a single scalar that can be directly encoded into |
| 1336 |
JSON. This scalar replaces the object in the JSON text. |
| 1337 |
.Sp |
| 1338 |
For example, the following \f(CW\*(C`TO_JSON\*(C'\fR method will convert all URI |
| 1339 |
objects to JSON strings when serialised. The fact that these values |
| 1340 |
originally were URI objects is lost. |
| 1341 |
.Sp |
| 1342 |
.Vb 4 |
| 1343 |
\& sub URI::TO_JSON { |
| 1344 |
\& my ($uri) = @_; |
| 1345 |
\& $uri\->as_string |
| 1346 |
\& } |
| 1347 |
.Ve |
| 1348 |
.ie n .IP "3. ""allow_bignum"" is enabled and the object is a ""Math::BigInt"" or ""Math::BigFloat""." 4 |
| 1349 |
.el .IP "3. \f(CWallow_bignum\fR is enabled and the object is a \f(CWMath::BigInt\fR or \f(CWMath::BigFloat\fR." 4 |
| 1350 |
.IX Item "3. allow_bignum is enabled and the object is a Math::BigInt or Math::BigFloat." |
| 1351 |
The object will be serialised as a JSON number value. |
| 1352 |
.ie n .IP "4. ""allow_blessed"" is enabled." 4 |
| 1353 |
.el .IP "4. \f(CWallow_blessed\fR is enabled." 4 |
| 1354 |
.IX Item "4. allow_blessed is enabled." |
| 1355 |
The object will be serialised as a JSON null value. |
| 1356 |
.IP "5. none of the above" 4 |
| 1357 |
.IX Item "5. none of the above" |
| 1358 |
If none of the settings are enabled or the respective methods are missing, |
| 1359 |
\&\f(CW\*(C`JSON::PP\*(C'\fR throws an exception. |
| 1360 |
.PP |
| 1361 |
\fIDESERIALISATION\fR |
| 1362 |
.IX Subsection "DESERIALISATION" |
| 1363 |
.PP |
| 1364 |
For deserialisation there are only two cases to consider: either |
| 1365 |
nonstandard tagging was used, in which case \f(CW\*(C`allow_tags\*(C'\fR decides, |
| 1366 |
or objects cannot be automatically be deserialised, in which |
| 1367 |
case you can use postprocessing or the \f(CW\*(C`filter_json_object\*(C'\fR or |
| 1368 |
\&\f(CW\*(C`filter_json_single_key_object\*(C'\fR callbacks to get some real objects our of |
| 1369 |
your JSON. |
| 1370 |
.PP |
| 1371 |
This section only considers the tagged value case: a tagged JSON object |
| 1372 |
is encountered during decoding and \f(CW\*(C`allow_tags\*(C'\fR is disabled, a parse |
| 1373 |
error will result (as if tagged values were not part of the grammar). |
| 1374 |
.PP |
| 1375 |
If \f(CW\*(C`allow_tags\*(C'\fR is enabled, \f(CW\*(C`JSON::PP\*(C'\fR will look up the \f(CW\*(C`THAW\*(C'\fR method |
| 1376 |
of the package/classname used during serialisation (it will not attempt |
| 1377 |
to load the package as a Perl module). If there is no such method, the |
| 1378 |
decoding will fail with an error. |
| 1379 |
.PP |
| 1380 |
Otherwise, the \f(CW\*(C`THAW\*(C'\fR method is invoked with the classname as first |
| 1381 |
argument, the constant string \f(CW\*(C`JSON\*(C'\fR as second argument, and all the |
| 1382 |
values from the JSON array (the values originally returned by the |
| 1383 |
\&\f(CW\*(C`FREEZE\*(C'\fR method) as remaining arguments. |
| 1384 |
.PP |
| 1385 |
The method must then return the object. While technically you can return |
| 1386 |
any Perl scalar, you might have to enable the \f(CW\*(C`allow_nonref\*(C'\fR setting to |
| 1387 |
make that work in all cases, so better return an actual blessed reference. |
| 1388 |
.PP |
| 1389 |
As an example, let's implement a \f(CW\*(C`THAW\*(C'\fR function that regenerates the |
| 1390 |
\&\f(CW\*(C`My::Object\*(C'\fR from the \f(CW\*(C`FREEZE\*(C'\fR example earlier: |
| 1391 |
.PP |
| 1392 |
.Vb 2 |
| 1393 |
\& sub My::Object::THAW { |
| 1394 |
\& my ($class, $serialiser, $type, $id) = @_; |
| 1395 |
\& |
| 1396 |
\& $class\->new (type => $type, id => $id) |
| 1397 |
\& } |
| 1398 |
.Ve |
| 1399 |
.SH "ENCODING/CODESET FLAG NOTES" |
| 1400 |
.IX Header "ENCODING/CODESET FLAG NOTES" |
| 1401 |
This section is taken from JSON::XS. |
| 1402 |
.PP |
| 1403 |
The interested reader might have seen a number of flags that signify |
| 1404 |
encodings or codesets \- \f(CW\*(C`utf8\*(C'\fR, \f(CW\*(C`latin1\*(C'\fR and \f(CW\*(C`ascii\*(C'\fR. There seems to be |
| 1405 |
some confusion on what these do, so here is a short comparison: |
| 1406 |
.PP |
| 1407 |
\&\f(CW\*(C`utf8\*(C'\fR controls whether the JSON text created by \f(CW\*(C`encode\*(C'\fR (and expected |
| 1408 |
by \f(CW\*(C`decode\*(C'\fR) is UTF\-8 encoded or not, while \f(CW\*(C`latin1\*(C'\fR and \f(CW\*(C`ascii\*(C'\fR only |
| 1409 |
control whether \f(CW\*(C`encode\*(C'\fR escapes character values outside their respective |
| 1410 |
codeset range. Neither of these flags conflict with each other, although |
| 1411 |
some combinations make less sense than others. |
| 1412 |
.PP |
| 1413 |
Care has been taken to make all flags symmetrical with respect to |
| 1414 |
\&\f(CW\*(C`encode\*(C'\fR and \f(CW\*(C`decode\*(C'\fR, that is, texts encoded with any combination of |
| 1415 |
these flag values will be correctly decoded when the same flags are used |
| 1416 |
\&\- in general, if you use different flag settings while encoding vs. when |
| 1417 |
decoding you likely have a bug somewhere. |
| 1418 |
.PP |
| 1419 |
Below comes a verbose discussion of these flags. Note that a "codeset" is |
| 1420 |
simply an abstract set of character-codepoint pairs, while an encoding |
| 1421 |
takes those codepoint numbers and \fIencodes\fR them, in our case into |
| 1422 |
octets. Unicode is (among other things) a codeset, UTF\-8 is an encoding, |
| 1423 |
and ISO\-8859\-1 (= latin 1) and ASCII are both codesets \fIand\fR encodings at |
| 1424 |
the same time, which can be confusing. |
| 1425 |
.ie n .IP """utf8"" flag disabled" 4 |
| 1426 |
.el .IP "\f(CWutf8\fR flag disabled" 4 |
| 1427 |
.IX Item "utf8 flag disabled" |
| 1428 |
When \f(CW\*(C`utf8\*(C'\fR is disabled (the default), then \f(CW\*(C`encode\*(C'\fR/\f(CW\*(C`decode\*(C'\fR generate |
| 1429 |
and expect Unicode strings, that is, characters with high ordinal Unicode |
| 1430 |
values (> 255) will be encoded as such characters, and likewise such |
| 1431 |
characters are decoded as-is, no changes to them will be done, except |
| 1432 |
"(re\-)interpreting" them as Unicode codepoints or Unicode characters, |
| 1433 |
respectively (to Perl, these are the same thing in strings unless you do |
| 1434 |
funny/weird/dumb stuff). |
| 1435 |
.Sp |
| 1436 |
This is useful when you want to do the encoding yourself (e.g. when you |
| 1437 |
want to have UTF\-16 encoded JSON texts) or when some other layer does |
| 1438 |
the encoding for you (for example, when printing to a terminal using a |
| 1439 |
filehandle that transparently encodes to UTF\-8 you certainly do NOT want |
| 1440 |
to UTF\-8 encode your data first and have Perl encode it another time). |
| 1441 |
.ie n .IP """utf8"" flag enabled" 4 |
| 1442 |
.el .IP "\f(CWutf8\fR flag enabled" 4 |
| 1443 |
.IX Item "utf8 flag enabled" |
| 1444 |
If the \f(CW\*(C`utf8\*(C'\fR\-flag is enabled, \f(CW\*(C`encode\*(C'\fR/\f(CW\*(C`decode\*(C'\fR will encode all |
| 1445 |
characters using the corresponding UTF\-8 multi-byte sequence, and will |
| 1446 |
expect your input strings to be encoded as UTF\-8, that is, no "character" |
| 1447 |
of the input string must have any value > 255, as UTF\-8 does not allow |
| 1448 |
that. |
| 1449 |
.Sp |
| 1450 |
The \f(CW\*(C`utf8\*(C'\fR flag therefore switches between two modes: disabled means you |
| 1451 |
will get a Unicode string in Perl, enabled means you get an UTF\-8 encoded |
| 1452 |
octet/binary string in Perl. |
| 1453 |
.ie n .IP """latin1"" or ""ascii"" flags enabled" 4 |
| 1454 |
.el .IP "\f(CWlatin1\fR or \f(CWascii\fR flags enabled" 4 |
| 1455 |
.IX Item "latin1 or ascii flags enabled" |
| 1456 |
With \f(CW\*(C`latin1\*(C'\fR (or \f(CW\*(C`ascii\*(C'\fR) enabled, \f(CW\*(C`encode\*(C'\fR will escape characters |
| 1457 |
with ordinal values > 255 (> 127 with \f(CW\*(C`ascii\*(C'\fR) and encode the remaining |
| 1458 |
characters as specified by the \f(CW\*(C`utf8\*(C'\fR flag. |
| 1459 |
.Sp |
| 1460 |
If \f(CW\*(C`utf8\*(C'\fR is disabled, then the result is also correctly encoded in those |
| 1461 |
character sets (as both are proper subsets of Unicode, meaning that a |
| 1462 |
Unicode string with all character values < 256 is the same thing as a |
| 1463 |
ISO\-8859\-1 string, and a Unicode string with all character values < 128 is |
| 1464 |
the same thing as an ASCII string in Perl). |
| 1465 |
.Sp |
| 1466 |
If \f(CW\*(C`utf8\*(C'\fR is enabled, you still get a correct UTF\-8\-encoded string, |
| 1467 |
regardless of these flags, just some more characters will be escaped using |
| 1468 |
\&\f(CW\*(C`\euXXXX\*(C'\fR then before. |
| 1469 |
.Sp |
| 1470 |
Note that ISO\-8859\-1\-\fIencoded\fR strings are not compatible with UTF\-8 |
| 1471 |
encoding, while ASCII-encoded strings are. That is because the ISO\-8859\-1 |
| 1472 |
encoding is NOT a subset of UTF\-8 (despite the ISO\-8859\-1 \fIcodeset\fR being |
| 1473 |
a subset of Unicode), while ASCII is. |
| 1474 |
.Sp |
| 1475 |
Surprisingly, \f(CW\*(C`decode\*(C'\fR will ignore these flags and so treat all input |
| 1476 |
values as governed by the \f(CW\*(C`utf8\*(C'\fR flag. If it is disabled, this allows you |
| 1477 |
to decode ISO\-8859\-1\- and ASCII-encoded strings, as both strict subsets of |
| 1478 |
Unicode. If it is enabled, you can correctly decode UTF\-8 encoded strings. |
| 1479 |
.Sp |
| 1480 |
So neither \f(CW\*(C`latin1\*(C'\fR nor \f(CW\*(C`ascii\*(C'\fR are incompatible with the \f(CW\*(C`utf8\*(C'\fR flag \- |
| 1481 |
they only govern when the JSON output engine escapes a character or not. |
| 1482 |
.Sp |
| 1483 |
The main use for \f(CW\*(C`latin1\*(C'\fR is to relatively efficiently store binary data |
| 1484 |
as JSON, at the expense of breaking compatibility with most JSON decoders. |
| 1485 |
.Sp |
| 1486 |
The main use for \f(CW\*(C`ascii\*(C'\fR is to force the output to not contain characters |
| 1487 |
with values > 127, which means you can interpret the resulting string |
| 1488 |
as UTF\-8, ISO\-8859\-1, ASCII, KOI8\-R or most about any character set and |
| 1489 |
8\-bit\-encoding, and still get the same data structure back. This is useful |
| 1490 |
when your channel for JSON transfer is not 8\-bit clean or the encoding |
| 1491 |
might be mangled in between (e.g. in mail), and works because ASCII is a |
| 1492 |
proper subset of most 8\-bit and multibyte encodings in use in the world. |
| 1493 |
.SH BUGS |
| 1494 |
.IX Header "BUGS" |
| 1495 |
Please report bugs on a specific behavior of this module to RT or GitHub |
| 1496 |
issues (preferred): |
| 1497 |
.PP |
| 1498 |
<https://github.com/makamaka/JSON\-PP/issues> |
| 1499 |
.PP |
| 1500 |
<https://rt.cpan.org/Public/Dist/Display.html?Queue=JSON\-PP> |
| 1501 |
.PP |
| 1502 |
As for new features and requests to change common behaviors, please |
| 1503 |
ask the author of JSON::XS (Marc Lehmann, <schmorp[at]schmorp.de>) |
| 1504 |
first, by email (important!), to keep compatibility among JSON.pm backends. |
| 1505 |
.PP |
| 1506 |
Generally speaking, if you need something special for you, you are advised |
| 1507 |
to create a new module, maybe based on JSON::Tiny, which is smaller and |
| 1508 |
written in a much cleaner way than this module. |
| 1509 |
.SH "SEE ALSO" |
| 1510 |
.IX Header "SEE ALSO" |
| 1511 |
The \fIjson_pp\fR command line utility for quick experiments. |
| 1512 |
.PP |
| 1513 |
JSON::XS, Cpanel::JSON::XS, and JSON::Tiny for faster alternatives. |
| 1514 |
JSON and JSON::MaybeXS for easy migration. |
| 1515 |
.PP |
| 1516 |
JSON::PP::Compat5005 and JSON::PP::Compat5006 for older perl users. |
| 1517 |
.PP |
| 1518 |
RFC4627 (<http://www.ietf.org/rfc/rfc4627.txt>) |
| 1519 |
.PP |
| 1520 |
RFC7159 (<http://www.ietf.org/rfc/rfc7159.txt>) |
| 1521 |
.PP |
| 1522 |
RFC8259 (<http://www.ietf.org/rfc/rfc8259.txt>) |
| 1523 |
.SH AUTHOR |
| 1524 |
.IX Header "AUTHOR" |
| 1525 |
Makamaka Hannyaharamitu, <makamaka[at]cpan.org> |
| 1526 |
.SH "CURRENT MAINTAINER" |
| 1527 |
.IX Header "CURRENT MAINTAINER" |
| 1528 |
Kenichi Ishigaki, <ishigaki[at]cpan.org> |
| 1529 |
.SH "COPYRIGHT AND LICENSE" |
| 1530 |
.IX Header "COPYRIGHT AND LICENSE" |
| 1531 |
Copyright 2007\-2016 by Makamaka Hannyaharamitu |
| 1532 |
.PP |
| 1533 |
Most of the documentation is taken from JSON::XS by Marc Lehmann |
| 1534 |
.PP |
| 1535 |
This library is free software; you can redistribute it and/or modify |
| 1536 |
it under the same terms as Perl itself. |