--- CBOR-XS/XS.pm	2013/10/26 11:08:34	1.3
+++ CBOR-XS/XS.pm	2013/10/27 22:35:15	1.7
@@ -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 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.
+This makes it a faster and more compact binary alternative to JSON, with
+the added ability of supporting serialising of perl objects.
+
+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,64 @@
 
 =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
 
-These CBOR values become C<CBOR::XS::true> and C<CBOR::XS::false>,
+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.
+
+=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 serialised with C<FREEZE>. See "OBJECT
+SERIALISATION", below, for details.
 
-=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 +258,46 @@
 
 =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
 
-=item CBOR::XS::true, CBOR::XS::false
+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.
 
-These special values become CBOR True and CBOR False values,
-respectively. You can also use C<\1> and C<\0> directly if you want.
+=item Types::Serialiser::true, Types::Serialiser::false, Types::Serialiser::error
 
-=item blessed objects
+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.
 
-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.
+=item other blessed objects
+
+Other blessed objects are serialised via C<TO_CBOR> or C<FREEZE>. See
+"OBJECT SERIALISATION", below, for details.
 
 =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,17 +329,114 @@
 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
 
+=head2 OBJECT SERIALISATION
+
+This module knows two way to serialise a Perl object: The CBOR-specific
+way, and the generic way.
+
+Whenever the encoder encounters a Perl object that it cnanot serialise
+directly (most of them), it will first look up the C<TO_CBOR> method on
+it.
+
+If it has a C<TO_CBOR> method, it will call it with the object as only
+argument, and expects exactly one return value, which it will then
+substitute and encode it in the place of the object.
+
+Otherwise, it will look up the C<FREEZE> method. If it exists, it will
+call it with the object as first argument, and the constant string C<CBOR>
+as the second argument, to distinguish it from other serialisers.
+
+The C<FREEZE> method can return any number of values (i.e. zero or
+more). These will be encoded as CBOR perl object, together with the
+classname.
+
+If an object supports neither C<TO_CBOR> nor C<FREEZE>, encoding will fail
+with an error.
 
-=head2 MAGIC HEADER
+Objects encoded via C<TO_CBOR> cannot be automatically decoded, but
+objects encoded via C<FREEZE> can be decoded using the following protocol:
+
+When an encoded CBOR perl object is encountered by the decoder, it will
+look up the C<THAW> method, by using the stored classname, and will fail
+if the method cannot be found.
+
+After the lookup it will call the C<THAW> method with the stored classname
+as first argument, the constant string C<CBOR> as second argument, and all
+values returned by C<FREEZE> as remaining arguments.
+
+=head4 EXAMPLES
+
+Here is an example C<TO_CBOR> method:
+
+   sub My::Object::TO_CBOR {
+      my ($obj) = @_;
+
+      ["this is a serialised My::Object object", $obj->{id}]
+   }
+
+When a C<My::Object> is encoded to CBOR, it will instead encode a simple
+array with two members: a string, and the "object id". Decoding this CBOR
+string will yield a normal perl array reference in place of the object.
+
+A more useful and practical example would be a serialisation method for
+the URI module. CBOR has a custom tag value for URIs, namely 32:
+
+  sub URI::TO_CBOR {
+     my ($self) = @_;
+     my $uri = "$self"; # stringify uri
+     utf8::upgrade $uri; # make sure it will be encoded as UTF-8 string
+     CBOR::XS::tagged 32, "$_[0]"
+  }
+
+This will encode URIs as a UTF-8 string with tag 32, which indicates an
+URI.
+
+Decoding such an URI will not (currently) give you an URI object, but
+instead a CBOR::XS::Tagged object with tag number 32 and the string -
+exactly what was returned by C<TO_CBOR>.
+
+To serialise an object so it can automatically be deserialised, you need
+to use C<FREEZE> and C<THAW>. To take the URI module as example, this
+would be a possible implementation:
+
+   sub URI::FREEZE {
+      my ($self, $serialiser) = @_;
+      "$self" # encode url string
+   }
+
+   sub URI::THAW {
+      my ($class, $serialiser, $uri) = @_;
+
+      $class->new ($uri)
+   }
+
+Unlike C<TO_CBOR>, multiple values can be returned by C<FREEZE>. For
+example, a C<FREEZE> method that returns "type", "id" and "variant" values
+would cause an invocation of C<THAW> with 5 arguments:
+
+   sub My::Object::FREEZE {
+      my ($self, $serialiser) = @_;
+
+      ($self->{type}, $self->{id}, $self->{variant})
+   }
+
+   sub My::Object::THAW {
+      my ($class, $serialiser, $type, $id, $variant) = @_;
+
+      $class-<new (type => $type, id => $id, variant => $variant)
+   }
+
+
+=head1 MAGIC HEADER
 
 There is no way to distinguish CBOR from other formats
 programmatically. To make it easier to distinguish CBOR from other
@@ -278,9 +449,19 @@
 required.
 
 
-=head2 CBOR and JSON
+=head1 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 +539,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 +556,5 @@
 
 =cut
 
+1
+