|
|
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 | For historical reasons, the "Types::Serialiser::Boolean" stash is just |
|
|
82 | an alias for "JSON::PP::Boolean". When printed, the classname withh |
|
|
83 | usually be "JSON::PP::Boolean", but isa tests and stash pointer |
|
|
84 | comparison will normally work correctly (i.e. Types::Serialiser::true |
|
|
85 | ISA JSON::PP::Boolean, but also ISA Types::Serialiser::Boolean). |
|
|
86 | |
|
|
87 | A GENERIC OBJECT SERIALIATION PROTOCOL |
|
|
88 | This section explains the object serialisation protocol used by |
|
|
89 | CBOR::XS. It is meant to be generic enough to support any kind of |
|
|
90 | generic object serialiser. |
|
|
91 | |
|
|
92 | This protocol is called "the Types::Serialiser object serialisation |
|
|
93 | protocol". |
|
|
94 | |
|
|
95 | ENCODING |
|
|
96 | When the encoder encounters an object that it cannot otherwise encode |
|
|
97 | (for example, CBOR::XS can encode a few special types itself, and will |
|
|
98 | first attempt to use the special "TO_CBOR" serialisation protocol), it |
|
|
99 | will look up the "FREEZE" method on the object. |
|
|
100 | |
|
|
101 | If it exists, it will call it with two arguments: the object to |
|
|
102 | serialise, and a constant string that indicates the name of the |
|
|
103 | serialisationformat. For example CBOR::XS uses "CBOR", and JSON and |
|
|
104 | JSON::XS (or any other JSON serialiser), would use "JSON" as second |
|
|
105 | argument. |
|
|
106 | |
|
|
107 | The "FREEZE" method can then return zero or more values to identify the |
|
|
108 | object instance. The serialiser is then supposed to encode the class |
|
|
109 | name and all of these return values (which must be encodable in the |
|
|
110 | format) using the relevant form for perl objects. In CBOR for example, |
|
|
111 | there is a registered tag number for encoded perl objects. |
|
|
112 | |
|
|
113 | The values that "FREEZE" returns must be serialisable with the |
|
|
114 | serialiser that calls it. Therefore, it is recommended to use simple |
|
|
115 | types such as strings and numbers, and maybe array references and hashes |
|
|
116 | (basically, the JSON data model). You can always use a more complex |
|
|
117 | format for a specific serialiser by checking the second argument. |
|
|
118 | |
|
|
119 | DECODING |
|
|
120 | When the decoder then encounters such an encoded perl object, it should |
|
|
121 | look up the "THAW" method on the stored classname, and invoke it with |
|
|
122 | the classname, the constant string to identify the format, and all the |
|
|
123 | return values returned by "FREEZE". |
|
|
124 | |
|
|
125 | EXAMPLES |
|
|
126 | See the "OBJECT SERIALISATION" section in the CBOR::XS manpage for more |
|
|
127 | details, an example implementation, and code examples. |
|
|
128 | |
|
|
129 | Here is an example "FREEZE"/"THAW" method pair: |
|
|
130 | |
|
|
131 | sub My::Object::FREEZE { |
|
|
132 | my ($self, $serialiser) = @_; |
|
|
133 | |
|
|
134 | ($self->{type}, $self->{id}, $self->{variant}) |
|
|
135 | } |
|
|
136 | |
|
|
137 | sub My::Object::THAW { |
|
|
138 | my ($class, $serialiser, $type, $id, $variant) = @_; |
|
|
139 | |
|
|
140 | $class-<new (type => $type, id => $id, variant => $variant) |
|
|
141 | } |
|
|
142 | |
|
|
143 | BUGS |
|
|
144 | The use of overload makes this module much heavier than it should be (on |
|
|
145 | my system, this module: 4kB RSS, overload: 260kB RSS). |
|
|
146 | |
|
|
147 | SEE ALSO |
|
|
148 | Currently, JSON::XS and CBOR::XS use these types. |
|
|
149 | |
|
|
150 | AUTHOR |
|
|
151 | Marc Lehmann <schmorp@schmorp.de> |
|
|
152 | http://home.schmorp.de/ |
|
|
153 | |