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.5 by root, Sat Oct 26 23:02:55 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 31WARNING! THIS IS A PRE-ALPHA RELEASE! IT WILL CRASH, CORRUPT YOUR DATA
22AND EAT YOUR CHILDREN! (Actually, apart from being untested and a bit 32AND EAT YOUR CHILDREN! (Actually, apart from being untested and a bit
… …
26Representation (CBOR) and vice versa. CBOR is a fast binary serialisation 36Representation (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 37format 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 38can represent something in JSON, you should be able to represent it in
29CBOR. 39CBOR.
30 40
31This makes it a faster and more compact binary alternative to JSON. 41This makes it a faster and more compact binary alternative to JSON, with
42the added ability of supporting serialising of perl objects.
32 43
33The primary goal of this module is to be I<correct> and the secondary goal 44The primary goal of this module is to be I<correct> and the secondary goal
34is to be I<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.
35 46
36See 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
… …
47 58
48our @EXPORT = qw(encode_cbor decode_cbor); 59our @EXPORT = qw(encode_cbor decode_cbor);
49 60
50use Exporter; 61use Exporter;
51use XSLoader; 62use XSLoader;
63
64use Types::Serialiser;
52 65
53our $MAGIC = "\xd9\xd9\xf7"; 66our $MAGIC = "\xd9\xd9\xf7";
54 67
55=head1 FUNCTIONAL INTERFACE 68=head1 FUNCTIONAL INTERFACE
56 69
… …
194 207
195CBOR 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
196array or hash, respectively. The keys of the map will be stringified 209array or hash, respectively. The keys of the map will be stringified
197during this process. 210during this process.
198 211
212=item null
213
214CBOR null becomes C<undef> in Perl.
215
199=item true, false 216=item true, false, undefined
200 217
201These 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>,
202respectively. They are overloaded to act almost exactly like the numbers 220respectively. They are overloaded to act almost exactly like the numbers
203C<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
204the C<CBOR::XS::is_bool> function. 222error). See the L<Types::Serialiser> manpage for details.
205 223
206=item null, undefined 224=item CBOR tag 256 (perl object)
207 225
208CBOR 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
209Undefined may raise an exception or something else). 227deserialise a Perl object.
210 228
211=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).
212 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
213Tagged 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
21455799 is ignored (this tag implements the magic header). 244handled internally are currently converted into a L<CBOR::XS::Tagged>
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 245object, which is simply a blessed array reference consisting of the
218value 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.
219 249
220=item anything else 250=item anything else
221 251
222Anything else (e.g. unsupported simple values) will raise a decoding 252Anything else (e.g. unsupported simple values) will raise a decoding
223error. 253error.
… …
256 286
257Objects 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]>
258pair. 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
259encoded as appropriate for the value. 289encoded as appropriate for the value.
260 290
261=item CBOR::XS::true, CBOR::XS::false 291=item Types::Serialiser::true, Types::Serialiser::false, Types::Serialiser::error
262 292
263These special values become CBOR true and CBOR false values, 293These special values become CBOR true, CBOR false and CBOR undefined
264respectively. 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.
265 296
266=item blessed objects 297=item blessed objects
267 298
268Other 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
269will 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
… …
417Please refrain from using rt.cpan.org or any other bug reporting 448Please refrain from using rt.cpan.org or any other bug reporting
418service. I put the contact address into my modules for a reason. 449service. I put the contact address into my modules for a reason.
419 450
420=cut 451=cut
421 452
422our $true = do { bless \(my $dummy = 1), "CBOR::XS::Boolean" };
423our $false = do { bless \(my $dummy = 0), "CBOR::XS::Boolean" };
424
425sub true() { $true }
426sub false() { $false }
427
428sub is_bool($) {
429 UNIVERSAL::isa $_[0], "CBOR::XS::Boolean"
430# or UNIVERSAL::isa $_[0], "CBOR::Literal"
431}
432
433XSLoader::load "CBOR::XS", $VERSION; 453XSLoader::load "CBOR::XS", $VERSION;
434
435package CBOR::XS::Boolean;
436
437use overload
438 "0+" => sub { ${$_[0]} },
439 "++" => sub { $_[0] = ${$_[0]} + 1 },
440 "--" => sub { $_[0] = ${$_[0]} - 1 },
441 fallback => 1;
442
4431;
444 454
445=head1 SEE ALSO 455=head1 SEE ALSO
446 456
447The 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,
448serialisation. 458serialisation.
449 459
460The L<Types::Serialiser> module provides the data model for true, false
461and error values.
462
450=head1 AUTHOR 463=head1 AUTHOR
451 464
452 Marc Lehmann <schmorp@schmorp.de> 465 Marc Lehmann <schmorp@schmorp.de>
453 http://home.schmorp.de/ 466 http://home.schmorp.de/
454 467
455=cut 468=cut
456 469
4701
471

Diff Legend

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