--- CBOR-XS/XS.pm	2013/10/26 22:25:47	1.4
+++ CBOR-XS/XS.pm	2013/10/27 20:40:25	1.6
@@ -14,16 +14,35 @@
  # OO-interface
 
  $coder = CBOR::XS->new;
- #TODO
+ $binary_cbor_data = $coder->encode ($perl_value);
+ $perl_value       = $coder->decode ($binary_cbor_data);
+
+ # prefix decoding
+
+ my $many_cbor_strings = ...;
+ while (length $many_cbor_strings) {
+    my ($data, $length) = $cbor->decode_prefix ($many_cbor_strings);
+    # data was decoded
+    substr $many_cbor_strings, 0, $length, ""; # remove decoded cbor string
+ }
 
 =head1 DESCRIPTION
 
-WARNING! THIS IS A PRE-ALPHA RELEASE! IT WILL CRASH, CORRUPT YOUR DATA AND
-EAT YOUR CHILDREN!
+WARNING! THIS IS A PRE-ALPHA RELEASE! IT WILL CRASH, CORRUPT YOUR DATA
+AND EAT YOUR CHILDREN! (Actually, apart from being untested and a bit
+feature-limited, it might already be useful).
+
+This module converts Perl data structures to the Concise Binary Object
+Representation (CBOR) and vice versa. CBOR is a fast binary serialisation
+format that aims to use a superset of the JSON data model, i.e. when you
+can represent something in JSON, you should be able to represent it in
+CBOR.
+
+This makes it a faster and more compact binary alternative to JSON, with
+the added ability of supporting serialising of perl objects.
 
-This module converts Perl data structures to CBOR and vice versa. Its
-primary goal is to be I<correct> and its secondary goal is to be
-I<fast>. To reach the latter goal it was written in C.
+The primary goal of this module is to be I<correct> and the secondary goal
+is to be I<fast>. To reach the latter goal it was written in C.
 
 See MAPPING, below, on how CBOR::XS maps perl values to CBOR values and
 vice versa.
@@ -34,7 +53,7 @@
 
 use common::sense;
 
-our $VERSION = 0.02;
+our $VERSION = 0.03;
 our @ISA = qw(Exporter);
 
 our @EXPORT = qw(encode_cbor decode_cbor);
@@ -42,6 +61,8 @@
 use Exporter;
 use XSLoader;
 
+use Types::Serialiser;
+
 our $MAGIC = "\xd9\xd9\xf7";
 
 =head1 FUNCTIONAL INTERFACE
@@ -188,26 +209,43 @@
 array or hash, respectively. The keys of the map will be stringified
 during this process.
 
-=item true, false
+=item null
+
+CBOR null becomes C<undef> in Perl.
 
-These CBOR values become C<CBOR::XS::true> and C<CBOR::XS::false>,
+=item true, false, undefined
+
+These CBOR values become C<Types:Serialiser::true>,
+C<Types:Serialiser::false> and C<Types::Serialiser::error>,
 respectively. They are overloaded to act almost exactly like the numbers
-C<1> and C<0>. You can check whether a scalar is a CBOR boolean by using
-the C<CBOR::XS::is_bool> function.
+C<1> and C<0> (for true and false) or to throw an exception on access (for
+error). See the L<Types::Serialiser> manpage for details.
+
+=item CBOR tag 256 (perl object)
+
+The tag value C<256> (TODO: pending iana registration) will be used to
+deserialise a Perl object.
+
+TODO For this to work, the class must be loaded and must have a
+C<FROM_CBOR> method. The decoder will then call the C<FROM_CBOR> method
+with the constructor arguments provided by the C<TO_CBOR> method (see
+below).
 
-=item null, undefined
+The C<FROM_CBOR> method must return a single value that will then be used
+as the deserialised value.
 
-CBOR null and undefined values becomes C<undef> in Perl (in the future,
-Undefined may raise an exception or something else).
+=item CBOR tag 55799 (magic header)
 
-=item tags
+The tag 55799 is ignored (this tag implements the magic header).
 
-Tagged items consists of a numeric tag and another CBOR value. The tag
-55799 is ignored (this tag implements the magic header).
+=item other CBOR tags
 
-All other tags are currently converted into a L<CBOR::XS::Tagged> object,
-which is simply a blessed array reference consistsing of the numeric tag
-value followed by the (decoded) BOR value.
+Tagged items consists of a numeric tag and another CBOR value. Tags not
+handled internally are currently converted into a L<CBOR::XS::Tagged>
+object, which is simply a blessed array reference consisting of the
+numeric tag value followed by the (decoded) CBOR value.
+
+In the future, support for user-supplied conversions might get added.
 
 =item anything else
 
@@ -250,10 +288,11 @@
 pair. The (numerical) tag will be encoded as a CBOR tag, the value will be
 encoded as appropriate for the value.
 
-=item CBOR::XS::true, CBOR::XS::false
+=item Types::Serialiser::true, Types::Serialiser::false, Types::Serialiser::error
 
-These special values become CBOR true and CBOR false values,
-respectively. You can also use C<\1> and C<\0> directly if you want.
+These special values become CBOR true, CBOR false and CBOR undefined
+values, respectively. You can also use C<\1>, C<\0> and C<\undef> directly
+if you want.
 
 =item blessed objects
 
@@ -411,34 +450,16 @@
 
 =cut
 
-our $true  = do { bless \(my $dummy = 1), "CBOR::XS::Boolean" };
-our $false = do { bless \(my $dummy = 0), "CBOR::XS::Boolean" };
-
-sub true()  { $true  }
-sub false() { $false }
-
-sub is_bool($) {
-   UNIVERSAL::isa $_[0], "CBOR::XS::Boolean"
-#      or UNIVERSAL::isa $_[0], "CBOR::Literal"
-}
-
 XSLoader::load "CBOR::XS", $VERSION;
 
-package CBOR::XS::Boolean;
-
-use overload
-   "0+"     => sub { ${$_[0]} },
-   "++"     => sub { $_[0] = ${$_[0]} + 1 },
-   "--"     => sub { $_[0] = ${$_[0]} - 1 },
-   fallback => 1;
-
-1;
-
 =head1 SEE ALSO
 
 The L<JSON> and L<JSON::XS> modules that do similar, but human-readable,
 serialisation.
 
+The L<Types::Serialiser> module provides the data model for true, false
+and error values.
+
 =head1 AUTHOR
 
  Marc Lehmann <schmorp@schmorp.de>
@@ -446,3 +467,5 @@
 
 =cut
 
+1
+