… | |
… | |
397 | Example, encode a Perl scalar as JSON value with enabled |
397 | Example, encode a Perl scalar as JSON value with enabled |
398 | "allow_nonref", resulting in an invalid JSON text: |
398 | "allow_nonref", resulting in an invalid JSON text: |
399 | |
399 | |
400 | JSON::XS->new->allow_nonref->encode ("Hello, World!") |
400 | JSON::XS->new->allow_nonref->encode ("Hello, World!") |
401 | => "Hello, World!" |
401 | => "Hello, World!" |
|
|
402 | |
|
|
403 | $json = $json->allow_unknown ([$enable]) |
|
|
404 | $enabled = $json->get_allow_unknown |
|
|
405 | If $enable is true (or missing), then "encode" will *not* throw an |
|
|
406 | exception when it encounters values it cannot represent in JSON (for |
|
|
407 | example, filehandles) but instead will encode a JSON "null" value. |
|
|
408 | Note that blessed objects are not included here and are handled |
|
|
409 | separately by c<allow_nonref>. |
|
|
410 | |
|
|
411 | If $enable is false (the default), then "encode" will throw an |
|
|
412 | exception when it encounters anything it cannot encode as JSON. |
|
|
413 | |
|
|
414 | This option does not affect "decode" in any way, and it is |
|
|
415 | recommended to leave it off unless you know your communications |
|
|
416 | partner. |
402 | |
417 | |
403 | $json = $json->allow_blessed ([$enable]) |
418 | $json = $json->allow_blessed ([$enable]) |
404 | $enabled = $json->get_allow_blessed |
419 | $enabled = $json->get_allow_blessed |
405 | If $enable is true (or missing), then the "encode" method will not |
420 | If $enable is true (or missing), then the "encode" method will not |
406 | barf when it encounters a blessed reference. Instead, the value of |
421 | barf when it encounters a blessed reference. Instead, the value of |
… | |
… | |
541 | saving space. |
556 | saving space. |
542 | |
557 | |
543 | $json = $json->max_depth ([$maximum_nesting_depth]) |
558 | $json = $json->max_depth ([$maximum_nesting_depth]) |
544 | $max_depth = $json->get_max_depth |
559 | $max_depth = $json->get_max_depth |
545 | Sets the maximum nesting level (default 512) accepted while encoding |
560 | Sets the maximum nesting level (default 512) accepted while encoding |
546 | or decoding. If the JSON text or Perl data structure has an equal or |
561 | or decoding. If a higher nesting level is detected in JSON text or a |
547 | higher nesting level then this limit, then the encoder and decoder |
562 | Perl data structure, then the encoder and decoder will stop and |
548 | will stop and croak at that point. |
563 | croak at that point. |
549 | |
564 | |
550 | Nesting level is defined by number of hash- or arrayrefs that the |
565 | Nesting level is defined by number of hash- or arrayrefs that the |
551 | encoder needs to traverse to reach a given point or the number of |
566 | encoder needs to traverse to reach a given point or the number of |
552 | "{" or "[" characters without their matching closing parenthesis |
567 | "{" or "[" characters without their matching closing parenthesis |
553 | crossed to reach a given character in a string. |
568 | crossed to reach a given character in a string. |
554 | |
569 | |
555 | Setting the maximum depth to one disallows any nesting, so that |
570 | Setting the maximum depth to one disallows any nesting, so that |
556 | ensures that the object is only a single hash/object or array. |
571 | ensures that the object is only a single hash/object or array. |
557 | |
572 | |
558 | The argument to "max_depth" will be rounded up to the next highest |
|
|
559 | power of two. If no argument is given, the highest possible setting |
573 | If no argument is given, the highest possible setting will be used, |
560 | will be used, which is rarely useful. |
574 | which is rarely useful. |
|
|
575 | |
|
|
576 | Note that nesting is implemented by recursion in C. The default |
|
|
577 | value has been chosen to be as large as typical operating systems |
|
|
578 | allow without crashing. |
561 | |
579 | |
562 | See SECURITY CONSIDERATIONS, below, for more info on why this is |
580 | See SECURITY CONSIDERATIONS, below, for more info on why this is |
563 | useful. |
581 | useful. |
564 | |
582 | |
565 | $json = $json->max_size ([$maximum_string_size]) |
583 | $json = $json->max_size ([$maximum_string_size]) |
566 | $max_size = $json->get_max_size |
584 | $max_size = $json->get_max_size |
567 | Set the maximum length a JSON text may have (in bytes) where |
585 | Set the maximum length a JSON text may have (in bytes) where |
568 | decoding is being attempted. The default is 0, meaning no limit. |
586 | decoding is being attempted. The default is 0, meaning no limit. |
569 | When "decode" is called on a string longer then this number of |
587 | When "decode" is called on a string that is longer then this many |
570 | characters it will not attempt to decode the string but throw an |
588 | bytes, it will not attempt to decode the string but throw an |
571 | exception. This setting has no effect on "encode" (yet). |
589 | exception. This setting has no effect on "encode" (yet). |
572 | |
590 | |
573 | The argument to "max_size" will be rounded up to the next highest |
|
|
574 | power of two (so may be more than requested). If no argument is |
|
|
575 | given, the limit check will be deactivated (same as when 0 is |
591 | If no argument is given, the limit check will be deactivated (same |
576 | specified). |
592 | as when 0 is specified). |
577 | |
593 | |
578 | See SECURITY CONSIDERATIONS, below, for more info on why this is |
594 | See SECURITY CONSIDERATIONS, below, for more info on why this is |
579 | useful. |
595 | useful. |
580 | |
596 | |
581 | $json_text = $json->encode ($perl_scalar) |
597 | $json_text = $json->encode ($perl_scalar) |
… | |
… | |
1097 | |
1113 | |
1098 | First comes a comparison between various modules using a very short |
1114 | First comes a comparison between various modules using a very short |
1099 | single-line JSON string (also available at |
1115 | single-line JSON string (also available at |
1100 | <http://dist.schmorp.de/misc/json/short.json>). |
1116 | <http://dist.schmorp.de/misc/json/short.json>). |
1101 | |
1117 | |
1102 | {"method": "handleMessage", "params": ["user1", "we were just talking"], \ |
1118 | {"method": "handleMessage", "params": ["user1", |
1103 | "id": null, "array":[1,11,234,-5,1e5,1e7, true, false]} |
1119 | "we were just talking"], "id": null, "array":[1,11,234,-5,1e5,1e7, |
|
|
1120 | true, false]} |
1104 | |
1121 | |
1105 | It shows the number of encodes/decodes per second (JSON::XS uses the |
1122 | It shows the number of encodes/decodes per second (JSON::XS uses the |
1106 | functional interface, while JSON::XS/2 uses the OO interface with |
1123 | functional interface, while JSON::XS/2 uses the OO interface with |
1107 | pretty-printing and hashkey sorting enabled, JSON::XS/3 enables shrink). |
1124 | pretty-printing and hashkey sorting enabled, JSON::XS/3 enables shrink). |
1108 | Higher is better: |
1125 | Higher is better: |