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.5 by root, Sat Nov 30 18:33:51 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 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
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 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
81BUGS 156BUGS
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
85SEE ALSO 160SEE ALSO

Diff Legend

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