| … | |
… | |
| 467 | |
467 | |
| 468 | =item $json = $json->allow_blessed ([$enable]) |
468 | =item $json = $json->allow_blessed ([$enable]) |
| 469 | |
469 | |
| 470 | =item $enabled = $json->get_allow_blessed |
470 | =item $enabled = $json->get_allow_blessed |
| 471 | |
471 | |
|
|
472 | See "OBJECT SERIALISATION" for details. |
|
|
473 | |
| 472 | If C<$enable> is true (or missing), then the C<encode> method will not |
474 | If C<$enable> is true (or missing), then the C<encode> method will not |
| 473 | barf when it encounters a blessed reference. Instead, the value of the |
475 | barf when it encounters a blessed reference that it cannot convert |
| 474 | B<convert_blessed> option will decide whether C<null> (C<convert_blessed> |
476 | otherwise. Instead, a JSON C<null> value is encoded instead of the object. |
| 475 | disabled or no C<TO_JSON> method found) or a representation of the |
|
|
| 476 | object (C<convert_blessed> enabled and C<TO_JSON> method found) is being |
|
|
| 477 | encoded. Has no effect on C<decode>. |
|
|
| 478 | |
477 | |
| 479 | If C<$enable> is false (the default), then C<encode> will throw an |
478 | If C<$enable> is false (the default), then C<encode> will throw an |
| 480 | exception when it encounters a blessed object. |
479 | exception when it encounters a blessed object that it cannot convert |
|
|
480 | otherwise. |
|
|
481 | |
|
|
482 | This setting has no effect on C<decode>. |
| 481 | |
483 | |
| 482 | =item $json = $json->convert_blessed ([$enable]) |
484 | =item $json = $json->convert_blessed ([$enable]) |
| 483 | |
485 | |
| 484 | =item $enabled = $json->get_convert_blessed |
486 | =item $enabled = $json->get_convert_blessed |
|
|
487 | |
|
|
488 | See "OBJECT SERIALISATION" for details. |
| 485 | |
489 | |
| 486 | If C<$enable> is true (or missing), then C<encode>, upon encountering a |
490 | If C<$enable> is true (or missing), then C<encode>, upon encountering a |
| 487 | blessed object, will check for the availability of the C<TO_JSON> method |
491 | blessed object, will check for the availability of the C<TO_JSON> method |
| 488 | on the object's class. If found, it will be called in scalar context |
492 | on the object's class. If found, it will be called in scalar context and |
| 489 | and the resulting scalar will be encoded instead of the object. If no |
493 | the resulting scalar will be encoded instead of the object. |
| 490 | C<TO_JSON> method is found, the value of C<allow_blessed> will decide what |
|
|
| 491 | to do. |
|
|
| 492 | |
494 | |
| 493 | The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON> |
495 | The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON> |
| 494 | returns other blessed objects, those will be handled in the same |
496 | returns other blessed objects, those will be handled in the same |
| 495 | way. C<TO_JSON> must take care of not causing an endless recursion cycle |
497 | way. C<TO_JSON> must take care of not causing an endless recursion cycle |
| 496 | (== crash) in this case. The name of C<TO_JSON> was chosen because other |
498 | (== crash) in this case. The name of C<TO_JSON> was chosen because other |
| 497 | methods called by the Perl core (== not by the user of the object) are |
499 | methods called by the Perl core (== not by the user of the object) are |
| 498 | usually in upper case letters and to avoid collisions with any C<to_json> |
500 | usually in upper case letters and to avoid collisions with any C<to_json> |
| 499 | function or method. |
501 | function or method. |
| 500 | |
502 | |
| 501 | This setting does not yet influence C<decode> in any way, but in the |
503 | If C<$enable> is false (the default), then C<encode> will not consider |
| 502 | future, global hooks might get installed that influence C<decode> and are |
504 | this type of conversion. |
| 503 | enabled by this setting. |
|
|
| 504 | |
505 | |
| 505 | If C<$enable> is false, then the C<allow_blessed> setting will decide what |
506 | This setting has no effect on C<decode>. |
| 506 | to do when a blessed object is found. |
507 | |
|
|
508 | =item $json = $json->allow_tags ([$enable]) |
|
|
509 | |
|
|
510 | =item $enabled = $json->allow_tags |
|
|
511 | |
|
|
512 | See "OBJECT SERIALISATION" for details. |
|
|
513 | |
|
|
514 | If C<$enable> is true (or missing), then C<encode>, upon encountering a |
|
|
515 | blessed object, will check for the availability of the C<FREEZE> method on |
|
|
516 | the object's class. If found, it will be used to serialise the object into |
|
|
517 | a nonstandard tagged JSON value (that JSON decoders cannot decode). |
|
|
518 | |
|
|
519 | It also causes C<decode> to parse such tagged JSON values and deserialise |
|
|
520 | them via a call to the C<THAW> method. |
|
|
521 | |
|
|
522 | If C<$enable> is false (the default), then C<encode> will not consider |
|
|
523 | this type of conversion, and tagged JSON values will cause a parse error |
|
|
524 | in C<decode>, as if tags were not part of the grammar. |
| 507 | |
525 | |
| 508 | =item $json = $json->filter_json_object ([$coderef->($hashref)]) |
526 | =item $json = $json->filter_json_object ([$coderef->($hashref)]) |
| 509 | |
527 | |
| 510 | When C<$coderef> is specified, it will be called from C<decode> each |
528 | When C<$coderef> is specified, it will be called from C<decode> each |
| 511 | time it decodes a JSON object. The only argument is a reference to the |
529 | time it decodes a JSON object. The only argument is a reference to the |
| … | |
… | |
| 1176 | This section only considers the tagged value case: I a tagged JSON object |
1194 | This section only considers the tagged value case: I a tagged JSON object |
| 1177 | is encountered during decoding and C<allow_tags> is disabled, a parse |
1195 | is encountered during decoding and C<allow_tags> is disabled, a parse |
| 1178 | error will result (as if tagged values were not part of the grammar). |
1196 | error will result (as if tagged values were not part of the grammar). |
| 1179 | |
1197 | |
| 1180 | If C<allow_tags> is enabled, C<JSON::XS> will look up the C<THAW> method |
1198 | If C<allow_tags> is enabled, C<JSON::XS> will look up the C<THAW> method |
| 1181 | of the package/classname used during serialisation. If there is no such |
1199 | of the package/classname used during serialisation (it will not attempt |
|
|
1200 | to load the package as a Perl module). If there is no such method, the |
| 1182 | method, the decoding will fail with an error. |
1201 | decoding will fail with an error. |
| 1183 | |
1202 | |
| 1184 | Otherwise, the C<THAW> method is invoked with the classname as first |
1203 | Otherwise, the C<THAW> method is invoked with the classname as first |
| 1185 | argument, the constant string C<JSON> as second argument, and all the |
1204 | argument, the constant string C<JSON> as second argument, and all the |
| 1186 | values from the JSON array (the values originally returned by the |
1205 | values from the JSON array (the values originally returned by the |
| 1187 | C<FREEZE> method) as remaining arguments. |
1206 | C<FREEZE> method) as remaining arguments. |
