… | |
… | |
12 | SIMPLE SCALAR CONSTANTS |
12 | SIMPLE SCALAR CONSTANTS |
13 | Simple scalar constants are values that are overloaded to act like |
13 | Simple scalar constants are values that are overloaded to act like |
14 | simple Perl values, but have (class) type to differentiate them from |
14 | simple Perl values, but have (class) type to differentiate them from |
15 | normal Perl scalars. This is necessary because these have different |
15 | normal Perl scalars. This is necessary because these have different |
16 | representations in the serialisation formats. |
16 | representations in the serialisation formats. |
|
|
17 | |
|
|
18 | In the following, functions with zero or one arguments have a prototype |
|
|
19 | of "()" and "($)", respectively, so act as constants and unary |
|
|
20 | operators. |
17 | |
21 | |
18 | BOOLEANS (Types::Serialiser::Boolean class) |
22 | BOOLEANS (Types::Serialiser::Boolean class) |
19 | This type has only two instances, true and false. A natural |
23 | This type has only two instances, true and false. A natural |
20 | representation for these in Perl is 1 and 0, but serialisation formats |
24 | representation for these in Perl is 1 and 0, but serialisation formats |
21 | need to be able to differentiate between them and mere numbers. |
25 | need to be able to differentiate between them and mere numbers. |
… | |
… | |
35 | ($Types::Serialiser::false) or the constant form |
39 | ($Types::Serialiser::false) or the constant form |
36 | ("Types::Serialiser::false"). |
40 | ("Types::Serialiser::false"). |
37 | |
41 | |
38 | The constant is represented as a reference to a scalar containing 0 |
42 | The constant is represented as a reference to a scalar containing 0 |
39 | - implementations are allowed to directly test for this. |
43 | - implementations are allowed to directly test for this. |
|
|
44 | |
|
|
45 | Types::Serialiser::as_bool $value |
|
|
46 | Converts a Perl scalar into a boolean, which is useful syntactic |
|
|
47 | sugar. Strictly equivalent to: |
|
|
48 | |
|
|
49 | $value ? $Types::Serialiser::true : $Types::Serialiser::false |
40 | |
50 | |
41 | $is_bool = Types::Serialiser::is_bool $value |
51 | $is_bool = Types::Serialiser::is_bool $value |
42 | Returns true iff the $value is either $Types::Serialiser::true or |
52 | Returns true iff the $value is either $Types::Serialiser::true or |
43 | $Types::Serialiser::false. |
53 | $Types::Serialiser::false. |
44 | |
54 | |
… | |
… | |
76 | to see if it's 1 (true), 0 (false) or "undef" (error). |
86 | to see if it's 1 (true), 0 (false) or "undef" (error). |
77 | |
87 | |
78 | While it is possible to use an isa test, directly comparing stash |
88 | While it is possible to use an isa test, directly comparing stash |
79 | pointers is faster and guaranteed to work. |
89 | pointers is faster and guaranteed to work. |
80 | |
90 | |
|
|
91 | For historical reasons, the "Types::Serialiser::Boolean" stash is just |
|
|
92 | an alias for "JSON::PP::Boolean". When printed, the classname with |
|
|
93 | usually be "JSON::PP::Boolean", but isa tests and stash pointer |
|
|
94 | comparison will normally work correctly (i.e. Types::Serialiser::true |
|
|
95 | ISA JSON::PP::Boolean, but also ISA Types::Serialiser::Boolean). |
|
|
96 | |
|
|
97 | A GENERIC OBJECT SERIALIATION PROTOCOL |
|
|
98 | This section explains the object serialisation protocol used by |
|
|
99 | CBOR::XS. It is meant to be generic enough to support any kind of |
|
|
100 | generic object serialiser. |
|
|
101 | |
|
|
102 | This protocol is called "the Types::Serialiser object serialisation |
|
|
103 | protocol". |
|
|
104 | |
|
|
105 | ENCODING |
|
|
106 | When the encoder encounters an object that it cannot otherwise encode |
|
|
107 | (for example, CBOR::XS can encode a few special types itself, and will |
|
|
108 | first attempt to use the special "TO_CBOR" serialisation protocol), it |
|
|
109 | will look up the "FREEZE" method on the object. |
|
|
110 | |
|
|
111 | Note that the "FREEZE" method will normally be called *during* encoding, |
|
|
112 | and *MUST NOT* change the data structure that is being encoded in any |
|
|
113 | way, or it might cause memory corruption or worse. |
|
|
114 | |
|
|
115 | If it exists, it will call it with two arguments: the object to |
|
|
116 | serialise, and a constant string that indicates the name of the data |
|
|
117 | model. For example CBOR::XS uses "CBOR", and the JSON and JSON::XS |
|
|
118 | modules (or any other JSON serialiser), would use "JSON" as second |
|
|
119 | argument. |
|
|
120 | |
|
|
121 | The "FREEZE" method can then return zero or more values to identify the |
|
|
122 | object instance. The serialiser is then supposed to encode the class |
|
|
123 | name and all of these return values (which must be encodable in the |
|
|
124 | format) using the relevant form for Perl objects. In CBOR for example, |
|
|
125 | there is a registered tag number for encoded perl objects. |
|
|
126 | |
|
|
127 | The values that "FREEZE" returns must be serialisable with the |
|
|
128 | serialiser that calls it. Therefore, it is recommended to use simple |
|
|
129 | types such as strings and numbers, and maybe array references and hashes |
|
|
130 | (basically, the JSON data model). You can always use a more complex |
|
|
131 | format for a specific data model by checking the second argument, the |
|
|
132 | data model. |
|
|
133 | |
|
|
134 | The "data model" is not the same as the "data format" - the data model |
|
|
135 | indicates what types and kinds of return values can be returned from |
|
|
136 | "FREEZE". For example, in "CBOR" it is permissible to return tagged CBOR |
|
|
137 | values, while JSON does not support these at all, so "JSON" would be a |
|
|
138 | valid (but too limited) data model name for "CBOR::XS". similarly, a |
|
|
139 | serialising format that supports more or less the same data model as |
|
|
140 | JSON could use "JSON" as data model without losing anything. |
|
|
141 | |
|
|
142 | DECODING |
|
|
143 | When the decoder then encounters such an encoded perl object, it should |
|
|
144 | look up the "THAW" method on the stored classname, and invoke it with |
|
|
145 | the classname, the constant string to identify the data model/data |
|
|
146 | format, and all the return values returned by "FREEZE". |
|
|
147 | |
|
|
148 | EXAMPLES |
|
|
149 | See the "OBJECT SERIALISATION" section in the CBOR::XS manpage for more |
|
|
150 | details, an example implementation, and code examples. |
|
|
151 | |
|
|
152 | Here is an example "FREEZE"/"THAW" method pair: |
|
|
153 | |
|
|
154 | sub My::Object::FREEZE { |
|
|
155 | my ($self, $model) = @_; |
|
|
156 | |
|
|
157 | ($self->{type}, $self->{id}, $self->{variant}) |
|
|
158 | } |
|
|
159 | |
|
|
160 | sub My::Object::THAW { |
|
|
161 | my ($class, $model, $type, $id, $variant) = @_; |
|
|
162 | |
|
|
163 | $class->new (type => $type, id => $id, variant => $variant) |
|
|
164 | } |
|
|
165 | |
81 | BUGS |
166 | BUGS |
82 | The use of overload makes this module much heavier than it should be (on |
167 | The use of overload makes this module much heavier than it should be (on |
83 | my system, this module: 4kB RSS, overload: 260kB RSS). |
168 | my system, this module: 4kB RSS, overload: 260kB RSS). |
84 | |
169 | |
85 | SEE ALSO |
170 | SEE ALSO |