ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/JSON-XS/README
(Generate patch)

Comparing JSON-XS/README (file contents):
Revision 1.24 by root, Thu Mar 27 06:37:35 2008 UTC vs.
Revision 1.26 by root, Tue Jun 3 06:43:45 2008 UTC

32 primary goal is to be *correct* and its secondary goal is to be *fast*. 32 primary goal is to be *correct* and its secondary goal is to be *fast*.
33 To reach the latter goal it was written in C. 33 To reach the latter goal it was written in C.
34 34
35 Beginning with version 2.0 of the JSON module, when both JSON and 35 Beginning with version 2.0 of the JSON module, when both JSON and
36 JSON::XS are installed, then JSON will fall back on JSON::XS (this can 36 JSON::XS are installed, then JSON will fall back on JSON::XS (this can
37 be overriden) with no overhead due to emulation (by inheritign 37 be overridden) with no overhead due to emulation (by inheriting
38 constructor and methods). If JSON::XS is not available, it will fall 38 constructor and methods). If JSON::XS is not available, it will fall
39 back to the compatible JSON::PP module as backend, so using JSON instead 39 back to the compatible JSON::PP module as backend, so using JSON instead
40 of JSON::XS gives you a portable JSON API that can be fast when you need 40 of JSON::XS gives you a portable JSON API that can be fast when you need
41 and doesn't require a C compiler when that is a problem. 41 and doesn't require a C compiler when that is a problem.
42 42
57 This module knows how to handle Unicode, documents how and when it 57 This module knows how to handle Unicode, documents how and when it
58 does so, and even documents what "correct" means. 58 does so, and even documents what "correct" means.
59 59
60 * round-trip integrity 60 * round-trip integrity
61 61
62 When you serialise a perl data structure using only datatypes 62 When you serialise a perl data structure using only data types
63 supported by JSON, the deserialised data structure is identical on 63 supported by JSON, the deserialised data structure is identical on
64 the Perl level. (e.g. the string "2.0" doesn't suddenly become "2" 64 the Perl level. (e.g. the string "2.0" doesn't suddenly become "2"
65 just because it looks like a number). There minor *are* exceptions 65 just because it looks like a number). There minor *are* exceptions
66 to this, read the MAPPING section below to learn about those. 66 to this, read the MAPPING section below to learn about those.
67 67
78 too. 78 too.
79 79
80 * simple to use 80 * simple to use
81 81
82 This module has both a simple functional interface as well as an 82 This module has both a simple functional interface as well as an
83 objetc oriented interface interface. 83 object oriented interface interface.
84 84
85 * reasonably versatile output formats 85 * reasonably versatile output formats
86 86
87 You can choose between the most compact guaranteed-single-line 87 You can choose between the most compact guaranteed-single-line
88 format possible (nice for simple line-based protocols), a pure-ascii 88 format possible (nice for simple line-based protocols), a pure-ASCII
89 format (for when your transport is not 8-bit clean, still supports 89 format (for when your transport is not 8-bit clean, still supports
90 the whole Unicode range), or a pretty-printed format (for when you 90 the whole Unicode range), or a pretty-printed format (for when you
91 want to read that stuff). Or you can combine those features in 91 want to read that stuff). Or you can combine those features in
92 whatever way you like. 92 whatever way you like.
93 93
101 101
102 This function call is functionally identical to: 102 This function call is functionally identical to:
103 103
104 $json_text = JSON::XS->new->utf8->encode ($perl_scalar) 104 $json_text = JSON::XS->new->utf8->encode ($perl_scalar)
105 105
106 except being faster. 106 Except being faster.
107 107
108 $perl_scalar = decode_json $json_text 108 $perl_scalar = decode_json $json_text
109 The opposite of "encode_json": expects an UTF-8 (binary) string and 109 The opposite of "encode_json": expects an UTF-8 (binary) string and
110 tries to parse that as an UTF-8 encoded JSON text, returning the 110 tries to parse that as an UTF-8 encoded JSON text, returning the
111 resulting reference. Croaks on error. 111 resulting reference. Croaks on error.
112 112
113 This function call is functionally identical to: 113 This function call is functionally identical to:
114 114
115 $perl_scalar = JSON::XS->new->utf8->decode ($json_text) 115 $perl_scalar = JSON::XS->new->utf8->decode ($json_text)
116 116
117 except being faster. 117 Except being faster.
118 118
119 $is_boolean = JSON::XS::is_bool $scalar 119 $is_boolean = JSON::XS::is_bool $scalar
120 Returns true if the passed scalar represents either JSON::XS::true 120 Returns true if the passed scalar represents either JSON::XS::true
121 or JSON::XS::false, two constants that act like 1 and 0, 121 or JSON::XS::false, two constants that act like 1 and 0,
122 respectively and are used to represent JSON "true" and "false" 122 respectively and are used to represent JSON "true" and "false"
152 152
153 If you didn't know about that flag, just the better, pretend it 153 If you didn't know about that flag, just the better, pretend it
154 doesn't exist. 154 doesn't exist.
155 155
156 4. A "Unicode String" is simply a string where each character can be 156 4. A "Unicode String" is simply a string where each character can be
157 validly interpreted as a Unicode codepoint. 157 validly interpreted as a Unicode code point.
158 If you have UTF-8 encoded data, it is no longer a Unicode string, 158 If you have UTF-8 encoded data, it is no longer a Unicode string,
159 but a Unicode string encoded in UTF-8, giving you a binary string. 159 but a Unicode string encoded in UTF-8, giving you a binary string.
160 160
161 5. A string containing "high" (> 255) character values is *not* a UTF-8 161 5. A string containing "high" (> 255) character values is *not* a UTF-8
162 string. 162 string.
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)
607 623
608 JSON::XS->new->decode_prefix ("[1] the tail") 624 JSON::XS->new->decode_prefix ("[1] the tail")
609 => ([], 3) 625 => ([], 3)
610 626
611INCREMENTAL PARSING 627INCREMENTAL PARSING
612 [This section and the API it details is still EXPERIMENTAL]
613
614 In some cases, there is the need for incremental parsing of JSON texts. 628 In some cases, there is the need for incremental parsing of JSON texts.
615 While this module always has to keep both JSON text and resulting Perl 629 While this module always has to keep both JSON text and resulting Perl
616 data structure in memory at one time, it does allow you to parse a JSON 630 data structure in memory at one time, it does allow you to parse a JSON
617 stream incrementally. It does so by accumulating text until it has a 631 stream incrementally. It does so by accumulating text until it has a
618 full JSON object, which it then can decode. This process is similar to 632 full JSON object, which it then can decode. This process is similar to
668 This will reset the state of the incremental parser and will remove 682 This will reset the state of the incremental parser and will remove
669 the parsed text from the input buffer. This is useful after 683 the parsed text from the input buffer. This is useful after
670 "incr_parse" died, in which case the input buffer and incremental 684 "incr_parse" died, in which case the input buffer and incremental
671 parser state is left unchanged, to skip the text parsed so far and 685 parser state is left unchanged, to skip the text parsed so far and
672 to reset the parse state. 686 to reset the parse state.
687
688 $json->incr_reset
689 This completely resets the incremental parser, that is, after this
690 call, it will be as if the parser had never parsed anything.
691
692 This is useful if you want ot repeatedly parse JSON objects and want
693 to ignore any trailing data, which means you have to reset the
694 parser after each successful decode.
673 695
674 LIMITATIONS 696 LIMITATIONS
675 All options that affect decoding are supported, except "allow_nonref". 697 All options that affect decoding are supported, except "allow_nonref".
676 The reason for this is that it cannot be made to work sensibly: JSON 698 The reason for this is that it cannot be made to work sensibly: JSON
677 objects and arrays are self-delimited, i.e. you can concatenate them 699 objects and arrays are self-delimited, i.e. you can concatenate them
897 an exception to be thrown, except for references to the integers 0 919 an exception to be thrown, except for references to the integers 0
898 and 1, which get turned into "false" and "true" atoms in JSON. You 920 and 1, which get turned into "false" and "true" atoms in JSON. You
899 can also use "JSON::XS::false" and "JSON::XS::true" to improve 921 can also use "JSON::XS::false" and "JSON::XS::true" to improve
900 readability. 922 readability.
901 923
902 encode_json [\0,JSON::XS::true] # yields [false,true] 924 encode_json [\0, JSON::XS::true] # yields [false,true]
903 925
904 JSON::XS::true, JSON::XS::false 926 JSON::XS::true, JSON::XS::false
905 These special values become JSON true and JSON false values, 927 These special values become JSON true and JSON false values,
906 respectively. You can also use "\1" and "\0" directly if you want. 928 respectively. You can also use "\1" and "\0" directly if you want.
907 929
1097 1119
1098 First comes a comparison between various modules using a very short 1120 First comes a comparison between various modules using a very short
1099 single-line JSON string (also available at 1121 single-line JSON string (also available at
1100 <http://dist.schmorp.de/misc/json/short.json>). 1122 <http://dist.schmorp.de/misc/json/short.json>).
1101 1123
1102 {"method": "handleMessage", "params": ["user1", "we were just talking"], \ 1124 {"method": "handleMessage", "params": ["user1",
1103 "id": null, "array":[1,11,234,-5,1e5,1e7, true, false]} 1125 "we were just talking"], "id": null, "array":[1,11,234,-5,1e5,1e7,
1126 true, false]}
1104 1127
1105 It shows the number of encodes/decodes per second (JSON::XS uses the 1128 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 1129 functional interface, while JSON::XS/2 uses the OO interface with
1107 pretty-printing and hashkey sorting enabled, JSON::XS/3 enables shrink). 1130 pretty-printing and hashkey sorting enabled, JSON::XS/3 enables shrink).
1108 Higher is better: 1131 Higher is better:
1201 1224
1202 (It might actually work, but you have been warned). 1225 (It might actually work, but you have been warned).
1203 1226
1204BUGS 1227BUGS
1205 While the goal of this module is to be correct, that unfortunately does 1228 While the goal of this module is to be correct, that unfortunately does
1206 not mean it's bug-free, only that I think its design is bug-free. It is 1229 not mean it's bug-free, only that I think its design is bug-free. If you
1207 still relatively early in its development. If you keep reporting bugs
1208 they will be fixed swiftly, though. 1230 keep reporting bugs they will be fixed swiftly, though.
1209 1231
1210 Please refrain from using rt.cpan.org or any other bug reporting 1232 Please refrain from using rt.cpan.org or any other bug reporting
1211 service. I put the contact address into my modules for a reason. 1233 service. I put the contact address into my modules for a reason.
1212 1234
1213SEE ALSO 1235SEE ALSO

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines