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.1 by root, Fri Oct 25 23:09:45 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.01; 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;
65
66our $MAGIC = "\xd9\xd9\xf7";
44 67
45=head1 FUNCTIONAL INTERFACE 68=head1 FUNCTIONAL INTERFACE
46 69
47The following convenience methods are provided by this module. They are 70The following convenience methods are provided by this module. They are
48exported by default: 71exported by default:
… …
161 184
162=head2 CBOR -> PERL 185=head2 CBOR -> PERL
163 186
164=over 4 187=over 4
165 188
166=item True, False 189=item integers
167 190
168These 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>,
169respectively. They are overloaded to act almost exactly like the numbers 220respectively. They are overloaded to act almost exactly like the numbers
170C<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
171the C<CBOR::XS::is_bool> function. 222error). See the L<Types::Serialiser> manpage for details.
172 223
173=item null 224=item CBOR tag 256 (perl object)
174 225
175A CBOR Null value becomes C<undef> in Perl. 226The tag value C<256> (TODO: pending iana registration) will be used to
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.
176 254
177=back 255=back
178 256
179 257
180=head2 PERL -> CBOR 258=head2 PERL -> CBOR
… …
185 263
186=over 4 264=over 4
187 265
188=item hash references 266=item hash references
189 267
190Perl hash references become CBOR maps. As there is no inherent ordering 268Perl hash references become CBOR maps. As there is no inherent ordering in
191in 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
192pseudo-random order. 270order.
271
272Currently, tied hashes will use the indefinite-length format, while normal
273hashes will use the fixed-length format.
193 274
194=item array references 275=item array references
195 276
196Perl array references become CBOR arrays. 277Perl array references become fixed-length CBOR arrays.
197 278
198=item other references 279=item other references
199 280
200Other unblessed references are generally not allowed and will cause an 281Other unblessed references are generally not allowed and will cause an
201exception 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
202C<1>, which get turned into C<False> and C<True> in CBOR. 283C<1>, which get turned into false and true in CBOR.
203 284
204=item CBOR::XS::true, CBOR::XS::false 285=item CBOR::XS::Tagged objects
205 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
206These special values become CBOR True and CBOR False values, 293These special values become CBOR true, CBOR false and CBOR undefined
207respectively. 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.
208 296
209=item blessed objects 297=item blessed objects
210 298
211Blessed objects are not directly representable in CBOR. TODO 299Other blessed objects currently need to have a C<TO_CBOR> method. It
212See the 300will be called on every object that is being serialised, and must return
213C<allow_blessed> and C<convert_blessed> methods on various options on 301something that can be encoded in CBOR.
214how to deal with this: basically, you can choose between throwing an
215exception, encoding the reference as if it weren't blessed, or provide
216your own serialiser method.
217 302
218=item simple scalars 303=item simple scalars
219 304
220TODO 305TODO
221Simple 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
222difficult objects to encode: CBOR::XS will encode undefined scalars as 307difficult objects to encode: CBOR::XS will encode undefined scalars as
223CBOR 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
224before encoding as CBOR strings, and anything else as number value: 309before encoding as CBOR strings, and anything else as number value:
225 310
226 # dump as number 311 # dump as number
227 encode_cbor [2] # yields [2] 312 encode_cbor [2] # yields [2]
228 encode_cbor [-3.0e17] # yields [-3e+17] 313 encode_cbor [-3.0e17] # yields [-3e+17]
… …
250 335
251You 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
252if 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
253:). 338:).
254 339
255Note that numerical precision has the same meaning as under Perl (so 340Perl values that seem to be integers generally use the shortest possible
256binary to decimal conversion follows the same rules as in Perl, which 341representation. Floating-point values will use either the IEEE single
257can differ to other languages). Also, your perl interpreter might expose 342format if possible without loss of precision, otherwise the IEEE double
258extensions to the floating point numbers of your platform, such as 343format will be used. Perls that use formats other than IEEE double to
259infinities or NaN's - these cannot be represented in CBOR, and it is an 344represent numerical values are supported, but might suffer loss of
260error to pass those in. 345precision.
261 346
262=back 347=back
263 348
264 349
350=head2 MAGIC HEADER
351
352There is no way to distinguish CBOR from other formats
353programmatically. To make it easier to distinguish CBOR from other
354formats, the CBOR specification has a special "magic string" that can be
355prepended to any CBOR string without changing it's meaning.
356
357This string is available as C<$CBOR::XS::MAGIC>. This module does not
358prepend this string tot he CBOR data it generates, but it will ignroe it
359if present, so users can prepend this string as a "file type" indicator as
360required.
361
362
265=head2 CBOR and JSON 363=head2 CBOR and JSON
266 364
267TODO 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.
268 376
269 377
270=head1 SECURITY CONSIDERATIONS 378=head1 SECURITY CONSIDERATIONS
271 379
272When you are using CBOR in a protocol, talking to untrusted potentially 380When you are using CBOR in a protocol, talking to untrusted potentially
… …
340Please refrain from using rt.cpan.org or any other bug reporting 448Please refrain from using rt.cpan.org or any other bug reporting
341service. I put the contact address into my modules for a reason. 449service. I put the contact address into my modules for a reason.
342 450
343=cut 451=cut
344 452
345our $true = do { bless \(my $dummy = 1), "CBOR::XS::Boolean" };
346our $false = do { bless \(my $dummy = 0), "CBOR::XS::Boolean" };
347
348sub true() { $true }
349sub false() { $false }
350
351sub is_bool($) {
352 UNIVERSAL::isa $_[0], "CBOR::XS::Boolean"
353# or UNIVERSAL::isa $_[0], "CBOR::Literal"
354}
355
356XSLoader::load "CBOR::XS", $VERSION; 453XSLoader::load "CBOR::XS", $VERSION;
357
358package CBOR::XS::Boolean;
359
360use overload
361 "0+" => sub { ${$_[0]} },
362 "++" => sub { $_[0] = ${$_[0]} + 1 },
363 "--" => sub { $_[0] = ${$_[0]} - 1 },
364 fallback => 1;
365
3661;
367 454
368=head1 SEE ALSO 455=head1 SEE ALSO
369 456
370The 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,
371serialisation. 458serialisation.
372 459
460The L<Types::Serialiser> module provides the data model for true, false
461and error values.
462
373=head1 AUTHOR 463=head1 AUTHOR
374 464
375 Marc Lehmann <schmorp@schmorp.de> 465 Marc Lehmann <schmorp@schmorp.de>
376 http://home.schmorp.de/ 466 http://home.schmorp.de/
377 467
378=cut 468=cut
379 469
4701
471

Diff Legend

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