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.6 by root, Sun Oct 27 20:40:25 2013 UTC

… …
12 $perl_value = decode_cbor $binary_cbor_data; 12 $perl_value = decode_cbor $binary_cbor_data;
13 13
14 # OO-interface 14 # OO-interface
15 15
16 $coder = CBOR::XS->new; 16 $coder = CBOR::XS->new;
17 #TODO 17 $binary_cbor_data = $coder->encode ($perl_value);
18 $perl_value = $coder->decode ($binary_cbor_data);
19
20 # prefix decoding
21
22 my $many_cbor_strings = ...;
23 while (length $many_cbor_strings) {
24 my ($data, $length) = $cbor->decode_prefix ($many_cbor_strings);
25 # data was decoded
26 substr $many_cbor_strings, 0, $length, ""; # remove decoded cbor string
27 }
18 28
19=head1 DESCRIPTION 29=head1 DESCRIPTION
20 30
21WARNING! THIS IS A PRE-ALPHA RELEASE! IT WILL CRASH, CORRUPT YOUR DATA AND 31WARNING! THIS IS A PRE-ALPHA RELEASE! IT WILL CRASH, CORRUPT YOUR DATA
22EAT YOUR CHILDREN! 32AND EAT YOUR CHILDREN! (Actually, apart from being untested and a bit
33feature-limited, it might already be useful).
23 34
24This module converts Perl data structures to CBOR and vice versa. Its 35This module converts Perl data structures to the Concise Binary Object
36Representation (CBOR) and vice versa. CBOR is a fast binary serialisation
37format that aims to use a superset of the JSON data model, i.e. when you
38can represent something in JSON, you should be able to represent it in
39CBOR.
40
41This makes it a faster and more compact binary alternative to JSON, with
42the added ability of supporting serialising of perl objects.
43
25primary goal is to be I<correct> and its secondary goal is to be 44The 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. 45is to be I<fast>. To reach the latter goal it was written in C.
27 46
28See MAPPING, below, on how CBOR::XS maps perl values to CBOR values and 47See MAPPING, below, on how CBOR::XS maps perl values to CBOR values and
29vice versa. 48vice versa.
30 49
31=cut 50=cut
32 51
33package CBOR::XS; 52package CBOR::XS;
34 53
35use common::sense; 54use common::sense;
36 55
37our $VERSION = 0.02; 56our $VERSION = 0.03;
38our @ISA = qw(Exporter); 57our @ISA = qw(Exporter);
39 58
40our @EXPORT = qw(encode_cbor decode_cbor); 59our @EXPORT = qw(encode_cbor decode_cbor);
41 60
42use Exporter; 61use Exporter;
43use XSLoader; 62use XSLoader;
63
64use Types::Serialiser;
44 65
45our $MAGIC = "\xd9\xd9\xf7"; 66our $MAGIC = "\xd9\xd9\xf7";
46 67
47=head1 FUNCTIONAL INTERFACE 68=head1 FUNCTIONAL INTERFACE
48 69
… …
163 184
164=head2 CBOR -> PERL 185=head2 CBOR -> PERL
165 186
166=over 4 187=over 4
167 188
168=item True, False 189=item integers
169 190
170These CBOR values become C<CBOR::XS::true> and C<CBOR::XS::false>, 191CBOR integers become (numeric) perl scalars. On perls without 64 bit
192support, 64 bit integers will be truncated or otherwise corrupted.
193
194=item byte strings
195
196Byte strings will become octet strings in Perl (the byte values 0..255
197will simply become characters of the same value in Perl).
198
199=item UTF-8 strings
200
201UTF-8 strings in CBOR will be decoded, i.e. the UTF-8 octets will be
202decoded into proper Unicode code points. At the moment, the validity of
203the UTF-8 octets will not be validated - corrupt input will result in
204corrupted Perl strings.
205
206=item arrays, maps
207
208CBOR arrays and CBOR maps will be converted into references to a Perl
209array or hash, respectively. The keys of the map will be stringified
210during this process.
211
212=item null
213
214CBOR null becomes C<undef> in Perl.
215
216=item true, false, undefined
217
218These CBOR values become C<Types:Serialiser::true>,
219C<Types:Serialiser::false> and C<Types::Serialiser::error>,
171respectively. They are overloaded to act almost exactly like the numbers 220respectively. 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 221C<1> and C<0> (for true and false) or to throw an exception on access (for
173the C<CBOR::XS::is_bool> function. 222error). See the L<Types::Serialiser> manpage for details.
174 223
175=item Null, Undefined 224=item CBOR tag 256 (perl object)
176 225
177CBOR Null and Undefined values becomes C<undef> in Perl (in the future, 226The tag value C<256> (TODO: pending iana registration) will be used to
178Undefined may raise an exception). 227deserialise a Perl object.
228
229TODO For this to work, the class must be loaded and must have a
230C<FROM_CBOR> method. The decoder will then call the C<FROM_CBOR> method
231with the constructor arguments provided by the C<TO_CBOR> method (see
232below).
233
234The C<FROM_CBOR> method must return a single value that will then be used
235as the deserialised value.
236
237=item CBOR tag 55799 (magic header)
238
239The tag 55799 is ignored (this tag implements the magic header).
240
241=item other CBOR tags
242
243Tagged items consists of a numeric tag and another CBOR value. Tags not
244handled internally are currently converted into a L<CBOR::XS::Tagged>
245object, which is simply a blessed array reference consisting of the
246numeric tag value followed by the (decoded) CBOR value.
247
248In the future, support for user-supplied conversions might get added.
249
250=item anything else
251
252Anything else (e.g. unsupported simple values) will raise a decoding
253error.
179 254
180=back 255=back
181 256
182 257
183=head2 PERL -> CBOR 258=head2 PERL -> CBOR
… …
188 263
189=over 4 264=over 4
190 265
191=item hash references 266=item hash references
192 267
193Perl hash references become CBOR maps. As there is no inherent ordering 268Perl 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 269hash keys (or CBOR maps), they will usually be encoded in a pseudo-random
195pseudo-random order. 270order.
271
272Currently, tied hashes will use the indefinite-length format, while normal
273hashes will use the fixed-length format.
196 274
197=item array references 275=item array references
198 276
199Perl array references become CBOR arrays. 277Perl array references become fixed-length CBOR arrays.
200 278
201=item other references 279=item other references
202 280
203Other unblessed references are generally not allowed and will cause an 281Other unblessed references are generally not allowed and will cause an
204exception to be thrown, except for references to the integers C<0> and 282exception 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. 283C<1>, which get turned into false and true in CBOR.
206 284
207=item CBOR::XS::true, CBOR::XS::false 285=item CBOR::XS::Tagged objects
208 286
287Objects of this type must be arrays consisting of a single C<[tag, value]>
288pair. The (numerical) tag will be encoded as a CBOR tag, the value will be
289encoded as appropriate for the value.
290
291=item Types::Serialiser::true, Types::Serialiser::false, Types::Serialiser::error
292
209These special values become CBOR True and CBOR False values, 293These special values become CBOR true, CBOR false and CBOR undefined
210respectively. You can also use C<\1> and C<\0> directly if you want. 294values, respectively. You can also use C<\1>, C<\0> and C<\undef> directly
295if you want.
211 296
212=item blessed objects 297=item blessed objects
213 298
214Blessed objects are not directly representable in CBOR. TODO 299Other blessed objects currently need to have a C<TO_CBOR> method. It
215See the 300will be called on every object that is being serialised, and must return
216C<allow_blessed> and C<convert_blessed> methods on various options on 301something 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 302
221=item simple scalars 303=item simple scalars
222 304
223TODO 305TODO
224Simple Perl scalars (any scalar that is not a reference) are the most 306Simple Perl scalars (any scalar that is not a reference) are the most
225difficult objects to encode: CBOR::XS will encode undefined scalars as 307difficult objects to encode: CBOR::XS will encode undefined scalars as
226CBOR C<Null> values, scalars that have last been used in a string context 308CBOR null values, scalars that have last been used in a string context
227before encoding as CBOR strings, and anything else as number value: 309before encoding as CBOR strings, and anything else as number value:
228 310
229 # dump as number 311 # dump as number
230 encode_cbor [2] # yields [2] 312 encode_cbor [2] # yields [2]
231 encode_cbor [-3.0e17] # yields [-3e+17] 313 encode_cbor [-3.0e17] # yields [-3e+17]
… …
253 335
254You can not currently force the type in other, less obscure, ways. Tell me 336You 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 337if you need this capability (but don't forget to explain why it's needed
256:). 338:).
257 339
258Note that numerical precision has the same meaning as under Perl (so 340Perl values that seem to be integers generally use the shortest possible
259binary to decimal conversion follows the same rules as in Perl, which 341representation. Floating-point values will use either the IEEE single
260can differ to other languages). Also, your perl interpreter might expose 342format if possible without loss of precision, otherwise the IEEE double
261extensions to the floating point numbers of your platform, such as 343format 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 344represent numerical values are supported, but might suffer loss of
263error to pass those in. 345precision.
264 346
265=back 347=back
266 348
267 349
268=head2 MAGIC HEADER 350=head2 MAGIC HEADER
… …
278required. 360required.
279 361
280 362
281=head2 CBOR and JSON 363=head2 CBOR and JSON
282 364
283TODO 365CBOR is supposed to implement a superset of the JSON data model, and is,
366with some coercion, able to represent all JSON texts (something that other
367"binary JSON" formats such as BSON generally do not support).
368
369CBOR implements some extra hints and support for JSON interoperability,
370and the spec offers further guidance for conversion between CBOR and
371JSON. None of this is currently implemented in CBOR, and the guidelines
372in the spec do not result in correct round-tripping of data. If JSON
373interoperability is improved in the future, then the goal will be to
374ensure that decoded JSON data will round-trip encoding and decoding to
375CBOR intact.
284 376
285 377
286=head1 SECURITY CONSIDERATIONS 378=head1 SECURITY CONSIDERATIONS
287 379
288When you are using CBOR in a protocol, talking to untrusted potentially 380When you are using CBOR in a protocol, talking to untrusted potentially
… …
356Please refrain from using rt.cpan.org or any other bug reporting 448Please refrain from using rt.cpan.org or any other bug reporting
357service. I put the contact address into my modules for a reason. 449service. I put the contact address into my modules for a reason.
358 450
359=cut 451=cut
360 452
361our $true = do { bless \(my $dummy = 1), "CBOR::XS::Boolean" };
362our $false = do { bless \(my $dummy = 0), "CBOR::XS::Boolean" };
363
364sub true() { $true }
365sub false() { $false }
366
367sub is_bool($) {
368 UNIVERSAL::isa $_[0], "CBOR::XS::Boolean"
369# or UNIVERSAL::isa $_[0], "CBOR::Literal"
370}
371
372XSLoader::load "CBOR::XS", $VERSION; 453XSLoader::load "CBOR::XS", $VERSION;
373
374package CBOR::XS::Boolean;
375
376use overload
377 "0+" => sub { ${$_[0]} },
378 "++" => sub { $_[0] = ${$_[0]} + 1 },
379 "--" => sub { $_[0] = ${$_[0]} - 1 },
380 fallback => 1;
381
3821;
383 454
384=head1 SEE ALSO 455=head1 SEE ALSO
385 456
386The L<JSON> and L<JSON::XS> modules that do similar, but human-readable, 457The L<JSON> and L<JSON::XS> modules that do similar, but human-readable,
387serialisation. 458serialisation.
388 459
460The L<Types::Serialiser> module provides the data model for true, false
461and error values.
462
389=head1 AUTHOR 463=head1 AUTHOR
390 464
391 Marc Lehmann <schmorp@schmorp.de> 465 Marc Lehmann <schmorp@schmorp.de>
392 http://home.schmorp.de/ 466 http://home.schmorp.de/
393 467
394=cut 468=cut
395 469
4701
471

Diff Legend

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