1JSON version 2.17 2================= 3 4INSTALLATION 5 6To install this module type the following: 7 8 perl Makefile.PL 9 make 10 make test 11 make install 12 13NAME 14 JSON - JSON (JavaScript Object Notation) encoder/decoder 15 16SYNOPSIS 17 use JSON; # imports encode_json, decode_json, to_json and from_json. 18 19 $json_text = to_json($perl_scalar); 20 $perl_scalar = from_json($json_text); 21 22 # option-acceptable 23 $json_text = to_json($perl_scalar, {ascii => 1}); 24 $perl_scalar = from_json($json_text, {utf8 => 1}); 25 26 # OOP 27 $json = new JSON; 28 29 $json_text = $json->encode($perl_scalar); 30 $perl_scalar = $json->decode($json_text); 31 32 # pretty-printing 33 $json_text = $json->pretty->encode($perl_scalar); 34 35 # simple interface 36 $utf8_encoded_json_text = encode_json $perl_hash_or_arrayref; 37 $perl_hash_or_arrayref = decode_json $utf8_encoded_json_text; 38 39 # If you want to use PP only support features, call with '-support_by_pp' 40 # When XS unsupported feature is enable, using PP de/encode. 41 42 use JSON -support_by_pp; 43 44VERSION 45 2.17 46 47 This version is compatible with JSON::XS 2.27 and later. 48 49DESCRIPTION 50 ************************** CAUTION ******************************** 51 * This is 'JSON module version 2' and there are many differences * 52 * to version 1.xx * 53 * Please check your applications useing old version. * 54 * See to 'INCOMPATIBLE CHANGES TO OLD VERSION' * 55 ******************************************************************* 56 57 JSON (JavaScript Object Notation) is a simple data format. See to 58 <http://www.json.org/> and 59 "RFC4627"(<http://www.ietf.org/rfc/rfc4627.txt>). 60 61 This module converts Perl data structures to JSON and vice versa using 62 either JSON::XS or JSON::PP. 63 64 JSON::XS is the fastest and most proper JSON module on CPAN which must 65 be compiled and installed in your environment. JSON::PP is a pure-Perl 66 module which is bundled in this distribution and has a strong 67 compatibility to JSON::XS. 68 69 This module try to use JSON::XS by default and fail to it, use JSON::PP 70 instead. So its features completely depend on JSON::XS or JSON::PP. 71 72 See to "BACKEND MODULE DECISION". 73 74 To distinguish the module name 'JSON' and the format type JSON, the 75 former is quoted by C<> (its results vary with your using media), and 76 the latter is left just as it is. 77 78 Module name : "JSON" 79 80 Format type : JSON 81 82 FEATURES 83 * correct unicode handling 84 This module (i.e. backend modules) knows how to handle Unicode, 85 documents how and when it does so, and even documents what "correct" 86 means. 87 88 Even though there are limitations, this feature is available since 89 Perl version 5.6. 90 91 JSON::XS requires Perl 5.8.2 (but works correctly in 5.8.8 or 92 later), so in older versions "JSON" sholud call JSON::PP as the 93 backend which can be used since Perl 5.005. 94 95 With Perl 5.8.x JSON::PP works, but from 5.8.0 to 5.8.2, because of 96 a Perl side problem, JSON::PP works slower in the versions. And in 97 5.005, the Unicode handling is not available. See to "UNICODE 98 HANDLING ON PERLS" in JSON::PP for more information. 99 100 See also to "A FEW NOTES ON UNICODE AND PERL" in JSON::XS and 101 "ENCODING/CODESET_FLAG_NOTES" in JSON::XS. 102 103 * round-trip integrity 104 When you serialise a perl data structure using only data types 105 supported by JSON, the deserialised data structure is identical on 106 the Perl level. (e.g. the string "2.0" doesn't suddenly become "2" 107 just because it looks like a number). There minor *are* exceptions 108 to this, read the MAPPING section below to learn about those. 109 110 * strict checking of JSON correctness 111 There is no guessing, no generating of illegal JSON texts by 112 default, and only JSON is accepted as input by default (the latter 113 is a security feature). 114 115 See to "FEATURES" in JSON::XS and "FEATURES" in JSON::PP. 116 117 * fast 118 This module returns a JSON::XS object itself if avaliable. Compared 119 to other JSON modules and other serialisers such as Storable, 120 JSON::XS usually compares favourably in terms of speed, too. 121 122 If not avaliable, "JSON" returns a JSON::PP object instead of 123 JSON::XS and it is very slow as pure-Perl. 124 125 * simple to use 126 This module has both a simple functional interface as well as an 127 object oriented interface interface. 128 129 * reasonably versatile output formats 130 You can choose between the most compact guaranteed-single-line 131 format possible (nice for simple line-based protocols), a pure-ASCII 132 format (for when your transport is not 8-bit clean, still supports 133 the whole Unicode range), or a pretty-printed format (for when you 134 want to read that stuff). Or you can combine those features in 135 whatever way you like. 136 137FUNCTIONAL INTERFACE 138 Some documents are copied and modified from "FUNCTIONAL INTERFACE" in 139 JSON::XS. "to_json" and "from_json" are additional functions. 140 141 to_json 142 $json_text = to_json($perl_scalar) 143 144 Converts the given Perl data structure to a json string. 145 146 This function call is functionally identical to: 147 148 $json_text = JSON->new->encode($perl_scalar) 149 150 Takes a hash reference as the second. 151 152 $json_text = to_json($perl_scalar, $flag_hashref) 153 154 So, 155 156 $json_text = encode_json($perl_scalar, {utf8 => 1, pretty => 1}) 157 158 equivalent to: 159 160 $json_text = JSON->new->utf8(1)->pretty(1)->encode($perl_scalar) 161 162 from_json 163 $perl_scalar = from_json($json_text) 164 165 The opposite of "to_json": expects a json string and tries to parse it, 166 returning the resulting reference. 167 168 This function call is functionally identical to: 169 170 $perl_scalar = JSON->decode($json_text) 171 172 Takes a hash reference as the second. 173 174 $perl_scalar = from_json($json_text, $flag_hashref) 175 176 So, 177 178 $perl_scalar = from_json($json_text, {utf8 => 1}) 179 180 equivalent to: 181 182 $perl_scalar = JSON->new->utf8(1)->decode($json_text) 183 184 encode_json 185 $json_text = encode_json $perl_scalar 186 187 Converts the given Perl data structure to a UTF-8 encoded, binary 188 string. 189 190 This function call is functionally identical to: 191 192 $json_text = JSON->new->utf8->encode($perl_scalar) 193 194 decode_json 195 $perl_scalar = decode_json $json_text 196 197 The opposite of "encode_json": expects an UTF-8 (binary) string and 198 tries to parse that as an UTF-8 encoded JSON text, returning the 199 resulting reference. 200 201 This function call is functionally identical to: 202 203 $perl_scalar = JSON->new->utf8->decode($json_text) 204 205 JSON::is_bool 206 $is_boolean = JSON::is_bool($scalar) 207 208 Returns true if the passed scalar represents either JSON::true or 209 JSON::false, two constants that act like 1 and 0 respectively and are 210 also used to represent JSON "true" and "false" in Perl strings. 211 212 JSON::true 213 Returns JSON true value which is blessed object. It "isa" JSON::Boolean 214 object. 215 216 JSON::false 217 Returns JSON false value which is blessed object. It "isa" JSON::Boolean 218 object. 219 220 JSON::null 221 Returns "undef". 222 223 See MAPPING, below, for more information on how JSON values are mapped 224 to Perl. 225 226COMMON OBJECT-ORIENTED INTERFACE 227 new 228 $json = new JSON 229 230 Returns a new "JSON" object inherited from either JSON::XS or JSON::PP 231 that can be used to de/encode JSON strings. 232 233 All boolean flags described below are by default *disabled*. 234 235 The mutators for flags all return the JSON object again and thus calls 236 can be chained: 237 238 my $json = JSON->new->utf8->space_after->encode({a => [1,2]}) 239 => {"a": [1, 2]} 240 241 ascii 242 $json = $json->ascii([$enable]) 243 244 $enabled = $json->get_ascii 245 246 If $enable is true (or missing), then the encode method will not 247 generate characters outside the code range 0..127. Any Unicode 248 characters outside that range will be escaped using either a single 249 \uXXXX or a double \uHHHH\uLLLLL escape sequence, as per RFC4627. 250 251 If $enable is false, then the encode method will not escape Unicode 252 characters unless required by the JSON syntax or other flags. This 253 results in a faster and more compact format. 254 255 This feature depends on the used Perl version and environment. 256 257 See to "UNICODE HANDLING ON PERLS" in JSON::PP if the backend is PP. 258 259 JSON->new->ascii(1)->encode([chr 0x10401]) 260 => ["\ud801\udc01"] 261 262 latin1 263 $json = $json->latin1([$enable]) 264 265 $enabled = $json->get_latin1 266 267 If $enable is true (or missing), then the encode method will encode the 268 resulting JSON text as latin1 (or iso-8859-1), escaping any characters 269 outside the code range 0..255. 270 271 If $enable is false, then the encode method will not escape Unicode 272 characters unless required by the JSON syntax or other flags. 273 274 JSON->new->latin1->encode (["\x{89}\x{abc}"] 275 => ["\x{89}\\u0abc"] # (perl syntax, U+abc escaped, U+89 not) 276 277 utf8 278 $json = $json->utf8([$enable]) 279 280 $enabled = $json->get_utf8 281 282 If $enable is true (or missing), then the encode method will encode the 283 JSON result into UTF-8, as required by many protocols, while the decode 284 method expects to be handled an UTF-8-encoded string. Please note that 285 UTF-8-encoded strings do not contain any characters outside the range 286 0..255, they are thus useful for bytewise/binary I/O. 287 288 In future versions, enabling this option might enable autodetection of 289 the UTF-16 and UTF-32 encoding families, as described in RFC4627. 290 291 If $enable is false, then the encode method will return the JSON string 292 as a (non-encoded) Unicode string, while decode expects thus a Unicode 293 string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs to be 294 done yourself, e.g. using the Encode module. 295 296 Example, output UTF-16BE-encoded JSON: 297 298 use Encode; 299 $jsontext = encode "UTF-16BE", JSON::XS->new->encode ($object); 300 301 Example, decode UTF-32LE-encoded JSON: 302 303 use Encode; 304 $object = JSON::XS->new->decode (decode "UTF-32LE", $jsontext); 305 306 See to "UNICODE HANDLING ON PERLS" in JSON::PP if the backend is PP. 307 308 pretty 309 $json = $json->pretty([$enable]) 310 311 This enables (or disables) all of the "indent", "space_before" and 312 "space_after" (and in the future possibly more) flags in one call to 313 generate the most readable (or most compact) form possible. 314 315 Equivalent to: 316 317 $json->indent->space_before->space_after 318 319 The indent space length is three and JSON::XS cannot change the indent 320 space length. 321 322 indent 323 $json = $json->indent([$enable]) 324 325 $enabled = $json->get_indent 326 327 If $enable is true (or missing), then the "encode" method will use a 328 multiline format as output, putting every array member or object/hash 329 key-value pair into its own line, identing them properly. 330 331 If $enable is false, no newlines or indenting will be produced, and the 332 resulting JSON text is guarenteed not to contain any "newlines". 333 334 This setting has no effect when decoding JSON texts. 335 336 The indent space length is three. With JSON::PP, you can also access 337 "indent_length" to change indent space length. 338 339 space_before 340 $json = $json->space_before([$enable]) 341 342 $enabled = $json->get_space_before 343 344 If $enable is true (or missing), then the "encode" method will add an 345 extra optional space before the ":" separating keys from values in JSON 346 objects. 347 348 If $enable is false, then the "encode" method will not add any extra 349 space at those places. 350 351 This setting has no effect when decoding JSON texts. 352 353 Example, space_before enabled, space_after and indent disabled: 354 355 {"key" :"value"} 356 357 space_after 358 $json = $json->space_after([$enable]) 359 360 $enabled = $json->get_space_after 361 362 If $enable is true (or missing), then the "encode" method will add an 363 extra optional space after the ":" separating keys from values in JSON 364 objects and extra whitespace after the "," separating key-value pairs 365 and array members. 366 367 If $enable is false, then the "encode" method will not add any extra 368 space at those places. 369 370 This setting has no effect when decoding JSON texts. 371 372 Example, space_before and indent disabled, space_after enabled: 373 374 {"key": "value"} 375 376 relaxed 377 $json = $json->relaxed([$enable]) 378 379 $enabled = $json->get_relaxed 380 381 If $enable is true (or missing), then "decode" will accept some 382 extensions to normal JSON syntax (see below). "encode" will not be 383 affected in anyway. *Be aware that this option makes you accept invalid 384 JSON texts as if they were valid!*. I suggest only to use this option to 385 parse application-specific files written by humans (configuration files, 386 resource files etc.) 387 388 If $enable is false (the default), then "decode" will only accept valid 389 JSON texts. 390 391 Currently accepted extensions are: 392 393 * list items can have an end-comma 394 JSON *separates* array elements and key-value pairs with commas. 395 This can be annoying if you write JSON texts manually and want to be 396 able to quickly append elements, so this extension accepts comma at 397 the end of such items not just between them: 398 399 [ 400 1, 401 2, <- this comma not normally allowed 402 ] 403 { 404 "k1": "v1", 405 "k2": "v2", <- this comma not normally allowed 406 } 407 408 * shell-style '#'-comments 409 Whenever JSON allows whitespace, shell-style comments are 410 additionally allowed. They are terminated by the first 411 carriage-return or line-feed character, after which more white-space 412 and comments are allowed. 413 414 [ 415 1, # this comment not allowed in JSON 416 # neither this one... 417 ] 418 419 canonical 420 $json = $json->canonical([$enable]) 421 422 $enabled = $json->get_canonical 423 424 If $enable is true (or missing), then the "encode" method will output 425 JSON objects by sorting their keys. This is adding a comparatively high 426 overhead. 427 428 If $enable is false, then the "encode" method will output key-value 429 pairs in the order Perl stores them (which will likely change between 430 runs of the same script). 431 432 This option is useful if you want the same data structure to be encoded 433 as the same JSON text (given the same overall settings). If it is 434 disabled, the same hash might be encoded differently even if contains 435 the same data, as key-value pairs have no inherent ordering in Perl. 436 437 This setting has no effect when decoding JSON texts. 438 439 allow_nonref 440 $json = $json->allow_nonref([$enable]) 441 442 $enabled = $json->get_allow_nonref 443 444 If $enable is true (or missing), then the "encode" method can convert a 445 non-reference into its corresponding string, number or null JSON value, 446 which is an extension to RFC4627. Likewise, "decode" will accept those 447 JSON values instead of croaking. 448 449 If $enable is false, then the "encode" method will croak if it isn't 450 passed an arrayref or hashref, as JSON texts must either be an object or 451 array. Likewise, "decode" will croak if given something that is not a 452 JSON object or array. 453 454 JSON->new->allow_nonref->encode ("Hello, World!") 455 => "Hello, World!" 456 457 allow_unknown 458 $json = $json->allow_unknown ([$enable]) 459 460 $enabled = $json->get_allow_unknown 461 462 If $enable is true (or missing), then "encode" will *not* throw an 463 exception when it encounters values it cannot represent in JSON (for 464 example, filehandles) but instead will encode a JSON "null" value. Note 465 that blessed objects are not included here and are handled separately by 466 c<allow_nonref>. 467 468 If $enable is false (the default), then "encode" will throw an exception 469 when it encounters anything it cannot encode as JSON. 470 471 This option does not affect "decode" in any way, and it is recommended 472 to leave it off unless you know your communications partner. 473 474 allow_blessed 475 $json = $json->allow_blessed([$enable]) 476 477 $enabled = $json->get_allow_blessed 478 479 If $enable is true (or missing), then the "encode" method will not barf 480 when it encounters a blessed reference. Instead, the value of the 481 convert_blessed option will decide whether "null" ("convert_blessed" 482 disabled or no "TO_JSON" method found) or a representation of the object 483 ("convert_blessed" enabled and "TO_JSON" method found) is being encoded. 484 Has no effect on "decode". 485 486 If $enable is false (the default), then "encode" will throw an exception 487 when it encounters a blessed object. 488 489 convert_blessed 490 $json = $json->convert_blessed([$enable]) 491 492 $enabled = $json->get_convert_blessed 493 494 If $enable is true (or missing), then "encode", upon encountering a 495 blessed object, will check for the availability of the "TO_JSON" method 496 on the object's class. If found, it will be called in scalar context and 497 the resulting scalar will be encoded instead of the object. If no 498 "TO_JSON" method is found, the value of "allow_blessed" will decide what 499 to do. 500 501 The "TO_JSON" method may safely call die if it wants. If "TO_JSON" 502 returns other blessed objects, those will be handled in the same way. 503 "TO_JSON" must take care of not causing an endless recursion cycle (== 504 crash) in this case. The name of "TO_JSON" was chosen because other 505 methods called by the Perl core (== not by the user of the object) are 506 usually in upper case letters and to avoid collisions with the "to_json" 507 function or method. 508 509 This setting does not yet influence "decode" in any way. 510 511 If $enable is false, then the "allow_blessed" setting will decide what 512 to do when a blessed object is found. 513 514 convert_blessed_universally mode 515 If use "JSON" with "-convert_blessed_universally", the 516 "UNIVERSAL::TO_JSON" subroutine is defined as the below code: 517 518 *UNIVERSAL::TO_JSON = sub { 519 my $b_obj = B::svref_2object( $_[0] ); 520 return $b_obj->isa('B::HV') ? { %{ $_[0] } } 521 : $b_obj->isa('B::AV') ? [ @{ $_[0] } ] 522 : undef 523 ; 524 } 525 526 This will cause that "encode" method converts simple blessed objects 527 into JSON objects as non-blessed object. 528 529 JSON -convert_blessed_universally; 530 $json->allow_blessed->convert_blessed->encode( $blessed_object ) 531 532 This feature is experimental and may be removed in the future. 533 534 filter_json_object 535 $json = $json->filter_json_object([$coderef]) 536 537 When $coderef is specified, it will be called from "decode" each time it 538 decodes a JSON object. The only argument passed to the coderef is a 539 reference to the newly-created hash. If the code references returns a 540 single scalar (which need not be a reference), this value (i.e. a copy 541 of that scalar to avoid aliasing) is inserted into the deserialised data 542 structure. If it returns an empty list (NOTE: *not* "undef", which is a 543 valid scalar), the original deserialised hash will be inserted. This 544 setting can slow down decoding considerably. 545 546 When $coderef is omitted or undefined, any existing callback will be 547 removed and "decode" will not change the deserialised hash in any way. 548 549 Example, convert all JSON objects into the integer 5: 550 551 my $js = JSON->new->filter_json_object (sub { 5 }); 552 # returns [5] 553 $js->decode ('[{}]'); # the given subroutine takes a hash reference. 554 # throw an exception because allow_nonref is not enabled 555 # so a lone 5 is not allowed. 556 $js->decode ('{"a":1, "b":2}'); 557 558 filter_json_single_key_object 559 $json = $json->filter_json_single_key_object($key [=> $coderef]) 560 561 Works remotely similar to "filter_json_object", but is only called for 562 JSON objects having a single key named $key. 563 564 This $coderef is called before the one specified via 565 "filter_json_object", if any. It gets passed the single value in the 566 JSON object. If it returns a single value, it will be inserted into the 567 data structure. If it returns nothing (not even "undef" but the empty 568 list), the callback from "filter_json_object" will be called next, as if 569 no single-key callback were specified. 570 571 If $coderef is omitted or undefined, the corresponding callback will be 572 disabled. There can only ever be one callback for a given key. 573 574 As this callback gets called less often then the "filter_json_object" 575 one, decoding speed will not usually suffer as much. Therefore, 576 single-key objects make excellent targets to serialise Perl objects 577 into, especially as single-key JSON objects are as close to the 578 type-tagged value concept as JSON gets (it's basically an ID/VALUE 579 tuple). Of course, JSON does not support this in any way, so you need to 580 make sure your data never looks like a serialised Perl hash. 581 582 Typical names for the single object key are "__class_whatever__", or 583 "$__dollars_are_rarely_used__$" or "}ugly_brace_placement", or even 584 things like "__class_md5sum(classname)__", to reduce the risk of 585 clashing with real hashes. 586 587 Example, decode JSON objects of the form "{ "__widget__" => <id> }" into 588 the corresponding $WIDGET{<id>} object: 589 590 # return whatever is in $WIDGET{5}: 591 JSON 592 ->new 593 ->filter_json_single_key_object (__widget__ => sub { 594 $WIDGET{ $_[0] } 595 }) 596 ->decode ('{"__widget__": 5') 597 598 # this can be used with a TO_JSON method in some "widget" class 599 # for serialisation to json: 600 sub WidgetBase::TO_JSON { 601 my ($self) = @_; 602 603 unless ($self->{id}) { 604 $self->{id} = ..get..some..id..; 605 $WIDGET{$self->{id}} = $self; 606 } 607 608 { __widget__ => $self->{id} } 609 } 610 611 shrink 612 $json = $json->shrink([$enable]) 613 614 $enabled = $json->get_shrink 615 616 With JSON::XS, this flag resizes strings generated by either "encode" or 617 "decode" to their minimum size possible. This can save memory when your 618 JSON texts are either very very long or you have many short strings. It 619 will also try to downgrade any strings to octet-form if possible: perl 620 stores strings internally either in an encoding called UTF-X or in 621 octet-form. The latter cannot store everything but uses less space in 622 general (and some buggy Perl or C code might even rely on that internal 623 representation being used). 624 625 With JSON::PP, it is noop about resizing strings but tries 626 "utf8::downgrade" to the returned string by "encode". See to utf8. 627 628 See to "OBJECT-ORIENTED INTERFACE" in JSON::XS and "METHODS" in 629 JSON::PP. 630 631 max_depth 632 $json = $json->max_depth([$maximum_nesting_depth]) 633 634 $max_depth = $json->get_max_depth 635 636 Sets the maximum nesting level (default 512) accepted while encoding or 637 decoding. If a higher nesting level is detected in JSON text or a Perl 638 data structure, then the encoder and decoder will stop and croak at that 639 point. 640 641 Nesting level is defined by number of hash- or arrayrefs that the 642 encoder needs to traverse to reach a given point or the number of "{" or 643 "[" characters without their matching closing parenthesis crossed to 644 reach a given character in a string. 645 646 If no argument is given, the highest possible setting will be used, 647 which is rarely useful. 648 649 Note that nesting is implemented by recursion in C. The default value 650 has been chosen to be as large as typical operating systems allow 651 without crashing. (JSON::XS) 652 653 With JSON::PP as the backend, when a large value (100 or more) was set 654 and it de/encodes a deep nested object/text, it may raise a warning 655 'Deep recursion on subroutin' at the perl runtime phase. 656 657 See "SECURITY CONSIDERATIONS" in JSON::XS for more info on why this is 658 useful. 659 660 max_size 661 $json = $json->max_size([$maximum_string_size]) 662 663 $max_size = $json->get_max_size 664 665 Set the maximum length a JSON text may have (in bytes) where decoding is 666 being attempted. The default is 0, meaning no limit. When "decode" is 667 called on a string that is longer then this many bytes, it will not 668 attempt to decode the string but throw an exception. This setting has no 669 effect on "encode" (yet). 670 671 If no argument is given, the limit check will be deactivated (same as 672 when 0 is specified). 673 674 See "SECURITY CONSIDERATIONS" in JSON::XS, below, for more info on why 675 this is useful. 676 677 encode 678 $json_text = $json->encode($perl_scalar) 679 680 Converts the given Perl data structure (a simple scalar or a reference 681 to a hash or array) to its JSON representation. Simple scalars will be 682 converted into JSON string or number sequences, while references to 683 arrays become JSON arrays and references to hashes become JSON objects. 684 Undefined Perl values (e.g. "undef") become JSON "null" values. 685 References to the integers 0 and 1 are converted into "true" and 686 "false". 687 688 decode 689 $perl_scalar = $json->decode($json_text) 690 691 The opposite of "encode": expects a JSON text and tries to parse it, 692 returning the resulting simple scalar or reference. Croaks on error. 693 694 JSON numbers and strings become simple Perl scalars. JSON arrays become 695 Perl arrayrefs and JSON objects become Perl hashrefs. "true" becomes 1 696 ("JSON::true"), "false" becomes 0 ("JSON::false") and "null" becomes 697 "undef". 698 699 decode_prefix 700 ($perl_scalar, $characters) = $json->decode_prefix($json_text) 701 702 This works like the "decode" method, but instead of raising an exception 703 when there is trailing garbage after the first JSON object, it will 704 silently stop parsing there and return the number of characters consumed 705 so far. 706 707 JSON->new->decode_prefix ("[1] the tail") 708 => ([], 3) 709 710 See to "OBJECT-ORIENTED INTERFACE" in JSON::XS 711 712 property 713 $boolean = $json->property($property_name) 714 715 Returns a boolean value about above some properties. 716 717 The available properties are "ascii", "latin1", "utf8", 718 "indent","space_before", "space_after", "relaxed", "canonical", 719 "allow_nonref", "allow_unknown", "allow_blessed", "convert_blessed", 720 "shrink", "max_depth" and "max_size". 721 722 $boolean = $json->property('utf8'); 723 => 0 724 $json->utf8; 725 $boolean = $json->property('utf8'); 726 => 1 727 728 Sets the propery with a given boolean value. 729 730 $json = $json->property($property_name => $boolean); 731 732 With no argumnt, it returns all the above properties as a hash 733 reference. 734 735 $flag_hashref = $json->property(); 736 737INCREMENTAL PARSING 738 In JSON::XS 2.2, incremental parsing feature of JSON texts was 739 implemented. Please check to "INCREMENTAL PARSING" in JSON::XS. 740 741 [void, scalar or list context] = $json->incr_parse ([$string]) 742 This is the central parsing function. It can both append new text 743 and extract objects from the stream accumulated so far (both of 744 these functions are optional). 745 746 If $string is given, then this string is appended to the already 747 existing JSON fragment stored in the $json object. 748 749 After that, if the function is called in void context, it will 750 simply return without doing anything further. This can be used to 751 add more text in as many chunks as you want. 752 753 If the method is called in scalar context, then it will try to 754 extract exactly *one* JSON object. If that is successful, it will 755 return this object, otherwise it will return "undef". If there is a 756 parse error, this method will croak just as "decode" would do (one 757 can then use "incr_skip" to skip the errornous part). This is the 758 most common way of using the method. 759 760 And finally, in list context, it will try to extract as many objects 761 from the stream as it can find and return them, or the empty list 762 otherwise. For this to work, there must be no separators between the 763 JSON objects or arrays, instead they must be concatenated 764 back-to-back. If an error occurs, an exception will be raised as in 765 the scalar context case. Note that in this case, any 766 previously-parsed JSON texts will be lost. 767 768 $lvalue_string = $json->incr_text 769 This method returns the currently stored JSON fragment as an lvalue, 770 that is, you can manipulate it. This *only* works when a preceding 771 call to "incr_parse" in *scalar context* successfully returned an 772 object. Under all other circumstances you must not call this 773 function (I mean it. although in simple tests it might actually 774 work, it *will* fail under real world conditions). As a special 775 exception, you can also call this method before having parsed 776 anything. 777 778 This function is useful in two cases: a) finding the trailing text 779 after a JSON object or b) parsing multiple JSON objects separated by 780 non-JSON text (such as commas). 781 782 In Perl 5.005, "lvalue" attribute is not available. You must write 783 codes like the below: 784 785 $string = $json->incr_text; 786 $string =~ s/\s*,\s*//; 787 $json->incr_text( $string ); 788 789 $json->incr_skip 790 This will reset the state of the incremental parser and will remove 791 the parsed text from the input buffer. This is useful after 792 "incr_parse" died, in which case the input buffer and incremental 793 parser state is left unchanged, to skip the text parsed so far and 794 to reset the parse state. 795 796 $json->incr_reset 797 This completely resets the incremental parser, that is, after this 798 call, it will be as if the parser had never parsed anything. 799 800 This is useful if you want ot repeatedly parse JSON objects and want 801 to ignore any trailing data, which means you have to reset the 802 parser after each successful decode. 803 804JSON::PP SUPPORT METHODS 805 The below methods are JSON::PP own methods, so when "JSON" works with 806 JSON::PP (i.e. the created object is a JSON::PP object), available. See 807 to "JSON::PP OWN METHODS" in JSON::PP in detail. 808 809 If you use "JSON" with additonal "-support_by_pp", some methods are 810 available even with JSON::XS. See to "USE PP FEATURES EVEN THOUGH XS 811 BACKEND". 812 813 BEING { $ENV{PERL_JSON_BACKEND} = 'JSON::XS' } 814 815 use JSON -support_by_pp; 816 817 my $json = new JSON; 818 $json->allow_nonref->escape_slash->encode("/"); 819 820 # functional interfaces too. 821 print to_json(["/"], {escape_slash => 1}); 822 print from_json('["foo"]', {utf8 => 1}); 823 824 If you do not want to all functions but "-support_by_pp", use 825 "-no_export". 826 827 use JSON -support_by_pp, -no_export; 828 # functional interfaces are not exported. 829 830 allow_singlequote 831 $json = $json->allow_singlequote([$enable]) 832 833 If $enable is true (or missing), then "decode" will accept any JSON 834 strings quoted by single quotations that are invalid JSON format. 835 836 $json->allow_singlequote->decode({"foo":'bar'}); 837 $json->allow_singlequote->decode({'foo':"bar"}); 838 $json->allow_singlequote->decode({'foo':'bar'}); 839 840 As same as the "relaxed" option, this option may be used to parse 841 application-specific files written by humans. 842 843 allow_barekey 844 $json = $json->allow_barekey([$enable]) 845 846 If $enable is true (or missing), then "decode" will accept bare keys of 847 JSON object that are invalid JSON format. 848 849 As same as the "relaxed" option, this option may be used to parse 850 application-specific files written by humans. 851 852 $json->allow_barekey->decode('{foo:"bar"}'); 853 854 allow_bignum 855 $json = $json->allow_bignum([$enable]) 856 857 If $enable is true (or missing), then "decode" will convert the big 858 integer Perl cannot handle as integer into a Math::BigInt object and 859 convert a floating number (any) into a Math::BigFloat. 860 861 On the contary, "encode" converts "Math::BigInt" objects and 862 "Math::BigFloat" objects into JSON numbers with "allow_blessed" enable. 863 864 $json->allow_nonref->allow_blessed->allow_bignum; 865 $bigfloat = $json->decode('2.000000000000000000000000001'); 866 print $json->encode($bigfloat); 867 # => 2.000000000000000000000000001 868 869 See to MAPPING aboout the conversion of JSON number. 870 871 loose 872 $json = $json->loose([$enable]) 873 874 The unescaped [\x00-\x1f\x22\x2f\x5c] strings are invalid in JSON 875 strings and the module doesn't allow to "decode" to these (except for 876 \x2f). If $enable is true (or missing), then "decode" will accept these 877 unescaped strings. 878 879 $json->loose->decode(qq|["abc 880 def"]|); 881 882 See to "JSON::PP OWN METHODS" in JSON::PP. 883 884 escape_slash 885 $json = $json->escape_slash([$enable]) 886 887 According to JSON Grammar, *slash* (U+002F) is escaped. But by default 888 JSON backend modules encode strings without escaping slash. 889 890 If $enable is true (or missing), then "encode" will escape slashes. 891 892 indent_length 893 $json = $json->indent_length($length) 894 895 With JSON::XS, The indent space length is 3 and cannot be changed. With 896 JSON::PP, it sets the indent space length with the given $length. The 897 default is 3. The acceptable range is 0 to 15. 898 899 sort_by 900 $json = $json->sort_by($function_name) 901 $json = $json->sort_by($subroutine_ref) 902 903 If $function_name or $subroutine_ref are set, its sort routine are used. 904 905 $js = $pc->sort_by(sub { $JSON::PP::a cmp $JSON::PP::b })->encode($obj); 906 # is($js, q|{"a":1,"b":2,"c":3,"d":4,"e":5,"f":6,"g":7,"h":8,"i":9}|); 907 908 $js = $pc->sort_by('own_sort')->encode($obj); 909 # is($js, q|{"a":1,"b":2,"c":3,"d":4,"e":5,"f":6,"g":7,"h":8,"i":9}|); 910 911 sub JSON::PP::own_sort { $JSON::PP::a cmp $JSON::PP::b } 912 913 As the sorting routine runs in the JSON::PP scope, the given subroutine 914 name and the special variables $a, $b will begin with 'JSON::PP::'. 915 916 If $integer is set, then the effect is same as "canonical" on. 917 918 See to "JSON::PP OWN METHODS" in JSON::PP. 919 920MAPPING 921 This section is copied from JSON::XS and modified to "JSON". JSON::XS 922 and JSON::PP mapping mechanisms are almost equivalent. 923 924 See to "MAPPING" in JSON::XS. 925 926 JSON -> PERL 927 object 928 A JSON object becomes a reference to a hash in Perl. No ordering of 929 object keys is preserved (JSON does not preserver object key 930 ordering itself). 931 932 array 933 A JSON array becomes a reference to an array in Perl. 934 935 string 936 A JSON string becomes a string scalar in Perl - Unicode codepoints 937 in JSON are represented by the same codepoints in the Perl string, 938 so no manual decoding is necessary. 939 940 number 941 A JSON number becomes either an integer, numeric (floating point) or 942 string scalar in perl, depending on its range and any fractional 943 parts. On the Perl level, there is no difference between those as 944 Perl handles all the conversion details, but an integer may take 945 slightly less memory and might represent more values exactly than 946 floating point numbers. 947 948 If the number consists of digits only, "JSON" will try to represent 949 it as an integer value. If that fails, it will try to represent it 950 as a numeric (floating point) value if that is possible without loss 951 of precision. Otherwise it will preserve the number as a string 952 value (in which case you lose roundtripping ability, as the JSON 953 number will be re-encoded toa JSON string). 954 955 Numbers containing a fractional or exponential part will always be 956 represented as numeric (floating point) values, possibly at a loss 957 of precision (in which case you might lose perfect roundtripping 958 ability, but the JSON number will still be re-encoded as a JSON 959 number). 960 961 If the backend is JSON::PP and "allow_bignum" is enable, the big 962 integers and the numeric can be optionally converted into 963 Math::BigInt and Math::BigFloat objects. 964 965 true, false 966 These JSON atoms become "JSON::true" and "JSON::false", 967 respectively. They are overloaded to act almost exactly like the 968 numbers 1 and 0. You can check wether a scalar is a JSON boolean by 969 using the "JSON::is_bool" function. 970 971 If "JSON::true" and "JSON::false" are used as strings or compared as 972 strings, they represent as "true" and "false" respectively. 973 974 print JSON::true . "\n"; 975 => true 976 print JSON::true + 1; 977 => 1 978 979 ok(JSON::true eq 'true'); 980 ok(JSON::true eq '1'); 981 ok(JSON::true == 1); 982 983 "JSON" will install these missing overloading features to the 984 backend modules. 985 986 null 987 A JSON null atom becomes "undef" in Perl. 988 989 "JSON::null" returns "unddef". 990 991 PERL -> JSON 992 The mapping from Perl to JSON is slightly more difficult, as Perl is a 993 truly typeless language, so we can only guess which JSON type is meant 994 by a Perl value. 995 996 hash references 997 Perl hash references become JSON objects. As there is no inherent 998 ordering in hash keys (or JSON objects), they will usually be 999 encoded in a pseudo-random order that can change between runs of the 1000 same program but stays generally the same within a single run of a 1001 program. "JSON" optionally sort the hash keys (determined by the 1002 *canonical* flag), so the same datastructure will serialise to the 1003 same JSON text (given same settings and version of JSON::XS), but 1004 this incurs a runtime overhead and is only rarely useful, e.g. when 1005 you want to compare some JSON text against another for equality. 1006 1007 In future, the ordered object feature will be added to JSON::PP 1008 using "tie" mechanism. 1009 1010 array references 1011 Perl array references become JSON arrays. 1012 1013 other references 1014 Other unblessed references are generally not allowed and will cause 1015 an exception to be thrown, except for references to the integers 0 1016 and 1, which get turned into "false" and "true" atoms in JSON. You 1017 can also use "JSON::false" and "JSON::true" to improve readability. 1018 1019 to_json [\0,JSON::true] # yields [false,true] 1020 1021 JSON::true, JSON::false, JSON::null 1022 These special values become JSON true and JSON false values, 1023 respectively. You can also use "\1" and "\0" directly if you want. 1024 1025 JSON::null returns "undef". 1026 1027 blessed objects 1028 Blessed objects are not directly representable in JSON. See the 1029 "allow_blessed" and "convert_blessed" methods on various options on 1030 how to deal with this: basically, you can choose between throwing an 1031 exception, encoding the reference as if it weren't blessed, or 1032 provide your own serialiser method. 1033 1034 With "convert_blessed_universally" mode, "encode" converts blessed 1035 hash references or blessed array references (contains other blessed 1036 references) into JSON members and arrays. 1037 1038 use JSON -convert_blessed_universally; 1039 JSON->new->allow_blessed->convert_blessed->encode( $blessed_object ); 1040 1041 See to convert_blessed. 1042 1043 simple scalars 1044 Simple Perl scalars (any scalar that is not a reference) are the 1045 most difficult objects to encode: JSON::XS and JSON::PP will encode 1046 undefined scalars as JSON "null" values, scalars that have last been 1047 used in a string context before encoding as JSON strings, and 1048 anything else as number value: 1049 1050 # dump as number 1051 encode_json [2] # yields [2] 1052 encode_json [-3.0e17] # yields [-3e+17] 1053 my $value = 5; encode_json [$value] # yields [5] 1054 1055 # used as string, so dump as string 1056 print $value; 1057 encode_json [$value] # yields ["5"] 1058 1059 # undef becomes null 1060 encode_json [undef] # yields [null] 1061 1062 You can force the type to be a string by stringifying it: 1063 1064 my $x = 3.1; # some variable containing a number 1065 "$x"; # stringified 1066 $x .= ""; # another, more awkward way to stringify 1067 print $x; # perl does it for you, too, quite often 1068 1069 You can force the type to be a number by numifying it: 1070 1071 my $x = "3"; # some variable containing a string 1072 $x += 0; # numify it, ensuring it will be dumped as a number 1073 $x *= 1; # same thing, the choise is yours. 1074 1075 You can not currently force the type in other, less obscure, ways. 1076 1077 Big Number 1078 If the backend is JSON::PP and "allow_bignum" is enable, "encode" 1079 converts "Math::BigInt" objects and "Math::BigFloat" objects into 1080 JSON numbers. 1081 1082JSON and ECMAscript 1083 See to "JSON and ECMAscript" in JSON::XS. 1084 1085JSON and YAML 1086 JSON is not a subset of YAML. See to "JSON and YAML" in JSON::XS. 1087 1088BACKEND MODULE DECISION 1089 When you use "JSON", "JSON" tries to "use" JSON::XS. If this call 1090 failed, it will "uses" JSON::PP. The required JSON::XS version is *2.2* 1091 or later. 1092 1093 The "JSON" constructor method returns an object inherited from the 1094 backend module, and JSON::XS object is a blessed scaler reference while 1095 JSON::PP is a blessed hash reference. 1096 1097 So, your program should not depend on the backend module, especially 1098 returned objects should not be modified. 1099 1100 my $json = JSON->new; # XS or PP? 1101 $json->{stash} = 'this is xs object'; # this code may raise an error! 1102 1103 To check the backend module, there are some methods - "backend", "is_pp" 1104 and "is_xs". 1105 1106 JSON->backend; # 'JSON::XS' or 'JSON::PP' 1107 1108 JSON->backend->is_pp: # 0 or 1 1109 1110 JSON->backend->is_xs: # 1 or 0 1111 1112 $json->is_xs; # 1 or 0 1113 1114 $json->is_pp; # 0 or 1 1115 1116 If you set an enviornment variable "PERL_JSON_BACKEND", The calling 1117 action will be changed. 1118 1119 PERL_JSON_BACKEND = 0 or PERL_JSON_BACKEND = 'JSON::PP' 1120 Always use JSON::PP 1121 1122 PERL_JSON_BACKEND == 1 or PERL_JSON_BACKEND = 'JSON::XS,JSON::PP' 1123 (The default) Use compiled JSON::XS if it is properly compiled & 1124 installed, otherwise use JSON::PP. 1125 1126 PERL_JSON_BACKEND == 2 or PERL_JSON_BACKEND = 'JSON::XS' 1127 Always use compiled JSON::XS, die if it isn't properly compiled & 1128 installed. 1129 1130 These ideas come from DBI::PurePerl mechanism. 1131 1132 example: 1133 1134 BEGIN { $ENV{PERL_JSON_BACKEND} = 'JSON::PP' } 1135 use JSON; # always uses JSON::PP 1136 1137 In future, it may be able to specify another module. 1138 1139USE PP FEATURES EVEN THOUGH XS BACKEND 1140 Many methods are available with either JSON::XS or JSON::PP and when the 1141 backend module is JSON::XS, if any JSON::PP specific (i.e. JSON::XS 1142 unspported) method is called, it will "warn" and be noop. 1143 1144 But If you "use" "JSON" passing the optional string "-support_by_pp", it 1145 makes a part of those unupported methods available. This feature is 1146 achieved by using JSON::PP in "de/encode". 1147 1148 BEGIN { $ENV{PERL_JSON_BACKEND} = 2 } # with JSON::XS 1149 use JSON -support_by_pp; 1150 my $json = new JSON; 1151 $json->allow_nonref->escape_slash->encode("/"); 1152 1153 At this time, the returned object is a "JSON::Backend::XS::Supportable" 1154 object (re-blessed XS object), and by checking JSON::XS unsupported 1155 flags in de/encoding, can support some unsupported methods - "loose", 1156 "allow_bignum", "allow_barekey", "allow_singlequote", "escape_slash", 1157 "as_nonblessed" and "indent_length". 1158 1159 When any unsupported methods are not enable, "XS de/encode" will be used 1160 as is. The switch is achieved by changing the symbolic tables. 1161 1162 "-support_by_pp" is effective only when the backend module is JSON::XS 1163 and it makes the de/encoding speed down a bit. 1164 1165 See to "JSON::PP SUPPORT METHODS". 1166 1167INCOMPATIBLE CHANGES TO OLD VERSION 1168 There are big incompatibility between new version (2.00) and old (1.xx). 1169 If you use old "JSON" 1.xx in your code, please check it. 1170 1171 See to "Transition ways from 1.xx to 2.xx." 1172 1173 jsonToObj and objToJson are obsoleted. 1174 Non Perl-style name "jsonToObj" and "objToJson" are obsoleted (but 1175 not yet deleted from the source). If you use these functions in your 1176 code, please replace them with "from_json" and "to_json". 1177 1178 Global variables are no longer available. 1179 "JSON" class variables - $JSON::AUTOCONVERT, $JSON::BareKey, etc... 1180 - are not avaliable any longer. Instead, various features can be 1181 used through object methods. 1182 1183 Package JSON::Converter and JSON::Parser are deleted. 1184 Now "JSON" bundles with JSON::PP which can handle JSON more properly 1185 than them. 1186 1187 Package JSON::NotString is deleted. 1188 There was "JSON::NotString" class which represents JSON value 1189 "true", "false", "null" and numbers. It was deleted and replaced by 1190 "JSON::Boolean". 1191 1192 "JSON::Boolean" represents "true" and "false". 1193 1194 "JSON::Boolean" does not represent "null". 1195 1196 "JSON::null" returns "undef". 1197 1198 "JSON" makes JSON::XS::Boolean and JSON::PP::Boolean is-a relation 1199 to JSON::Boolean. 1200 1201 function JSON::Number is obsoleted. 1202 "JSON::Number" is now needless because JSON::XS and JSON::PP have 1203 round-trip integrity. 1204 1205 JSONRPC modules are deleted. 1206 Perl implementation of JSON-RPC protocol - "JSONRPC ", 1207 "JSONRPC::Transport::HTTP" and "Apache::JSONRPC " are deleted in 1208 this distribution. Instead of them, there is JSON::RPC which 1209 supports JSON-RPC protocol version 1.1. 1210 1211 Transition ways from 1.xx to 2.xx. 1212 You should set "suport_by_pp" mode firstly, because it is always 1213 successful for the below codes even with JSON::XS. 1214 1215 use JSON -support_by_pp; 1216 1217 Exported jsonToObj (simple) 1218 from_json($json_text); 1219 1220 Exported objToJson (simple) 1221 to_json($perl_scalar); 1222 1223 Exported jsonToObj (advanced) 1224 $flags = {allow_barekey => 1, allow_singlequote => 1}; 1225 from_json($json_text, $flags); 1226 1227 equivalent to: 1228 1229 $JSON::BareKey = 1; 1230 $JSON::QuotApos = 1; 1231 jsonToObj($json_text); 1232 1233 Exported objToJson (advanced) 1234 $flags = {allow_blessed => 1, allow_barekey => 1}; 1235 to_json($perl_scalar, $flags); 1236 1237 equivalent to: 1238 1239 $JSON::BareKey = 1; 1240 objToJson($perl_scalar); 1241 1242 jsonToObj as object method 1243 $json->decode($json_text); 1244 1245 objToJson as object method 1246 $json->encode($perl_scalar); 1247 1248 new method with parameters 1249 The "new" method in 2.x takes any parameters no longer. You can set 1250 parameters instead; 1251 1252 $json = JSON->new->pretty; 1253 1254 $JSON::Pretty, $JSON::Indent, $JSON::Delimiter 1255 If "indent" is enable, that menas $JSON::Pretty flag set. And 1256 $JSON::Delimiter was substituted by "space_before" and 1257 "space_after". In conclusion: 1258 1259 $json->indent->space_before->space_after; 1260 1261 Equivalent to: 1262 1263 $json->pretty; 1264 1265 To change indent length, use "indent_length". 1266 1267 (Only with JSON::PP, if "-support_by_pp" is not used.) 1268 1269 $json->pretty->indent_length(2)->encode($perl_scalar); 1270 1271 $JSON::BareKey 1272 (Only with JSON::PP, if "-support_by_pp" is not used.) 1273 1274 $json->allow_barekey->decode($json_text) 1275 1276 $JSON::ConvBlessed 1277 use "-convert_blessed_universally". See to convert_blessed. 1278 1279 $JSON::QuotApos 1280 (Only with JSON::PP, if "-support_by_pp" is not used.) 1281 1282 $json->allow_singlequote->decode($json_text) 1283 1284 $JSON::SingleQuote 1285 Disable. "JSON" does not make such a invalid JSON string any longer. 1286 1287 $JSON::KeySort 1288 $json->canonical->encode($perl_scalar) 1289 1290 This is the ascii sort. 1291 1292 If you want to use with your own sort routine, check the "sort_by" 1293 method. 1294 1295 (Only with JSON::PP, even if "-support_by_pp" is used currently.) 1296 1297 $json->sort_by($sort_routine_ref)->encode($perl_scalar) 1298 1299 $json->sort_by(sub { $JSON::PP::a <=> $JSON::PP::b })->encode($perl_scalar) 1300 1301 Can't access $a and $b but $JSON::PP::a and $JSON::PP::b. 1302 1303 $JSON::SkipInvalid 1304 $json->allow_unknown 1305 1306 $JSON::AUTOCONVERT 1307 Needless. "JSON" backend modules have the round-trip integrity. 1308 1309 $JSON::UTF8 1310 Needless because "JSON" (JSON::XS/JSON::PP) sets the UTF8 flag on 1311 properly. 1312 1313 # With UTF8-flagged strings 1314 1315 $json->allow_nonref; 1316 $str = chr(1000); # UTF8-flagged 1317 1318 $json_text = $json->utf8(0)->encode($str); 1319 utf8::is_utf8($json_text); 1320 # true 1321 $json_text = $json->utf8(1)->encode($str); 1322 utf8::is_utf8($json_text); 1323 # false 1324 1325 $str = '"' . chr(1000) . '"'; # UTF8-flagged 1326 1327 $perl_scalar = $json->utf8(0)->decode($str); 1328 utf8::is_utf8($perl_scalar); 1329 # true 1330 $perl_scalar = $json->utf8(1)->decode($str); 1331 # died because of 'Wide character in subroutine' 1332 1333 See to "A FEW NOTES ON UNICODE AND PERL" in JSON::XS. 1334 1335 $JSON::UnMapping 1336 Disable. See to MAPPING. 1337 1338 $JSON::SelfConvert 1339 This option was deleted. Instead of it, if a givien blessed object 1340 has the "TO_JSON" method, "TO_JSON" will be executed with 1341 "convert_blessed". 1342 1343 $json->convert_blessed->encode($bleesed_hashref_or_arrayref) 1344 # if need, call allow_blessed 1345 1346 Note that it was "toJson" in old version, but now not "toJson" but 1347 "TO_JSON". 1348 1349TODO 1350 example programs 1351 1352THREADS 1353 No test with JSON::PP. If with JSON::XS, See to "THREADS" in JSON::XS. 1354 1355BUGS 1356 Please report bugs relevant to "JSON" to <makamaka[at]cpan.org>. 1357 1358SEE ALSO 1359 Most of the document is copied and modified from JSON::XS doc. 1360 1361 JSON::XS, JSON::PP 1362 1363 "RFC4627"(<http://www.ietf.org/rfc/rfc4627.txt>) 1364 1365AUTHOR 1366 Makamaka Hannyaharamitu, <makamaka[at]cpan.org> 1367 1368 JSON::XS was written by Marc Lehmann <schmorp[at]schmorp.de> 1369 1370 The relese of this new version owes to the courtesy of Marc Lehmann. 1371 1372COPYRIGHT AND LICENSE 1373 Copyright 2005-2009 by Makamaka Hannyaharamitu 1374 1375 This library is free software; you can redistribute it and/or modify it 1376 under the same terms as Perl itself. 1377 1378