--- Types-Serialiser/README	2013/10/27 19:49:33	1.1
+++ Types-Serialiser/README	2013/10/27 20:17:16	1.2
@@ -0,0 +1,91 @@
+NAME
+    Types::Serialiser - simple data types for common serialisation formats
+
+SYNOPSIS
+DESCRIPTION
+    This module provides some extra datatypes that are used by common
+    serialisation formats such as JSON or CBOR. The idea is to have a
+    repository of simple/small constants and containers that can be shared
+    by different implementations so they become interoperable between each
+    other.
+
+SIMPLE SCALAR CONSTANTS
+    Simple scalar constants are values that are overloaded to act like
+    simple Perl values, but have (class) type to differentiate them from
+    normal Perl scalars. This is necessary because these have different
+    representations in the serialisation formats.
+
+  BOOLEANS (Types::Serialiser::Boolean class)
+    This type has only two instances, true and false. A natural
+    representation for these in Perl is 1 and 0, but serialisation formats
+    need to be able to differentiate between them and mere numbers.
+
+    $Types::Serialiser::true, Types::Serialiser::true
+        This value represents the "true" value. In most contexts is acts
+        like the number 1. It is up to you whether you use the variable form
+        ($Types::Serialiser::true) or the constant form
+        ("Types::Serialiser::true").
+
+        The constant is represented as a reference to a scalar containing 1
+        - implementations are allowed to directly test for this.
+
+    $Types::Serialiser::false, Types::Serialiser::false
+        This value represents the "false" value. In most contexts is acts
+        like the number 0. It is up to you whether you use the variable form
+        ($Types::Serialiser::false) or the constant form
+        ("Types::Serialiser::false").
+
+        The constant is represented as a reference to a scalar containing 0
+        - implementations are allowed to directly test for this.
+
+    $is_bool = Types::Serialiser::is_bool $value
+        Returns true iff the $value is either $Types::Serialiser::true or
+        $Types::Serialiser::false.
+
+        For example, you could differentiate between a perl true value and a
+        "Types::Serialiser::true" by using this:
+
+           $value && Types::Serialiser::is_bool $value
+
+    $is_true = Types::Serialiser::is_true $value
+        Returns true iff $value is $Types::Serialiser::true.
+
+    $is_false = Types::Serialiser::is_false $value
+        Returns false iff $value is $Types::Serialiser::false.
+
+  ERROR (Types::Serialiser::Error class)
+    This class has only a single instance, "error". It is used to signal an
+    encoding or decoding error. In CBOR for example, and object that
+    couldn't be encoded will be represented by a CBOR undefined value, which
+    is represented by the error value in Perl.
+
+    $Types::Serialiser::error, Types::Serialiser::error
+        This value represents the "error" value. Accessing values of this
+        type will throw an exception.
+
+        The constant is represented as a reference to a scalar containing
+        "undef" - implementations are allowed to directly test for this.
+
+    $is_error = Types::Serialiser::is_error $value
+        Returns false iff $value is $Types::Serialiser::error.
+
+NOTES FOR XS USERS
+    The recommended way to detect whether a scalar is one of these objects
+    is to check whether the stash is the "Types::Serialiser::Boolean" or
+    "Types::Serialiser::Error" stash, and then follow the scalar reference
+    to see if it's 1 (true), 0 (false) or "undef" (error).
+
+    While it is possible to use an isa test, directly comparing stash
+    pointers is faster and guaranteed to work.
+
+BUGS
+    The use of overload makes this module much heavier than it should be (on
+    my system, this module: 4kB RSS, overload: 260kB RSS).
+
+SEE ALSO
+    Currently, JSON::XS and CBOR::XS use these types.
+
+AUTHOR
+     Marc Lehmann <schmorp@schmorp.de>
+     http://home.schmorp.de/
+