|
|
1 | 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 | |
