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

Comparing CBOR-XS/XS.pm (file contents):
Revision 1.3 by root, Sat Oct 26 11:08:34 2013 UTC vs.
Revision 1.5 by root, Sat Oct 26 23:02:55 2013 UTC

… …
16 $coder = CBOR::XS->new; 16 $coder = CBOR::XS->new;
17 #TODO 17 #TODO
18 18
19=head1 DESCRIPTION 19=head1 DESCRIPTION
20 20
21WARNING! THIS IS A PRE-ALPHA RELEASE! IT WILL CRASH, CORRUPT YOUR DATA AND 21WARNING! THIS IS A PRE-ALPHA RELEASE! IT WILL CRASH, CORRUPT YOUR DATA
22EAT YOUR CHILDREN! 22AND EAT YOUR CHILDREN! (Actually, apart from being untested and a bit
23feature-limited, it might already be useful).
23 24
24This module converts Perl data structures to CBOR and vice versa. Its 25This module converts Perl data structures to the Concise Binary Object
26Representation (CBOR) and vice versa. CBOR is a fast binary serialisation
27format that aims to use a superset of the JSON data model, i.e. when you
28can represent something in JSON, you should be able to represent it in
29CBOR.
30
31This makes it a faster and more compact binary alternative to JSON.
32
25primary goal is to be I<correct> and its secondary goal is to be 33The primary goal of this module is to be I<correct> and the secondary goal
26I<fast>. To reach the latter goal it was written in C. 34is to be I<fast>. To reach the latter goal it was written in C.
27 35
28See MAPPING, below, on how CBOR::XS maps perl values to CBOR values and 36See MAPPING, below, on how CBOR::XS maps perl values to CBOR values and
29vice versa. 37vice versa.
30 38
31=cut 39=cut
32 40
33package CBOR::XS; 41package CBOR::XS;
34 42
35use common::sense; 43use common::sense;
36 44
37our $VERSION = 0.02; 45our $VERSION = 0.03;
38our @ISA = qw(Exporter); 46our @ISA = qw(Exporter);
39 47
40our @EXPORT = qw(encode_cbor decode_cbor); 48our @EXPORT = qw(encode_cbor decode_cbor);
41 49
42use Exporter; 50use Exporter;
… …
163 171
164=head2 CBOR -> PERL 172=head2 CBOR -> PERL
165 173
166=over 4 174=over 4
167 175
176=item integers
177
178CBOR integers become (numeric) perl scalars. On perls without 64 bit
179support, 64 bit integers will be truncated or otherwise corrupted.
180
181=item byte strings
182
183Byte strings will become octet strings in Perl (the byte values 0..255
184will simply become characters of the same value in Perl).
185
186=item UTF-8 strings
187
188UTF-8 strings in CBOR will be decoded, i.e. the UTF-8 octets will be
189decoded into proper Unicode code points. At the moment, the validity of
190the UTF-8 octets will not be validated - corrupt input will result in
191corrupted Perl strings.
192
193=item arrays, maps
194
195CBOR arrays and CBOR maps will be converted into references to a Perl
196array or hash, respectively. The keys of the map will be stringified
197during this process.
198
168=item True, False 199=item true, false
169 200
170These CBOR values become C<CBOR::XS::true> and C<CBOR::XS::false>, 201These CBOR values become C<CBOR::XS::true> and C<CBOR::XS::false>,
171respectively. They are overloaded to act almost exactly like the numbers 202respectively. They are overloaded to act almost exactly like the numbers
172C<1> and C<0>. You can check whether a scalar is a CBOR boolean by using 203C<1> and C<0>. You can check whether a scalar is a CBOR boolean by using
173the C<CBOR::XS::is_bool> function. 204the C<CBOR::XS::is_bool> function.
174 205
175=item Null, Undefined 206=item null, undefined
176 207
177CBOR Null and Undefined values becomes C<undef> in Perl (in the future, 208CBOR null and undefined values becomes C<undef> in Perl (in the future,
178Undefined may raise an exception). 209Undefined may raise an exception or something else).
210
211=item tags
212
213Tagged items consists of a numeric tag and another CBOR value. The tag
21455799 is ignored (this tag implements the magic header).
215
216All other tags are currently converted into a L<CBOR::XS::Tagged> object,
217which is simply a blessed array reference consistsing of the numeric tag
218value followed by the (decoded) BOR value.
219
220=item anything else
221
222Anything else (e.g. unsupported simple values) will raise a decoding
223error.
179 224
180=back 225=back
181 226
182 227
183=head2 PERL -> CBOR 228=head2 PERL -> CBOR
… …
188 233
189=over 4 234=over 4
190 235
191=item hash references 236=item hash references
192 237
193Perl hash references become CBOR maps. As there is no inherent ordering 238Perl hash references become CBOR maps. As there is no inherent ordering in
194in hash keys (or CBOR maps), they will usually be encoded in a 239hash keys (or CBOR maps), they will usually be encoded in a pseudo-random
195pseudo-random order. 240order.
241
242Currently, tied hashes will use the indefinite-length format, while normal
243hashes will use the fixed-length format.
196 244
197=item array references 245=item array references
198 246
199Perl array references become CBOR arrays. 247Perl array references become fixed-length CBOR arrays.
200 248
201=item other references 249=item other references
202 250
203Other unblessed references are generally not allowed and will cause an 251Other unblessed references are generally not allowed and will cause an
204exception to be thrown, except for references to the integers C<0> and 252exception to be thrown, except for references to the integers C<0> and
205C<1>, which get turned into C<False> and C<True> in CBOR. 253C<1>, which get turned into false and true in CBOR.
254
255=item CBOR::XS::Tagged objects
256
257Objects of this type must be arrays consisting of a single C<[tag, value]>
258pair. The (numerical) tag will be encoded as a CBOR tag, the value will be
259encoded as appropriate for the value.
206 260
207=item CBOR::XS::true, CBOR::XS::false 261=item CBOR::XS::true, CBOR::XS::false
208 262
209These special values become CBOR True and CBOR False values, 263These special values become CBOR true and CBOR false values,
210respectively. You can also use C<\1> and C<\0> directly if you want. 264respectively. You can also use C<\1> and C<\0> directly if you want.
211 265
212=item blessed objects 266=item blessed objects
213 267
214Blessed objects are not directly representable in CBOR. TODO 268Other blessed objects currently need to have a C<TO_CBOR> method. It
215See the 269will be called on every object that is being serialised, and must return
216C<allow_blessed> and C<convert_blessed> methods on various options on 270something that can be encoded in CBOR.
217how to deal with this: basically, you can choose between throwing an
218exception, encoding the reference as if it weren't blessed, or provide
219your own serialiser method.
220 271
221=item simple scalars 272=item simple scalars
222 273
223TODO 274TODO
224Simple Perl scalars (any scalar that is not a reference) are the most 275Simple Perl scalars (any scalar that is not a reference) are the most
225difficult objects to encode: CBOR::XS will encode undefined scalars as 276difficult objects to encode: CBOR::XS will encode undefined scalars as
226CBOR C<Null> values, scalars that have last been used in a string context 277CBOR null values, scalars that have last been used in a string context
227before encoding as CBOR strings, and anything else as number value: 278before encoding as CBOR strings, and anything else as number value:
228 279
229 # dump as number 280 # dump as number
230 encode_cbor [2] # yields [2] 281 encode_cbor [2] # yields [2]
231 encode_cbor [-3.0e17] # yields [-3e+17] 282 encode_cbor [-3.0e17] # yields [-3e+17]
… …
253 304
254You can not currently force the type in other, less obscure, ways. Tell me 305You can not currently force the type in other, less obscure, ways. Tell me
255if you need this capability (but don't forget to explain why it's needed 306if you need this capability (but don't forget to explain why it's needed
256:). 307:).
257 308
258Note that numerical precision has the same meaning as under Perl (so 309Perl values that seem to be integers generally use the shortest possible
259binary to decimal conversion follows the same rules as in Perl, which 310representation. Floating-point values will use either the IEEE single
260can differ to other languages). Also, your perl interpreter might expose 311format if possible without loss of precision, otherwise the IEEE double
261extensions to the floating point numbers of your platform, such as 312format will be used. Perls that use formats other than IEEE double to
262infinities or NaN's - these cannot be represented in CBOR, and it is an 313represent numerical values are supported, but might suffer loss of
263error to pass those in. 314precision.
264 315
265=back 316=back
266 317
267 318
268=head2 MAGIC HEADER 319=head2 MAGIC HEADER
… …
278required. 329required.
279 330
280 331
281=head2 CBOR and JSON 332=head2 CBOR and JSON
282 333
283TODO 334CBOR is supposed to implement a superset of the JSON data model, and is,
335with some coercion, able to represent all JSON texts (something that other
336"binary JSON" formats such as BSON generally do not support).
337
338CBOR implements some extra hints and support for JSON interoperability,
339and the spec offers further guidance for conversion between CBOR and
340JSON. None of this is currently implemented in CBOR, and the guidelines
341in the spec do not result in correct round-tripping of data. If JSON
342interoperability is improved in the future, then the goal will be to
343ensure that decoded JSON data will round-trip encoding and decoding to
344CBOR intact.
284 345
285 346
286=head1 SECURITY CONSIDERATIONS 347=head1 SECURITY CONSIDERATIONS
287 348
288When you are using CBOR in a protocol, talking to untrusted potentially 349When you are using CBOR in a protocol, talking to untrusted potentially

Diff Legend

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