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

Comparing Types-Serialiser/README (file contents):
Revision 1.2 by root, Sun Oct 27 20:17:16 2013 UTC vs.
Revision 1.3 by root, Mon Oct 28 15:29:28 2013 UTC

… …
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 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
87A 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 DECODING
114 When the decoder then encounters such an encoded perl object, it should
115 look up the "THAW" method on the stored classname, and invoke it with
116 the classname, the constant string to identify the format, and all the
117 return values returned by "FREEZE".
118
119 EXAMPLES
120 See the "OBJECT SERIALISATION" section in the CBOR::XS manpage for more
121 details, an example implementation, and code examples.
122
123 Here is an example "FREEZE"/"THAW" method pair:
124
125 sub My::Object::FREEZE {
126 my ($self, $serialiser) = @_;
127
128 ($self->{type}, $self->{id}, $self->{variant})
129 }
130
131 sub My::Object::THAW {
132 my ($class, $serialiser, $type, $id, $variant) = @_;
133
134 $class-<new (type => $type, id => $id, variant => $variant)
135 }
136
81BUGS 137BUGS
82 The use of overload makes this module much heavier than it should be (on 138 The use of overload makes this module much heavier than it should be (on
83 my system, this module: 4kB RSS, overload: 260kB RSS). 139 my system, this module: 4kB RSS, overload: 260kB RSS).
84 140
85SEE ALSO 141SEE ALSO

Diff Legend

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