--- CBOR-XS/XS.pm	2013/10/26 11:08:34	1.3
+++ 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
@@ -165,17 +186,71 @@
 
 =over 4
 
-=item True, False
+=item integers
+
+CBOR integers become (numeric) perl scalars. On perls without 64 bit
+support, 64 bit integers will be truncated or otherwise corrupted.
+
+=item byte strings
+
+Byte strings will become octet strings in Perl (the byte values 0..255
+will simply become characters of the same value in Perl).
+
+=item UTF-8 strings
+
+UTF-8 strings in CBOR will be decoded, i.e. the UTF-8 octets will be
+decoded into proper Unicode code points. At the moment, the validity of
+the UTF-8 octets will not be validated - corrupt input will result in
+corrupted Perl strings.
 
-These CBOR values become C<CBOR::XS::true> and C<CBOR::XS::false>,
+=item arrays, maps
+
+CBOR arrays and CBOR maps will be converted into references to a Perl
+array or hash, respectively. The keys of the map will be stringified
+during this process.
+
+=item null
+
+CBOR null becomes C<undef> in Perl.
+
+=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).
+
+The C<FROM_CBOR> method must return a single value that will then be used
+as the deserialised value.
 
-=item Null, Undefined
+=item CBOR tag 55799 (magic header)
 
-CBOR Null and Undefined values becomes C<undef> in Perl (in the future,
-Undefined may raise an exception).
+The tag 55799 is ignored (this tag implements the magic header).
+
+=item other CBOR tags
+
+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
+
+Anything else (e.g. unsupported simple values) will raise a decoding
+error.
 
 =back
 
@@ -190,40 +265,47 @@
 
 =item hash references
 
-Perl hash references become CBOR maps. As there is no inherent ordering
-in hash keys (or CBOR maps), they will usually be encoded in a
-pseudo-random order.
+Perl hash references become CBOR maps. As there is no inherent ordering in
+hash keys (or CBOR maps), they will usually be encoded in a pseudo-random
+order.
+
+Currently, tied hashes will use the indefinite-length format, while normal
+hashes will use the fixed-length format.
 
 =item array references
 
-Perl array references become CBOR arrays.
+Perl array references become fixed-length CBOR arrays.
 
 =item other references
 
 Other unblessed references are generally not allowed and will cause an
 exception to be thrown, except for references to the integers C<0> and
-C<1>, which get turned into C<False> and C<True> in CBOR.
+C<1>, which get turned into false and true in CBOR.
+
+=item CBOR::XS::Tagged objects
+
+Objects of this type must be arrays consisting of a single C<[tag, value]>
+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
 
-Blessed objects are not directly representable in CBOR. TODO
-See the
-C<allow_blessed> and C<convert_blessed> methods on various options on
-how to deal with this: basically, you can choose between throwing an
-exception, encoding the reference as if it weren't blessed, or provide
-your own serialiser method.
+Other blessed objects currently need to have a C<TO_CBOR> method. It
+will be called on every object that is being serialised, and must return
+something that can be encoded in CBOR.
 
 =item simple scalars
 
 TODO
 Simple Perl scalars (any scalar that is not a reference) are the most
 difficult objects to encode: CBOR::XS will encode undefined scalars as
-CBOR C<Null> values, scalars that have last been used in a string context
+CBOR null values, scalars that have last been used in a string context
 before encoding as CBOR strings, and anything else as number value:
 
    # dump as number
@@ -255,12 +337,12 @@
 if you need this capability (but don't forget to explain why it's needed
 :).
 
-Note that numerical precision has the same meaning as under Perl (so
-binary to decimal conversion follows the same rules as in Perl, which
-can differ to other languages). Also, your perl interpreter might expose
-extensions to the floating point numbers of your platform, such as
-infinities or NaN's - these cannot be represented in CBOR, and it is an
-error to pass those in.
+Perl values that seem to be integers generally use the shortest possible
+representation. Floating-point values will use either the IEEE single
+format if possible without loss of precision, otherwise the IEEE double
+format will be used. Perls that use formats other than IEEE double to
+represent numerical values are supported, but might suffer loss of
+precision.
 
 =back
 
@@ -280,7 +362,17 @@
 
 =head2 CBOR and JSON
 
-TODO
+CBOR is supposed to implement a superset of the JSON data model, and is,
+with some coercion, able to represent all JSON texts (something that other
+"binary JSON" formats such as BSON generally do not support).
+
+CBOR implements some extra hints and support for JSON interoperability,
+and the spec offers further guidance for conversion between CBOR and
+JSON. None of this is currently implemented in CBOR, and the guidelines
+in the spec do not result in correct round-tripping of data. If JSON
+interoperability is improved in the future, then the goal will be to
+ensure that decoded JSON data will round-trip encoding and decoding to
+CBOR intact.
 
 
 =head1 SECURITY CONSIDERATIONS
@@ -358,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>
@@ -393,3 +467,5 @@
 
 =cut
 
+1
+