[ViewVC] Diff of: cvs/CBOR-XS/README

Comparing CBOR-XS/README (file contents):
Revision 1.3 by root, Sat Oct 26 11:08:34 2013 UTC vs.
Revision 1.4 by root, Sat Oct 26 23:02:55 2013 UTC

      $coder = CBOR::XS->new;
      #TODO
 DESCRIPTION
     WARNING! THIS IS A PRE-ALPHA RELEASE! IT WILL CRASH, CORRUPT YOUR DATA
-    AND EAT YOUR CHILDREN!
+    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 CBOR and vice versa. Its
+    This module converts Perl data structures to the Concise Binary Object
-    primary goal is to be *correct* and its secondary goal is to be *fast*.
+    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.
+    The primary goal of this module is to be *correct* and the secondary
-    To reach the latter goal it was written in C.
+    goal is to be *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.
 FUNCTIONAL INTERFACE
     For the more enlightened: note that in the following descriptions,
     lowercase *perl* refers to the Perl interpreter, while uppercase *Perl*
     refers to the abstract Perl language itself.
   CBOR -> PERL
+    integers
+        CBOR integers become (numeric) perl scalars. On perls without 64 bit
+        support, 64 bit integers will be truncated or otherwise corrupted.
+    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).
+    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.
+    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.
-    True, False
+    true, false
         These CBOR values become "CBOR::XS::true" and "CBOR::XS::false",
         respectively. They are overloaded to act almost exactly like the
         numbers 1 and 0. You can check whether a scalar is a CBOR boolean by
         using the "CBOR::XS::is_bool" function.
-    Null, Undefined
+    null, undefined
-        CBOR Null and Undefined values becomes "undef" in Perl (in the
+        CBOR null and undefined values becomes "undef" in Perl (in the
-        future, Undefined may raise an exception).
+        future, Undefined may raise an exception or something else).
+    tags
+        Tagged items consists of a numeric tag and another CBOR value. The
+        tag 55799 is ignored (this tag implements the magic header).
+        All other tags are currently converted into a CBOR::XS::Tagged
+        object, which is simply a blessed array reference consistsing of the
+        numeric tag value followed by the (decoded) BOR value.
+    anything else
+        Anything else (e.g. unsupported simple values) will raise a decoding
+        error.
   PERL -> CBOR
     The mapping from Perl to CBOR is slightly more difficult, as Perl is a
     truly typeless language, so we can only guess which CBOR type is meant
     by a Perl value.
     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.
+        Currently, tied hashes will use the indefinite-length format, while
+        normal hashes will use the fixed-length format.
     array references
-        Perl array references become CBOR arrays.
+        Perl array references become fixed-length CBOR arrays.
     other references
         Other unblessed references are generally not allowed and will cause
         an exception to be thrown, except for references to the integers 0
-        and 1, which get turned into "False" and "True" in CBOR.
+        and 1, which get turned into false and true in CBOR.
+    CBOR::XS::Tagged objects
+        Objects of this type must be arrays consisting of a single "[tag,
+        value]" pair. The (numerical) tag will be encoded as a CBOR tag, the
+        value will be encoded as appropriate for the value.
     CBOR::XS::true, CBOR::XS::false
-        These special values become CBOR True and CBOR False values,
+        These special values become CBOR true and CBOR false values,
         respectively. You can also use "\1" and "\0" directly if you want.
     blessed objects
-        Blessed objects are not directly representable in CBOR. TODO See the
+        Other blessed objects currently need to have a "TO_CBOR" method. It
-        "allow_blessed" and "convert_blessed" methods on various options on
+        will be called on every object that is being serialised, and must
-        how to deal with this: basically, you can choose between throwing an
+        return something that can be encoded in CBOR.
-        exception, encoding the reference as if it weren't blessed, or
-        provide your own serialiser method.
     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 "Null" values, scalars that have last been used in a
+        scalars as 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
            encode_cbor [2]                      # yields [2]
         You can not currently force the type in other, less obscure, ways.
         Tell me 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
+        Perl values that seem to be integers generally use the shortest
-        binary to decimal conversion follows the same rules as in Perl,
+        possible representation. Floating-point values will use either the
-        which can differ to other languages). Also, your perl interpreter
+        IEEE single format if possible without loss of precision, otherwise
-        might expose extensions to the floating point numbers of your
+        the IEEE double format will be used. Perls that use formats other
-        platform, such as infinities or NaN's - these cannot be represented
+        than IEEE double to represent numerical values are supported, but
-        in CBOR, and it is an error to pass those in.
+        might suffer loss of precision.
   MAGIC HEADER
     There is no way to distinguish CBOR from other formats programmatically.
     To make it easier to distinguish CBOR from other formats, the CBOR
     specification has a special "magic string" that can be prepended to any
     prepend this string tot he CBOR data it generates, but it will ignroe it
     if present, so users can prepend this string as a "file type" indicator
     as required.
   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.
 SECURITY CONSIDERATIONS
     When you are using CBOR in a protocol, talking to untrusted potentially
     hostile creatures requires relatively few measures.

Diff Legend

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

Comparing CBOR-XS/README (file contents): Revision 1.3 by root, Sat Oct 26 11:08:34 2013 UTC vs. Revision 1.4 by root, Sat Oct 26 23:02:55 2013 UTC

Diff Legend

Comparing CBOR-XS/README (file contents):
Revision 1.3 by root, Sat Oct 26 11:08:34 2013 UTC vs.
Revision 1.4 by root, Sat Oct 26 23:02:55 2013 UTC