… | |
… | |
202 | =over 4 |
202 | =over 4 |
203 | |
203 | |
204 | =item $json = new JSON::XS |
204 | =item $json = new JSON::XS |
205 | |
205 | |
206 | Creates a new JSON::XS object that can be used to de/encode JSON |
206 | Creates a new JSON::XS object that can be used to de/encode JSON |
207 | strings. All boolean flags described below are by default I<disabled>. |
207 | strings. All boolean flags described below are by default I<disabled> |
|
|
208 | (with the exception of C<allow_nonref>, which defaults to I<enabled> since |
|
|
209 | version C<4.0>). |
208 | |
210 | |
209 | The mutators for flags all return the JSON object again and thus calls can |
211 | The mutators for flags all return the JSON object again and thus calls can |
210 | be chained: |
212 | be chained: |
211 | |
213 | |
212 | my $json = JSON::XS->new->utf8->space_after->encode ({a => [1,2]}) |
214 | my $json = JSON::XS->new->utf8->space_after->encode ({a => [1,2]}) |
… | |
… | |
365 | |
367 | |
366 | =item $enabled = $json->get_relaxed |
368 | =item $enabled = $json->get_relaxed |
367 | |
369 | |
368 | If C<$enable> is true (or missing), then C<decode> will accept some |
370 | If C<$enable> is true (or missing), then C<decode> will accept some |
369 | extensions to normal JSON syntax (see below). C<encode> will not be |
371 | extensions to normal JSON syntax (see below). C<encode> will not be |
370 | affected in anyway. I<Be aware that this option makes you accept invalid |
372 | affected in any way. I<Be aware that this option makes you accept invalid |
371 | JSON texts as if they were valid!>. I suggest only to use this option to |
373 | JSON texts as if they were valid!>. I suggest only to use this option to |
372 | parse application-specific files written by humans (configuration files, |
374 | parse application-specific files written by humans (configuration files, |
373 | resource files etc.) |
375 | resource files etc.) |
374 | |
376 | |
375 | If C<$enable> is false (the default), then C<decode> will only accept |
377 | If C<$enable> is false (the default), then C<decode> will only accept |
… | |
… | |
441 | |
443 | |
442 | =item $json = $json->allow_nonref ([$enable]) |
444 | =item $json = $json->allow_nonref ([$enable]) |
443 | |
445 | |
444 | =item $enabled = $json->get_allow_nonref |
446 | =item $enabled = $json->get_allow_nonref |
445 | |
447 | |
|
|
448 | Unlike other boolean options, this opotion is enabled by default beginning |
|
|
449 | with version C<4.0>. See L<SECURITY CONSIDERATIONS> for the gory details. |
|
|
450 | |
446 | If C<$enable> is true (or missing), then the C<encode> method can convert a |
451 | If C<$enable> is true (or missing), then the C<encode> method can convert a |
447 | non-reference into its corresponding string, number or null JSON value, |
452 | non-reference into its corresponding string, number or null JSON value, |
448 | which is an extension to RFC4627. Likewise, C<decode> will accept those JSON |
453 | which is an extension to RFC4627. Likewise, C<decode> will accept those JSON |
449 | values instead of croaking. |
454 | values instead of croaking. |
450 | |
455 | |
451 | If C<$enable> is false, then the C<encode> method will croak if it isn't |
456 | If C<$enable> is false, then the C<encode> method will croak if it isn't |
452 | passed an arrayref or hashref, as JSON texts must either be an object |
457 | passed an arrayref or hashref, as JSON texts must either be an object |
453 | or array. Likewise, C<decode> will croak if given something that is not a |
458 | or array. Likewise, C<decode> will croak if given something that is not a |
454 | JSON object or array. |
459 | JSON object or array. |
455 | |
460 | |
456 | Example, encode a Perl scalar as JSON value with enabled C<allow_nonref>, |
461 | Example, encode a Perl scalar as JSON value without enabled C<allow_nonref>, |
457 | resulting in an invalid JSON text: |
462 | resulting in an error: |
458 | |
463 | |
459 | JSON::XS->new->allow_nonref->encode ("Hello, World!") |
464 | JSON::XS->new->allow_nonref (0)->encode ("Hello, World!") |
460 | => "Hello, World!" |
465 | => hash- or arrayref expected... |
461 | |
466 | |
462 | =item $json = $json->allow_unknown ([$enable]) |
467 | =item $json = $json->allow_unknown ([$enable]) |
463 | |
468 | |
464 | =item $enabled = $json->get_allow_unknown |
469 | =item $enabled = $json->get_allow_unknown |
465 | |
470 | |
… | |
… | |
515 | |
520 | |
516 | This setting has no effect on C<decode>. |
521 | This setting has no effect on C<decode>. |
517 | |
522 | |
518 | =item $json = $json->allow_tags ([$enable]) |
523 | =item $json = $json->allow_tags ([$enable]) |
519 | |
524 | |
520 | =item $enabled = $json->allow_tags |
525 | =item $enabled = $json->get_allow_tags |
521 | |
526 | |
522 | See L<OBJECT SERIALISATION> for details. |
527 | See L<OBJECT SERIALISATION> for details. |
523 | |
528 | |
524 | If C<$enable> is true (or missing), then C<encode>, upon encountering a |
529 | If C<$enable> is true (or missing), then C<encode>, upon encountering a |
525 | blessed object, will check for the availability of the C<FREEZE> method on |
530 | blessed object, will check for the availability of the C<FREEZE> method on |
… | |
… | |
534 | in C<decode>, as if tags were not part of the grammar. |
539 | in C<decode>, as if tags were not part of the grammar. |
535 | |
540 | |
536 | =item $json = $json->filter_json_object ([$coderef->($hashref)]) |
541 | =item $json = $json->filter_json_object ([$coderef->($hashref)]) |
537 | |
542 | |
538 | When C<$coderef> is specified, it will be called from C<decode> each |
543 | When C<$coderef> is specified, it will be called from C<decode> each |
539 | time it decodes a JSON object. The only argument is a reference to the |
544 | time it decodes a JSON object. The only argument is a reference to |
540 | newly-created hash. If the code references returns a single scalar (which |
545 | the newly-created hash. If the code reference returns a single scalar |
541 | need not be a reference), this value (i.e. a copy of that scalar to avoid |
546 | (which need not be a reference), this value (or rather a copy of it) is |
542 | aliasing) is inserted into the deserialised data structure. If it returns |
547 | inserted into the deserialised data structure. If it returns an empty |
543 | an empty list (NOTE: I<not> C<undef>, which is a valid scalar), the |
548 | list (NOTE: I<not> C<undef>, which is a valid scalar), the original |
544 | original deserialised hash will be inserted. This setting can slow down |
549 | deserialised hash will be inserted. This setting can slow down decoding |
545 | decoding considerably. |
550 | considerably. |
546 | |
551 | |
547 | When C<$coderef> is omitted or undefined, any existing callback will |
552 | When C<$coderef> is omitted or undefined, any existing callback will |
548 | be removed and C<decode> will not change the deserialised hash in any |
553 | be removed and C<decode> will not change the deserialised hash in any |
549 | way. |
554 | way. |
550 | |
555 | |
… | |
… | |
1567 | are browser design bugs, but it is still you who will have to deal with |
1572 | are browser design bugs, but it is still you who will have to deal with |
1568 | it, as major browser developers care only for features, not about getting |
1573 | it, as major browser developers care only for features, not about getting |
1569 | security right). |
1574 | security right). |
1570 | |
1575 | |
1571 | |
1576 | |
1572 | =head1 "OLD" VS. "NEW" JSON (RFC 4627 VS. RFC 7159) |
1577 | =head2 "OLD" VS. "NEW" JSON (RFC 4627 VS. RFC 7159) |
1573 | |
1578 | |
1574 | TL;DR: Due to security concerns, JSON::XS will not allow scalar data in |
1579 | JSON originally required JSON texts to represent an array or object - |
1575 | JSON texts by default - you need to create your own JSON::XS object and |
1580 | scalar values were explicitly not allowed. This has changed, and versions |
1576 | enable C<allow_nonref>: |
1581 | of JSON::XS beginning with C<4.0> reflect this by allowing scalar values |
|
|
1582 | by default. |
1577 | |
1583 | |
|
|
1584 | One reason why one might not want this is that this removes a fundamental |
|
|
1585 | property of JSON texts, namely that they are self-delimited and |
|
|
1586 | self-contained, or in other words, you could take any number of "old" |
|
|
1587 | JSON texts and paste them together, and the result would be unambiguously |
|
|
1588 | parseable: |
1578 | |
1589 | |
|
|
1590 | [1,3]{"k":5}[][null] # four JSON texts, without doubt |
|
|
1591 | |
|
|
1592 | By allowing scalars, this property is lost: in the following example, is |
|
|
1593 | this one JSON text (the number 12) or two JSON texts (the numbers 1 and |
|
|
1594 | 2): |
|
|
1595 | |
|
|
1596 | 12 # could be 12, or 1 and 2 |
|
|
1597 | |
|
|
1598 | Another lost property of "old" JSON is that no lookahead is required to |
|
|
1599 | know the end of a JSON text, i.e. the JSON text definitely ended at the |
|
|
1600 | last C<]> or C<}> character, there was no need to read extra characters. |
|
|
1601 | |
|
|
1602 | For example, a viable network protocol with "old" JSON was to simply |
|
|
1603 | exchange JSON texts without delimiter. For "new" JSON, you have to use a |
|
|
1604 | suitable delimiter (such as a newline) after every JSON text or ensure you |
|
|
1605 | never encode/decode scalar values. |
|
|
1606 | |
|
|
1607 | Most protocols do work by only transferring arrays or objects, and the |
|
|
1608 | easiest way to avoid problems with the "new" JSON definition is to |
|
|
1609 | explicitly disallow scalar values in your encoder and decoder: |
|
|
1610 | |
1579 | my $json = JSON::XS->new->allow_nonref; |
1611 | $json_coder = JSON::XS->new->allow_nonref (0) |
1580 | |
1612 | |
1581 | $text = $json->encode ($data); |
1613 | This is a somewhat unhappy situation, and the blame can fully be put on |
1582 | $data = $json->decode ($text); |
1614 | JSON's inmventor, Douglas Crockford, who unilaterally changed the format |
1583 | |
1615 | in 2006 without consulting the IETF, forcing the IETF to either fork the |
1584 | The long version: JSON being an important and supposedly stable format, |
1616 | format or go with it (as I was told, the IETF wasn't amused). |
1585 | the IETF standardised it as RFC 4627 in 2006. Unfortunately, the inventor |
|
|
1586 | of JSON, Dougles Crockford, unilaterally changed the definition of JSON in |
|
|
1587 | javascript. Rather than create a fork, the IETF decided to standardise the |
|
|
1588 | new syntax (apparently, so Iw as told, without finding it very amusing). |
|
|
1589 | |
|
|
1590 | The biggest difference between thed original JSON and the new JSON is that |
|
|
1591 | the new JSON supports scalars (anything other than arrays and objects) at |
|
|
1592 | the toplevel of a JSON text. While this is strictly backwards compatible |
|
|
1593 | to older versions, it breaks a number of protocols that relied on sending |
|
|
1594 | JSON back-to-back, and is a minor security concern. |
|
|
1595 | |
|
|
1596 | For example, imagine you have two banks communicating, and on one side, |
|
|
1597 | trhe JSON coder gets upgraded. Two messages, such as C<10> and C<1000> |
|
|
1598 | might then be confused to mean C<101000>, something that couldn't happen |
|
|
1599 | in the original JSON, because niether of these messages would be valid |
|
|
1600 | JSON. |
|
|
1601 | |
|
|
1602 | If one side accepts these messages, then an upgrade in the coder on either |
|
|
1603 | side could result in this becoming exploitable. |
|
|
1604 | |
|
|
1605 | This module has always allowed these messages as an optional extension, by |
|
|
1606 | default disabled. The security concerns are the reason why the default is |
|
|
1607 | still disabled, but future versions might/will likely upgrade to the newer |
|
|
1608 | RFC as default format, so you are advised to check your implementation |
|
|
1609 | and/or override the default with C<< ->allow_nonref (0) >> to ensure that |
|
|
1610 | future versions are safe. |
|
|
1611 | |
1617 | |
1612 | |
1618 | |
1613 | =head1 INTEROPERABILITY WITH OTHER MODULES |
1619 | =head1 INTEROPERABILITY WITH OTHER MODULES |
1614 | |
1620 | |
1615 | C<JSON::XS> uses the L<Types::Serialiser> module to provide boolean |
1621 | C<JSON::XS> uses the L<Types::Serialiser> module to provide boolean |
… | |
… | |
1700 | |
1706 | |
1701 | =head1 (I-)THREADS |
1707 | =head1 (I-)THREADS |
1702 | |
1708 | |
1703 | This module is I<not> guaranteed to be ithread (or MULTIPLICITY-) safe |
1709 | This module is I<not> guaranteed to be ithread (or MULTIPLICITY-) safe |
1704 | and there are no plans to change this. Note that perl's builtin so-called |
1710 | and there are no plans to change this. Note that perl's builtin so-called |
1705 | theeads/ithreads are officially deprecated and should not be used. |
1711 | threads/ithreads are officially deprecated and should not be used. |
1706 | |
1712 | |
1707 | |
1713 | |
1708 | =head1 THE PERILS OF SETLOCALE |
1714 | =head1 THE PERILS OF SETLOCALE |
1709 | |
1715 | |
1710 | Sometimes people avoid the Perl locale support and directly call the |
1716 | Sometimes people avoid the Perl locale support and directly call the |