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.4 by root, Sat Oct 26 22:25:47 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
… …
186 207
187CBOR arrays and CBOR maps will be converted into references to a Perl 208CBOR arrays and CBOR maps will be converted into references to a Perl
188array or hash, respectively. The keys of the map will be stringified 209array or hash, respectively. The keys of the map will be stringified
189during this process. 210during this process.
190 211
212=item null
213
214CBOR null becomes C<undef> in Perl.
215
191=item true, false 216=item true, false, undefined
192 217
193These CBOR values become C<CBOR::XS::true> and C<CBOR::XS::false>, 218These CBOR values become C<Types:Serialiser::true>,
219C<Types:Serialiser::false> and C<Types::Serialiser::error>,
194respectively. They are overloaded to act almost exactly like the numbers 220respectively. They are overloaded to act almost exactly like the numbers
195C<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
196the C<CBOR::XS::is_bool> function. 222error). See the L<Types::Serialiser> manpage for details.
197 223
198=item null, undefined 224=item CBOR tag 256 (perl object)
199 225
200CBOR 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
201Undefined may raise an exception or something else). 227deserialise a Perl object.
202 228
203=item tags 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).
204 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
205Tagged items consists of a numeric tag and another CBOR value. The tag 243Tagged items consists of a numeric tag and another CBOR value. Tags not
20655799 is ignored (this tag implements the magic header). 244handled internally are currently converted into a L<CBOR::XS::Tagged>
207
208All other tags are currently converted into a L<CBOR::XS::Tagged> object,
209which is simply a blessed array reference consistsing of the numeric tag 245object, which is simply a blessed array reference consisting of the
210value followed by the (decoded) BOR value. 246numeric tag value followed by the (decoded) CBOR value.
247
248In the future, support for user-supplied conversions might get added.
211 249
212=item anything else 250=item anything else
213 251
214Anything else (e.g. unsupported simple values) will raise a decoding 252Anything else (e.g. unsupported simple values) will raise a decoding
215error. 253error.
… …
248 286
249Objects of this type must be arrays consisting of a single C<[tag, value]> 287Objects of this type must be arrays consisting of a single C<[tag, value]>
250pair. The (numerical) tag will be encoded as a CBOR tag, the value will be 288pair. The (numerical) tag will be encoded as a CBOR tag, the value will be
251encoded as appropriate for the value. 289encoded as appropriate for the value.
252 290
253=item CBOR::XS::true, CBOR::XS::false 291=item Types::Serialiser::true, Types::Serialiser::false, Types::Serialiser::error
254 292
255These special values become CBOR true and CBOR false values, 293These special values become CBOR true, CBOR false and CBOR undefined
256respectively. 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.
257 296
258=item blessed objects 297=item blessed objects
259 298
260Other blessed objects currently need to have a C<TO_CBOR> method. It 299Other blessed objects currently need to have a C<TO_CBOR> method. It
261will be called on every object that is being serialised, and must return 300will be called on every object that is being serialised, and must return
… …
409Please refrain from using rt.cpan.org or any other bug reporting 448Please refrain from using rt.cpan.org or any other bug reporting
410service. I put the contact address into my modules for a reason. 449service. I put the contact address into my modules for a reason.
411 450
412=cut 451=cut
413 452
414our $true = do { bless \(my $dummy = 1), "CBOR::XS::Boolean" };
415our $false = do { bless \(my $dummy = 0), "CBOR::XS::Boolean" };
416
417sub true() { $true }
418sub false() { $false }
419
420sub is_bool($) {
421 UNIVERSAL::isa $_[0], "CBOR::XS::Boolean"
422# or UNIVERSAL::isa $_[0], "CBOR::Literal"
423}
424
425XSLoader::load "CBOR::XS", $VERSION; 453XSLoader::load "CBOR::XS", $VERSION;
426
427package CBOR::XS::Boolean;
428
429use overload
430 "0+" => sub { ${$_[0]} },
431 "++" => sub { $_[0] = ${$_[0]} + 1 },
432 "--" => sub { $_[0] = ${$_[0]} - 1 },
433 fallback => 1;
434
4351;
436 454
437=head1 SEE ALSO 455=head1 SEE ALSO
438 456
439The 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,
440serialisation. 458serialisation.
441 459
460The L<Types::Serialiser> module provides the data model for true, false
461and error values.
462
442=head1 AUTHOR 463=head1 AUTHOR
443 464
444 Marc Lehmann <schmorp@schmorp.de> 465 Marc Lehmann <schmorp@schmorp.de>
445 http://home.schmorp.de/ 466 http://home.schmorp.de/
446 467
447=cut 468=cut
448 469
4701
471

Diff Legend

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