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.4 by root, Tue Oct 29 13:08:35 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 The values that "FREEZE" returns must be serialisable with the
114 serialiser that calls it. Therefore, it is recommended to use simple
115 types such as strings and numbers, and maybe array references and hashes
116 (basically, the JSON data model). You can always use a more complex
117 format for a specific serialiser by checking the second argument.
118
119 DECODING
120 When the decoder then encounters such an encoded perl object, it should
121 look up the "THAW" method on the stored classname, and invoke it with
122 the classname, the constant string to identify the format, and all the
123 return values returned by "FREEZE".
124
125 EXAMPLES
126 See the "OBJECT SERIALISATION" section in the CBOR::XS manpage for more
127 details, an example implementation, and code examples.
128
129 Here is an example "FREEZE"/"THAW" method pair:
130
131 sub My::Object::FREEZE {
132 my ($self, $serialiser) = @_;
133
134 ($self->{type}, $self->{id}, $self->{variant})
135 }
136
137 sub My::Object::THAW {
138 my ($class, $serialiser, $type, $id, $variant) = @_;
139
140 $class-<new (type => $type, id => $id, variant => $variant)
141 }
142
81BUGS 143BUGS
82 The use of overload makes this module much heavier than it should be (on 144 The use of overload makes this module much heavier than it should be (on
83 my system, this module: 4kB RSS, overload: 260kB RSS). 145 my system, this module: 4kB RSS, overload: 260kB RSS).
84 146
85SEE ALSO 147SEE ALSO

Diff Legend

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