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

Comparing JSON-XS/XS.pm (file contents):
Revision 1.103 by root, Tue Apr 29 16:07:56 2008 UTC vs.
Revision 1.110 by root, Sun Jul 20 17:55:19 2008 UTC

… …
37primary goal is to be I<correct> and its secondary goal is to be 37primary goal is to be I<correct> and its secondary goal is to be
38I<fast>. To reach the latter goal it was written in C. 38I<fast>. To reach the latter goal it was written in C.
39 39
40Beginning with version 2.0 of the JSON module, when both JSON and 40Beginning with version 2.0 of the JSON module, when both JSON and
41JSON::XS are installed, then JSON will fall back on JSON::XS (this can be 41JSON::XS are installed, then JSON will fall back on JSON::XS (this can be
42overriden) with no overhead due to emulation (by inheritign constructor 42overridden) with no overhead due to emulation (by inheriting constructor
43and methods). If JSON::XS is not available, it will fall back to the 43and methods). If JSON::XS is not available, it will fall back to the
44compatible JSON::PP module as backend, so using JSON instead of JSON::XS 44compatible JSON::PP module as backend, so using JSON instead of JSON::XS
45gives you a portable JSON API that can be fast when you need and doesn't 45gives you a portable JSON API that can be fast when you need and doesn't
46require a C compiler when that is a problem. 46require a C compiler when that is a problem.
47 47
… …
65This module knows how to handle Unicode, documents how and when it does 65This module knows how to handle Unicode, documents how and when it does
66so, and even documents what "correct" means. 66so, and even documents what "correct" means.
67 67
68=item * round-trip integrity 68=item * round-trip integrity
69 69
70When you serialise a perl data structure using only datatypes supported 70When you serialise a perl data structure using only data types supported
71by JSON, the deserialised data structure is identical on the Perl level. 71by JSON, the deserialised data structure is identical on the Perl level.
72(e.g. the string "2.0" doesn't suddenly become "2" just because it looks 72(e.g. the string "2.0" doesn't suddenly become "2" just because it looks
73like a number). There minor I<are> exceptions to this, read the MAPPING 73like a number). There minor I<are> exceptions to this, read the MAPPING
74section below to learn about those. 74section below to learn about those.
75 75
… …
84Compared to other JSON modules and other serialisers such as Storable, 84Compared to other JSON modules and other serialisers such as Storable,
85this module usually compares favourably in terms of speed, too. 85this module usually compares favourably in terms of speed, too.
86 86
87=item * simple to use 87=item * simple to use
88 88
89This module has both a simple functional interface as well as an objetc 89This module has both a simple functional interface as well as an object
90oriented interface interface. 90oriented interface interface.
91 91
92=item * reasonably versatile output formats 92=item * reasonably versatile output formats
93 93
94You can choose between the most compact guaranteed-single-line format 94You can choose between the most compact guaranteed-single-line format
95possible (nice for simple line-based protocols), a pure-ascii format 95possible (nice for simple line-based protocols), a pure-ASCII format
96(for when your transport is not 8-bit clean, still supports the whole 96(for when your transport is not 8-bit clean, still supports the whole
97Unicode range), or a pretty-printed format (for when you want to read that 97Unicode range), or a pretty-printed format (for when you want to read that
98stuff). Or you can combine those features in whatever way you like. 98stuff). Or you can combine those features in whatever way you like.
99 99
100=back 100=back
101 101
102=cut 102=cut
103 103
104package JSON::XS; 104package JSON::XS;
105 105
106no warnings;
106use strict; 107use strict;
107 108
108our $VERSION = '2.2'; 109our $VERSION = '2.2222';
109our @ISA = qw(Exporter); 110our @ISA = qw(Exporter);
110 111
111our @EXPORT = qw(encode_json decode_json to_json from_json); 112our @EXPORT = qw(encode_json decode_json to_json from_json);
112 113
113sub to_json($) { 114sub to_json($) {
… …
137 138
138This function call is functionally identical to: 139This function call is functionally identical to:
139 140
140 $json_text = JSON::XS->new->utf8->encode ($perl_scalar) 141 $json_text = JSON::XS->new->utf8->encode ($perl_scalar)
141 142
142except being faster. 143Except being faster.
143 144
144=item $perl_scalar = decode_json $json_text 145=item $perl_scalar = decode_json $json_text
145 146
146The opposite of C<encode_json>: expects an UTF-8 (binary) string and tries 147The opposite of C<encode_json>: expects an UTF-8 (binary) string and tries
147to parse that as an UTF-8 encoded JSON text, returning the resulting 148to parse that as an UTF-8 encoded JSON text, returning the resulting
… …
149 150
150This function call is functionally identical to: 151This function call is functionally identical to:
151 152
152 $perl_scalar = JSON::XS->new->utf8->decode ($json_text) 153 $perl_scalar = JSON::XS->new->utf8->decode ($json_text)
153 154
154except being faster. 155Except being faster.
155 156
156=item $is_boolean = JSON::XS::is_bool $scalar 157=item $is_boolean = JSON::XS::is_bool $scalar
157 158
158Returns true if the passed scalar represents either JSON::XS::true or 159Returns true if the passed scalar represents either JSON::XS::true or
159JSON::XS::false, two constants that act like C<1> and C<0>, respectively 160JSON::XS::false, two constants that act like C<1> and C<0>, respectively
… …
197 198
198If you didn't know about that flag, just the better, pretend it doesn't 199If you didn't know about that flag, just the better, pretend it doesn't
199exist. 200exist.
200 201
201=item 4. A "Unicode String" is simply a string where each character can be 202=item 4. A "Unicode String" is simply a string where each character can be
202validly interpreted as a Unicode codepoint. 203validly interpreted as a Unicode code point.
203 204
204If you have UTF-8 encoded data, it is no longer a Unicode string, but a 205If you have UTF-8 encoded data, it is no longer a Unicode string, but a
205Unicode string encoded in UTF-8, giving you a binary string. 206Unicode string encoded in UTF-8, giving you a binary string.
206 207
207=item 5. A string containing "high" (> 255) character values is I<not> a UTF-8 string. 208=item 5. A string containing "high" (> 255) character values is I<not> a UTF-8 string.
… …
701=back 702=back
702 703
703 704
704=head1 INCREMENTAL PARSING 705=head1 INCREMENTAL PARSING
705 706
706[This section and the API it details is still EXPERIMENTAL]
707
708In some cases, there is the need for incremental parsing of JSON 707In some cases, there is the need for incremental parsing of JSON
709texts. While this module always has to keep both JSON text and resulting 708texts. While this module always has to keep both JSON text and resulting
710Perl data structure in memory at one time, it does allow you to parse a 709Perl data structure in memory at one time, it does allow you to parse a
711JSON stream incrementally. It does so by accumulating text until it has 710JSON stream incrementally. It does so by accumulating text until it has
712a full JSON object, which it then can decode. This process is similar to 711a full JSON object, which it then can decode. This process is similar to
713using C<decode_prefix> to see if a full JSON object is available, but is 712using C<decode_prefix> to see if a full JSON object is available, but
714much more efficient (JSON::XS will only attempt to parse the JSON text 713is much more efficient (and can be implemented with a minimum of method
714calls).
715
716JSON::XS will only attempt to parse the JSON text once it is sure it
715once it is sure it has enough text to get a decisive result, using a very 717has enough text to get a decisive result, using a very simple but
716simple but truly incremental parser). 718truly incremental parser. This means that it sometimes won't stop as
719early as the full parser, for example, it doesn't detect parenthese
720mismatches. The only thing it guarantees is that it starts decoding as
721soon as a syntactically valid JSON text has been seen. This means you need
722to set resource limits (e.g. C<max_size>) to ensure the parser will stop
723parsing in the presence if syntax errors.
717 724
718The following two methods deal with this. 725The following methods implement this incremental parser.
719 726
720=over 4 727=over 4
721 728
722=item [void, scalar or list context] = $json->incr_parse ([$string]) 729=item [void, scalar or list context] = $json->incr_parse ([$string])
723 730
… …
765 772
766This will reset the state of the incremental parser and will remove the 773This will reset the state of the incremental parser and will remove the
767parsed text from the input buffer. This is useful after C<incr_parse> 774parsed text from the input buffer. This is useful after C<incr_parse>
768died, in which case the input buffer and incremental parser state is left 775died, in which case the input buffer and incremental parser state is left
769unchanged, to skip the text parsed so far and to reset the parse state. 776unchanged, to skip the text parsed so far and to reset the parse state.
777
778=item $json->incr_reset
779
780This completely resets the incremental parser, that is, after this call,
781it will be as if the parser had never parsed anything.
782
783This is useful if you want ot repeatedly parse JSON objects and want to
784ignore any trailing data, which means you have to reset the parser after
785each successful decode.
770 786
771=back 787=back
772 788
773=head2 LIMITATIONS 789=head2 LIMITATIONS
774 790
… …
1015Other unblessed references are generally not allowed and will cause an 1031Other unblessed references are generally not allowed and will cause an
1016exception to be thrown, except for references to the integers C<0> and 1032exception to be thrown, except for references to the integers C<0> and
1017C<1>, which get turned into C<false> and C<true> atoms in JSON. You can 1033C<1>, which get turned into C<false> and C<true> atoms in JSON. You can
1018also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability. 1034also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability.
1019 1035
1020 encode_json [\0,JSON::XS::true] # yields [false,true] 1036 encode_json [\0, JSON::XS::true] # yields [false,true]
1021 1037
1022=item JSON::XS::true, JSON::XS::false 1038=item JSON::XS::true, JSON::XS::false
1023 1039
1024These special values become JSON true and JSON false values, 1040These special values become JSON true and JSON false values,
1025respectively. You can also use C<\1> and C<\0> directly if you want. 1041respectively. You can also use C<\1> and C<\0> directly if you want.

Diff Legend

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