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

Comparing JSON-XS/README (file contents):
Revision 1.25 by root, Wed Apr 16 18:38:38 2008 UTC vs.
Revision 1.28 by root, Mon Sep 29 03:09:27 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
… …
44 to write yet another JSON module? While it seems there are many JSON 44 to write yet another JSON module? While it seems there are many JSON
45 modules, none of them correctly handle all corner cases, and in most 45 modules, none of them correctly handle all corner cases, and in most
46 cases their maintainers are unresponsive, gone missing, or not listening 46 cases their maintainers are unresponsive, gone missing, or not listening
47 to bug reports for other reasons. 47 to bug reports for other reasons.
48 48
49 See COMPARISON, below, for a comparison to some other JSON modules.
50
51 See MAPPING, below, on how JSON::XS maps perl values to JSON values and 49 See MAPPING, below, on how JSON::XS maps perl values to JSON values and
52 vice versa. 50 vice versa.
53 51
54 FEATURES 52 FEATURES
55 * correct Unicode handling 53 * correct Unicode handling
… …
57 This module knows how to handle Unicode, documents how and when it 55 This module knows how to handle Unicode, documents how and when it
58 does so, and even documents what "correct" means. 56 does so, and even documents what "correct" means.
59 57
60 * round-trip integrity 58 * round-trip integrity
61 59
62 When you serialise a perl data structure using only datatypes 60 When you serialise a perl data structure using only data types
63 supported by JSON, the deserialised data structure is identical on 61 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" 62 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 63 just because it looks like a number). There minor *are* exceptions
66 to this, read the MAPPING section below to learn about those. 64 to this, read the MAPPING section below to learn about those.
67 65
… …
78 too. 76 too.
79 77
80 * simple to use 78 * simple to use
81 79
82 This module has both a simple functional interface as well as an 80 This module has both a simple functional interface as well as an
83 objetc oriented interface interface. 81 object oriented interface interface.
84 82
85 * reasonably versatile output formats 83 * reasonably versatile output formats
86 84
87 You can choose between the most compact guaranteed-single-line 85 You can choose between the most compact guaranteed-single-line
88 format possible (nice for simple line-based protocols), a pure-ascii 86 format possible (nice for simple line-based protocols), a pure-ASCII
89 format (for when your transport is not 8-bit clean, still supports 87 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 88 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 89 want to read that stuff). Or you can combine those features in
92 whatever way you like. 90 whatever way you like.
93 91
… …
101 99
102 This function call is functionally identical to: 100 This function call is functionally identical to:
103 101
104 $json_text = JSON::XS->new->utf8->encode ($perl_scalar) 102 $json_text = JSON::XS->new->utf8->encode ($perl_scalar)
105 103
106 except being faster. 104 Except being faster.
107 105
108 $perl_scalar = decode_json $json_text 106 $perl_scalar = decode_json $json_text
109 The opposite of "encode_json": expects an UTF-8 (binary) string and 107 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 108 tries to parse that as an UTF-8 encoded JSON text, returning the
111 resulting reference. Croaks on error. 109 resulting reference. Croaks on error.
112 110
113 This function call is functionally identical to: 111 This function call is functionally identical to:
114 112
115 $perl_scalar = JSON::XS->new->utf8->decode ($json_text) 113 $perl_scalar = JSON::XS->new->utf8->decode ($json_text)
116 114
117 except being faster. 115 Except being faster.
118 116
119 $is_boolean = JSON::XS::is_bool $scalar 117 $is_boolean = JSON::XS::is_bool $scalar
120 Returns true if the passed scalar represents either JSON::XS::true 118 Returns true if the passed scalar represents either JSON::XS::true
121 or JSON::XS::false, two constants that act like 1 and 0, 119 or JSON::XS::false, two constants that act like 1 and 0,
122 respectively and are used to represent JSON "true" and "false" 120 respectively and are used to represent JSON "true" and "false"
… …
152 150
153 If you didn't know about that flag, just the better, pretend it 151 If you didn't know about that flag, just the better, pretend it
154 doesn't exist. 152 doesn't exist.
155 153
156 4. A "Unicode String" is simply a string where each character can be 154 4. A "Unicode String" is simply a string where each character can be
157 validly interpreted as a Unicode codepoint. 155 validly interpreted as a Unicode code point.
158 If you have UTF-8 encoded data, it is no longer a Unicode string, 156 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. 157 but a Unicode string encoded in UTF-8, giving you a binary string.
160 158
161 5. A string containing "high" (> 255) character values is *not* a UTF-8 159 5. A string containing "high" (> 255) character values is *not* a UTF-8
162 string. 160 string.
… …
623 621
624 JSON::XS->new->decode_prefix ("[1] the tail") 622 JSON::XS->new->decode_prefix ("[1] the tail")
625 => ([], 3) 623 => ([], 3)
626 624
627INCREMENTAL PARSING 625INCREMENTAL PARSING
628 [This section and the API it details is still EXPERIMENTAL]
629
630 In some cases, there is the need for incremental parsing of JSON texts. 626 In some cases, there is the need for incremental parsing of JSON texts.
631 While this module always has to keep both JSON text and resulting Perl 627 While this module always has to keep both JSON text and resulting Perl
632 data structure in memory at one time, it does allow you to parse a JSON 628 data structure in memory at one time, it does allow you to parse a JSON
633 stream incrementally. It does so by accumulating text until it has a 629 stream incrementally. It does so by accumulating text until it has a
634 full JSON object, which it then can decode. This process is similar to 630 full JSON object, which it then can decode. This process is similar to
635 using "decode_prefix" to see if a full JSON object is available, but is 631 using "decode_prefix" to see if a full JSON object is available, but is
636 much more efficient (JSON::XS will only attempt to parse the JSON text 632 much more efficient (and can be implemented with a minimum of method
637 once it is sure it has enough text to get a decisive result, using a 633 calls).
638 very simple but truly incremental parser).
639 634
640 The following two methods deal with this. 635 JSON::XS will only attempt to parse the JSON text once it is sure it has
636 enough text to get a decisive result, using a very simple but truly
637 incremental parser. This means that it sometimes won't stop as early as
638 the full parser, for example, it doesn't detect parenthese mismatches.
639 The only thing it guarantees is that it starts decoding as soon as a
640 syntactically valid JSON text has been seen. This means you need to set
641 resource limits (e.g. "max_size") to ensure the parser will stop parsing
642 in the presence if syntax errors.
643
644 The following methods implement this incremental parser.
641 645
642 [void, scalar or list context] = $json->incr_parse ([$string]) 646 [void, scalar or list context] = $json->incr_parse ([$string])
643 This is the central parsing function. It can both append new text 647 This is the central parsing function. It can both append new text
644 and extract objects from the stream accumulated so far (both of 648 and extract objects from the stream accumulated so far (both of
645 these functions are optional). 649 these functions are optional).
… …
684 This will reset the state of the incremental parser and will remove 688 This will reset the state of the incremental parser and will remove
685 the parsed text from the input buffer. This is useful after 689 the parsed text from the input buffer. This is useful after
686 "incr_parse" died, in which case the input buffer and incremental 690 "incr_parse" died, in which case the input buffer and incremental
687 parser state is left unchanged, to skip the text parsed so far and 691 parser state is left unchanged, to skip the text parsed so far and
688 to reset the parse state. 692 to reset the parse state.
693
694 $json->incr_reset
695 This completely resets the incremental parser, that is, after this
696 call, it will be as if the parser had never parsed anything.
697
698 This is useful if you want ot repeatedly parse JSON objects and want
699 to ignore any trailing data, which means you have to reset the
700 parser after each successful decode.
689 701
690 LIMITATIONS 702 LIMITATIONS
691 All options that affect decoding are supported, except "allow_nonref". 703 All options that affect decoding are supported, except "allow_nonref".
692 The reason for this is that it cannot be made to work sensibly: JSON 704 The reason for this is that it cannot be made to work sensibly: JSON
693 objects and arrays are self-delimited, i.e. you can concatenate them 705 objects and arrays are self-delimited, i.e. you can concatenate them
… …
913 an exception to be thrown, except for references to the integers 0 925 an exception to be thrown, except for references to the integers 0
914 and 1, which get turned into "false" and "true" atoms in JSON. You 926 and 1, which get turned into "false" and "true" atoms in JSON. You
915 can also use "JSON::XS::false" and "JSON::XS::true" to improve 927 can also use "JSON::XS::false" and "JSON::XS::true" to improve
916 readability. 928 readability.
917 929
918 encode_json [\0,JSON::XS::true] # yields [false,true] 930 encode_json [\0, JSON::XS::true] # yields [false,true]
919 931
920 JSON::XS::true, JSON::XS::false 932 JSON::XS::true, JSON::XS::false
921 These special values become JSON true and JSON false values, 933 These special values become JSON true and JSON false values,
922 respectively. You can also use "\1" and "\0" directly if you want. 934 respectively. You can also use "\1" and "\0" directly if you want.
923 935
… …
1218 1230
1219 (It might actually work, but you have been warned). 1231 (It might actually work, but you have been warned).
1220 1232
1221BUGS 1233BUGS
1222 While the goal of this module is to be correct, that unfortunately does 1234 While the goal of this module is to be correct, that unfortunately does
1223 not mean it's bug-free, only that I think its design is bug-free. It is 1235 not mean it's bug-free, only that I think its design is bug-free. If you
1224 still relatively early in its development. If you keep reporting bugs
1225 they will be fixed swiftly, though. 1236 keep reporting bugs they will be fixed swiftly, though.
1226 1237
1227 Please refrain from using rt.cpan.org or any other bug reporting 1238 Please refrain from using rt.cpan.org or any other bug reporting
1228 service. I put the contact address into my modules for a reason. 1239 service. I put the contact address into my modules for a reason.
1229 1240
1230SEE ALSO 1241SEE ALSO

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines