… | |
… | |
76 | to see if it's 1 (true), 0 (false) or "undef" (error). |
76 | to see if it's 1 (true), 0 (false) or "undef" (error). |
77 | |
77 | |
78 | While it is possible to use an isa test, directly comparing stash |
78 | While it is possible to use an isa test, directly comparing stash |
79 | pointers is faster and guaranteed to work. |
79 | pointers is faster and guaranteed to work. |
80 | |
80 | |
|
|
81 | For historical reasons, the "Types::Serialiser::Boolean" stash is just |
|
|
82 | an alias for "JSON::PP::Boolean". When printed, the classname with |
|
|
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 | Note that the "FREEZE" method will normally be called *during* encoding, |
|
|
102 | and *MUST NOT* change the data structure that is being encoded in any |
|
|
103 | way, or it might cause memory corruption or worse. |
|
|
104 | |
|
|
105 | If it exists, it will call it with two arguments: the object to |
|
|
106 | serialise, and a constant string that indicates the name of the data |
|
|
107 | model. For example CBOR::XS uses "CBOR", and the JSON and JSON::XS |
|
|
108 | modules (or any other JSON serialiser), would use "JSON" as second |
|
|
109 | argument. |
|
|
110 | |
|
|
111 | The "FREEZE" method can then return zero or more values to identify the |
|
|
112 | object instance. The serialiser is then supposed to encode the class |
|
|
113 | name and all of these return values (which must be encodable in the |
|
|
114 | format) using the relevant form for Perl objects. In CBOR for example, |
|
|
115 | there is a registered tag number for encoded perl objects. |
|
|
116 | |
|
|
117 | The values that "FREEZE" returns must be serialisable with the |
|
|
118 | serialiser that calls it. Therefore, it is recommended to use simple |
|
|
119 | types such as strings and numbers, and maybe array references and hashes |
|
|
120 | (basically, the JSON data model). You can always use a more complex |
|
|
121 | format for a specific data model by checking the second argument, the |
|
|
122 | data model. |
|
|
123 | |
|
|
124 | The "data model" is not the same as the "data format" - the data model |
|
|
125 | indicates what types and kinds of return values can be returned from |
|
|
126 | "FREEZE". For example, in "CBOR" it is permissible to return tagged CBOR |
|
|
127 | values, while JSON does not support these at all, so "JSON" would be a |
|
|
128 | valid (but too limited) data model name for "CBOR::XS". similarly, a |
|
|
129 | serialising format that supports more or less the same data model as |
|
|
130 | JSON could use "JSON" as data model without losing anything. |
|
|
131 | |
|
|
132 | DECODING |
|
|
133 | When the decoder then encounters such an encoded perl object, it should |
|
|
134 | look up the "THAW" method on the stored classname, and invoke it with |
|
|
135 | the classname, the constant string to identify the data model/data |
|
|
136 | format, and all the return values returned by "FREEZE". |
|
|
137 | |
|
|
138 | EXAMPLES |
|
|
139 | See the "OBJECT SERIALISATION" section in the CBOR::XS manpage for more |
|
|
140 | details, an example implementation, and code examples. |
|
|
141 | |
|
|
142 | Here is an example "FREEZE"/"THAW" method pair: |
|
|
143 | |
|
|
144 | sub My::Object::FREEZE { |
|
|
145 | my ($self, $model) = @_; |
|
|
146 | |
|
|
147 | ($self->{type}, $self->{id}, $self->{variant}) |
|
|
148 | } |
|
|
149 | |
|
|
150 | sub My::Object::THAW { |
|
|
151 | my ($class, $model, $type, $id, $variant) = @_; |
|
|
152 | |
|
|
153 | $class->new (type => $type, id => $id, variant => $variant) |
|
|
154 | } |
|
|
155 | |
81 | BUGS |
156 | BUGS |
82 | The use of overload makes this module much heavier than it should be (on |
157 | The use of overload makes this module much heavier than it should be (on |
83 | my system, this module: 4kB RSS, overload: 260kB RSS). |
158 | my system, this module: 4kB RSS, overload: 260kB RSS). |
84 | |
159 | |
85 | SEE ALSO |
160 | SEE ALSO |