ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Types-Serialiser/Serialiser.pm
(Generate patch)

Comparing Types-Serialiser/Serialiser.pm (file contents):
Revision 1.7 by root, Tue Oct 29 18:33:11 2013 UTC vs.
Revision 1.8 by root, Mon Nov 4 15:12:16 2013 UTC

… …
157While it is possible to use an isa test, directly comparing stash pointers 157While it is possible to use an isa test, directly comparing stash pointers
158is faster and guaranteed to work. 158is faster and guaranteed to work.
159 159
160For historical reasons, the C<Types::Serialiser::Boolean> stash is 160For historical reasons, the C<Types::Serialiser::Boolean> stash is
161just an alias for C<JSON::PP::Boolean>. When printed, the classname 161just an alias for C<JSON::PP::Boolean>. When printed, the classname
162withh usually be C<JSON::PP::Boolean>, but isa tests and stash pointer 162with usually be C<JSON::PP::Boolean>, but isa tests and stash pointer
163comparison will normally work correctly (i.e. Types::Serialiser::true ISA 163comparison will normally work correctly (i.e. Types::Serialiser::true ISA
164JSON::PP::Boolean, but also ISA Types::Serialiser::Boolean). 164JSON::PP::Boolean, but also ISA Types::Serialiser::Boolean).
165 165
166=head1 A GENERIC OBJECT SERIALIATION PROTOCOL 166=head1 A GENERIC OBJECT SERIALIATION PROTOCOL
167 167
… …
177When the encoder encounters an object that it cannot otherwise encode (for 177When the encoder encounters an object that it cannot otherwise encode (for
178example, L<CBOR::XS> can encode a few special types itself, and will first 178example, L<CBOR::XS> can encode a few special types itself, and will first
179attempt to use the special C<TO_CBOR> serialisation protocol), it will 179attempt to use the special C<TO_CBOR> serialisation protocol), it will
180look up the C<FREEZE> method on the object. 180look up the C<FREEZE> method on the object.
181 181
182If it exists, it will call it with two arguments: the object to 182If it exists, it will call it with two arguments: the object to serialise,
183serialise, and a constant string that indicates the name of the 183and a constant string that indicates the name of the data model or data
184serialisationformat. For example L<CBOR::XS> uses C<CBOR>, and L<JSON> and 184format. For example L<CBOR::XS> uses C<CBOR>, and L<JSON> and L<JSON::XS>
185L<JSON::XS> (or any other JSON serialiser), would use C<JSON> as second 185(or any other JSON serialiser), would use C<JSON> as second argument.
186argument.
187 186
188The C<FREEZE> method can then return zero or more values to identify the 187The C<FREEZE> method can then return zero or more values to identify the
189object instance. The serialiser is then supposed to encode the class name 188object instance. The serialiser is then supposed to encode the class name
190and all of these return values (which must be encodable in the format) 189and all of these return values (which must be encodable in the format)
191using the relevant form for perl objects. In CBOR for example, there is a 190using the relevant form for perl objects. In CBOR for example, there is a
… …
193 192
194The values that C<FREEZE> returns must be serialisable with the serialiser 193The values that C<FREEZE> returns must be serialisable with the serialiser
195that calls it. Therefore, it is recommended to use simple types such as 194that calls it. Therefore, it is recommended to use simple types such as
196strings and numbers, and maybe array references and hashes (basically, the 195strings and numbers, and maybe array references and hashes (basically, the
197JSON data model). You can always use a more complex format for a specific 196JSON data model). You can always use a more complex format for a specific
198serialiser by checking the second argument. 197data model by checking the second argument.
199 198
200=head2 DECODING 199=head2 DECODING
201 200
202When the decoder then encounters such an encoded perl object, it should 201When the decoder then encounters such an encoded perl object, it should
203look up the C<THAW> method on the stored classname, and invoke it with the 202look up the C<THAW> method on the stored classname, and invoke it with the
204classname, the constant string to identify the format, and all the return 203classname, the constant string to identify the data model/data format, and
205values returned by C<FREEZE>. 204all the return values returned by C<FREEZE>.
206 205
207=head2 EXAMPLES 206=head2 EXAMPLES
208 207
209See the C<OBJECT SERIALISATION> section in the L<CBOR::XS> manpage for 208See the C<OBJECT SERIALISATION> section in the L<CBOR::XS> manpage for
210more details, an example implementation, and code examples. 209more details, an example implementation, and code examples.
211 210
212Here is an example C<FREEZE>/C<THAW> method pair: 211Here is an example C<FREEZE>/C<THAW> method pair:
213 212
214 sub My::Object::FREEZE { 213 sub My::Object::FREEZE {
215 my ($self, $serialiser) = @_; 214 my ($self, $model) = @_;
216 215
217 ($self->{type}, $self->{id}, $self->{variant}) 216 ($self->{type}, $self->{id}, $self->{variant})
218 } 217 }
219 218
220 sub My::Object::THAW { 219 sub My::Object::THAW {
221 my ($class, $serialiser, $type, $id, $variant) = @_; 220 my ($class, $model, $type, $id, $variant) = @_;
222 221
223 $class->new (type => $type, id => $id, variant => $variant) 222 $class->new (type => $type, id => $id, variant => $variant)
224 } 223 }
225 224
226=head1 BUGS 225=head1 BUGS

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines