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

Comparing Types-Serialiser/README (file contents):
Revision 1.4 by root, Tue Oct 29 13:08:35 2013 UTC vs.
Revision 1.5 by root, Sat Nov 30 18:33:51 2013 UTC

… …
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 81 For historical reasons, the "Types::Serialiser::Boolean" stash is just
82 an alias for "JSON::PP::Boolean". When printed, the classname withh 82 an alias for "JSON::PP::Boolean". When printed, the classname with
83 usually be "JSON::PP::Boolean", but isa tests and stash pointer 83 usually be "JSON::PP::Boolean", but isa tests and stash pointer
84 comparison will normally work correctly (i.e. Types::Serialiser::true 84 comparison will normally work correctly (i.e. Types::Serialiser::true
85 ISA JSON::PP::Boolean, but also ISA Types::Serialiser::Boolean). 85 ISA JSON::PP::Boolean, but also ISA Types::Serialiser::Boolean).
86 86
87A GENERIC OBJECT SERIALIATION PROTOCOL 87A GENERIC OBJECT SERIALIATION PROTOCOL
… …
96 When the encoder encounters an object that it cannot otherwise encode 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 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 98 first attempt to use the special "TO_CBOR" serialisation protocol), it
99 will look up the "FREEZE" method on the object. 99 will look up the "FREEZE" method on the object.
100 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
101 If it exists, it will call it with two arguments: the object to 105 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 106 serialise, and a constant string that indicates the name of the data
103 serialisationformat. For example CBOR::XS uses "CBOR", and JSON and 107 model. For example CBOR::XS uses "CBOR", and the JSON and JSON::XS
104 JSON::XS (or any other JSON serialiser), would use "JSON" as second 108 modules (or any other JSON serialiser), would use "JSON" as second
105 argument. 109 argument.
106 110
107 The "FREEZE" method can then return zero or more values to identify the 111 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 112 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 113 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, 114 format) using the relevant form for Perl objects. In CBOR for example,
111 there is a registered tag number for encoded perl objects. 115 there is a registered tag number for encoded perl objects.
112 116
113 The values that "FREEZE" returns must be serialisable with the 117 The values that "FREEZE" returns must be serialisable with the
114 serialiser that calls it. Therefore, it is recommended to use simple 118 serialiser that calls it. Therefore, it is recommended to use simple
115 types such as strings and numbers, and maybe array references and hashes 119 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 120 (basically, the JSON data model). You can always use a more complex
117 format for a specific serialiser by checking the second argument. 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.
118 131
119 DECODING 132 DECODING
120 When the decoder then encounters such an encoded perl object, it should 133 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 134 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 135 the classname, the constant string to identify the data model/data
123 return values returned by "FREEZE". 136 format, and all the return values returned by "FREEZE".
124 137
125 EXAMPLES 138 EXAMPLES
126 See the "OBJECT SERIALISATION" section in the CBOR::XS manpage for more 139 See the "OBJECT SERIALISATION" section in the CBOR::XS manpage for more
127 details, an example implementation, and code examples. 140 details, an example implementation, and code examples.
128 141
129 Here is an example "FREEZE"/"THAW" method pair: 142 Here is an example "FREEZE"/"THAW" method pair:
130 143
131 sub My::Object::FREEZE { 144 sub My::Object::FREEZE {
132 my ($self, $serialiser) = @_; 145 my ($self, $model) = @_;
133 146
134 ($self->{type}, $self->{id}, $self->{variant}) 147 ($self->{type}, $self->{id}, $self->{variant})
135 } 148 }
136 149
137 sub My::Object::THAW { 150 sub My::Object::THAW {
138 my ($class, $serialiser, $type, $id, $variant) = @_; 151 my ($class, $model, $type, $id, $variant) = @_;
139 152
140 $class-<new (type => $type, id => $id, variant => $variant) 153 $class->new (type => $type, id => $id, variant => $variant)
141 } 154 }
142 155
143BUGS 156BUGS
144 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
145 my system, this module: 4kB RSS, overload: 260kB RSS). 158 my system, this module: 4kB RSS, overload: 260kB RSS).

Diff Legend

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