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.36 by root, Mon Dec 2 06:37:53 2013 UTC vs.
Revision 1.40 by root, Sun Jan 5 14:24:54 2014 UTC

… …
64 64
65package CBOR::XS; 65package CBOR::XS;
66 66
67use common::sense; 67use common::sense;
68 68
69our $VERSION = 1.11; 69our $VERSION = 1.25;
70our @ISA = qw(Exporter); 70our @ISA = qw(Exporter);
71 71
72our @EXPORT = qw(encode_cbor decode_cbor); 72our @EXPORT = qw(encode_cbor decode_cbor);
73 73
74use Exporter; 74use Exporter;
… …
330and you need to know where the first CBOR string ends amd the next one 330and you need to know where the first CBOR string ends amd the next one
331starts. 331starts.
332 332
333 CBOR::XS->new->decode_prefix ("......") 333 CBOR::XS->new->decode_prefix ("......")
334 => ("...", 3) 334 => ("...", 3)
335
336=back
337
338=head2 INCREMENTAL PARSING
339
340In some cases, there is the need for incremental parsing of JSON
341texts. While this module always has to keep both CBOR text and resulting
342Perl data structure in memory at one time, it does allow you to parse a
343CBOR stream incrementally, using a similar to using "decode_prefix" to see
344if a full CBOR object is available, but is much more efficient.
345
346It basically works by parsing as much of a CBOR string as possible - if
347the CBOR data is not complete yet, the pasrer will remember where it was,
348to be able to restart when more data has been accumulated. Once enough
349data is available to either decode a complete CBOR value or raise an
350error, a real decode will be attempted.
351
352A typical use case would be a network protocol that consists of sending
353and receiving CBOR-encoded messages. The solution that works with CBOR and
354about anything else is by prepending a length to every CBOR value, so the
355receiver knows how many octets to read. More compact (and slightly slower)
356would be to just send CBOR values back-to-back, as C<CBOR::XS> knows where
357a CBOR value ends, and doesn't need an explicit length.
358
359The following methods help with this:
360
361=over 4
362
363=item @decoded = $cbor->incr_parse ($buffer)
364
365This method attempts to decode exactly one CBOR value from the beginning
366of the given C<$buffer>. The value is removed from the C<$buffer> on
367success. When C<$buffer> doesn't contain a complete value yet, it returns
368nothing. Finally, when the C<$buffer> doesn't start with something
369that could ever be a valid CBOR value, it raises an exception, just as
370C<decode> would. In the latter case the decoder state is undefined and
371must be reset before being able to parse further.
372
373This method modifies the C<$buffer> in place. When no CBOR value can be
374decoded, the decoder stores the current string offset. On the next call,
375continues decoding at the place where it stopped before. For this to make
376sense, the C<$buffer> must begin with the same octets as on previous
377unsuccessful calls.
378
379You can call this method in scalar context, in which case it either
380returns a decoded value or C<undef>. This makes it impossible to
381distinguish between CBOR null values (which decode to C<undef>) and an
382unsuccessful decode, which is often acceptable.
383
384=item @decoded = $cbor->incr_parse_multiple ($buffer)
385
386Same as C<incr_parse>, but attempts to decode as many CBOR values as
387possible in one go, instead of at most one. Calls to C<incr_parse> and
388C<incr_parse_multiple> can be interleaved.
389
390=item $cbor->incr_reset
391
392Resets the incremental decoder. This throws away any saved state, so that
393subsequent calls to C<incr_parse> or C<incr_parse_multiple> start to parse
394a new CBOR value from the beginning of the C<$buffer> again.
395
396This method can be caled at any time, but it I<must> be called if you want
397to change your C<$buffer> or there was a decoding error and you want to
398reuse the C<$cbor> object for future incremental parsings.
335 399
336=back 400=back
337 401
338 402
339=head1 MAPPING 403=head1 MAPPING
… …
989 # from FreeBSD, which can't parse ISO 8601, RFC3339, RFC4287 or much of anything 1053 # from FreeBSD, which can't parse ISO 8601, RFC3339, RFC4287 or much of anything
990 # else either. Whats incredibe over standard strptime totally escapes me. 1054 # else either. Whats incredibe over standard strptime totally escapes me.
991 # doesn't do fractional times, either. sigh. 1055 # doesn't do fractional times, either. sigh.
992 # In fact, it's all a lie, it uses whatever strptime it wants, and of course, 1056 # In fact, it's all a lie, it uses whatever strptime it wants, and of course,
993 # they are all incomptible. The openbsd one simply ignores %z (but according to the 1057 # they are all incomptible. The openbsd one simply ignores %z (but according to the
994 # docs, it would be much more incredibly flexible). 1058 # docs, it would be much more incredibly flexible indeed. If it worked, that is.).
995 scalar eval { 1059 scalar eval {
996 my $s = $_[1]; 1060 my $s = $_[1];
997 1061
998 $s =~ s/Z$/+00:00/; 1062 $s =~ s/Z$/+00:00/;
999 $s =~ s/(\.[0-9]+)?([+-][0-9][0-9]):([0-9][0-9])$// 1063 $s =~ s/(\.[0-9]+)?([+-][0-9][0-9]):([0-9][0-9])$//
… …
1072 my ($m, $e) = $_[0]->parts; 1136 my ($m, $e) = $_[0]->parts;
1073 tag 4, [$e->numify, $m] 1137 tag 4, [$e->numify, $m]
1074} 1138}
1075 1139
1076sub Time::Piece::TO_CBOR { 1140sub Time::Piece::TO_CBOR {
1077 tag 1, $_[0]->epoch 1141 tag 1, 0 + $_[0]->epoch
1078} 1142}
1079 1143
1080XSLoader::load "CBOR::XS", $VERSION; 1144XSLoader::load "CBOR::XS", $VERSION;
1081 1145
1082=head1 SEE ALSO 1146=head1 SEE ALSO

Diff Legend

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