| 1 |
root |
1.2 |
NAME |
| 2 |
|
|
Types::Serialiser - simple data types for common serialisation formats |
| 3 |
|
|
|
| 4 |
|
|
SYNOPSIS |
| 5 |
|
|
DESCRIPTION |
| 6 |
|
|
This module provides some extra datatypes that are used by common |
| 7 |
|
|
serialisation formats such as JSON or CBOR. The idea is to have a |
| 8 |
|
|
repository of simple/small constants and containers that can be shared |
| 9 |
|
|
by different implementations so they become interoperable between each |
| 10 |
|
|
other. |
| 11 |
|
|
|
| 12 |
|
|
SIMPLE SCALAR CONSTANTS |
| 13 |
|
|
Simple scalar constants are values that are overloaded to act like |
| 14 |
|
|
simple Perl values, but have (class) type to differentiate them from |
| 15 |
|
|
normal Perl scalars. This is necessary because these have different |
| 16 |
|
|
representations in the serialisation formats. |
| 17 |
|
|
|
| 18 |
|
|
BOOLEANS (Types::Serialiser::Boolean class) |
| 19 |
|
|
This type has only two instances, true and false. A natural |
| 20 |
|
|
representation for these in Perl is 1 and 0, but serialisation formats |
| 21 |
|
|
need to be able to differentiate between them and mere numbers. |
| 22 |
|
|
|
| 23 |
|
|
$Types::Serialiser::true, Types::Serialiser::true |
| 24 |
|
|
This value represents the "true" value. In most contexts is acts |
| 25 |
|
|
like the number 1. It is up to you whether you use the variable form |
| 26 |
|
|
($Types::Serialiser::true) or the constant form |
| 27 |
|
|
("Types::Serialiser::true"). |
| 28 |
|
|
|
| 29 |
|
|
The constant is represented as a reference to a scalar containing 1 |
| 30 |
|
|
- implementations are allowed to directly test for this. |
| 31 |
|
|
|
| 32 |
|
|
$Types::Serialiser::false, Types::Serialiser::false |
| 33 |
|
|
This value represents the "false" value. In most contexts is acts |
| 34 |
|
|
like the number 0. It is up to you whether you use the variable form |
| 35 |
|
|
($Types::Serialiser::false) or the constant form |
| 36 |
|
|
("Types::Serialiser::false"). |
| 37 |
|
|
|
| 38 |
|
|
The constant is represented as a reference to a scalar containing 0 |
| 39 |
|
|
- implementations are allowed to directly test for this. |
| 40 |
|
|
|
| 41 |
|
|
$is_bool = Types::Serialiser::is_bool $value |
| 42 |
|
|
Returns true iff the $value is either $Types::Serialiser::true or |
| 43 |
|
|
$Types::Serialiser::false. |
| 44 |
|
|
|
| 45 |
|
|
For example, you could differentiate between a perl true value and a |
| 46 |
|
|
"Types::Serialiser::true" by using this: |
| 47 |
|
|
|
| 48 |
|
|
$value && Types::Serialiser::is_bool $value |
| 49 |
|
|
|
| 50 |
|
|
$is_true = Types::Serialiser::is_true $value |
| 51 |
|
|
Returns true iff $value is $Types::Serialiser::true. |
| 52 |
|
|
|
| 53 |
|
|
$is_false = Types::Serialiser::is_false $value |
| 54 |
|
|
Returns false iff $value is $Types::Serialiser::false. |
| 55 |
|
|
|
| 56 |
|
|
ERROR (Types::Serialiser::Error class) |
| 57 |
|
|
This class has only a single instance, "error". It is used to signal an |
| 58 |
|
|
encoding or decoding error. In CBOR for example, and object that |
| 59 |
|
|
couldn't be encoded will be represented by a CBOR undefined value, which |
| 60 |
|
|
is represented by the error value in Perl. |
| 61 |
|
|
|
| 62 |
|
|
$Types::Serialiser::error, Types::Serialiser::error |
| 63 |
|
|
This value represents the "error" value. Accessing values of this |
| 64 |
|
|
type will throw an exception. |
| 65 |
|
|
|
| 66 |
|
|
The constant is represented as a reference to a scalar containing |
| 67 |
|
|
"undef" - implementations are allowed to directly test for this. |
| 68 |
|
|
|
| 69 |
|
|
$is_error = Types::Serialiser::is_error $value |
| 70 |
|
|
Returns false iff $value is $Types::Serialiser::error. |
| 71 |
|
|
|
| 72 |
|
|
NOTES FOR XS USERS |
| 73 |
|
|
The recommended way to detect whether a scalar is one of these objects |
| 74 |
|
|
is to check whether the stash is the "Types::Serialiser::Boolean" or |
| 75 |
|
|
"Types::Serialiser::Error" stash, and then follow the scalar reference |
| 76 |
|
|
to see if it's 1 (true), 0 (false) or "undef" (error). |
| 77 |
|
|
|
| 78 |
|
|
While it is possible to use an isa test, directly comparing stash |
| 79 |
|
|
pointers is faster and guaranteed to work. |
| 80 |
|
|
|
| 81 |
|
|
BUGS |
| 82 |
|
|
The use of overload makes this module much heavier than it should be (on |
| 83 |
|
|
my system, this module: 4kB RSS, overload: 260kB RSS). |
| 84 |
|
|
|
| 85 |
|
|
SEE ALSO |
| 86 |
|
|
Currently, JSON::XS and CBOR::XS use these types. |
| 87 |
|
|
|
| 88 |
|
|
AUTHOR |
| 89 |
|
|
Marc Lehmann <schmorp@schmorp.de> |
| 90 |
|
|
http://home.schmorp.de/ |
| 91 |
|
|
|
