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.3 by root, Sun Oct 27 22:46:21 2013 UTC vs.
Revision 1.8 by root, Mon Nov 4 15:12:16 2013 UTC

… …
15 15
16=cut 16=cut
17 17
18package Types::Serialiser; 18package Types::Serialiser;
19 19
20use common::sense; # required to suppress annoying warnings
21
20our $VERSION = 0.01; 22our $VERSION = 0.03;
21 23
22=head1 SIMPLE SCALAR CONSTANTS 24=head1 SIMPLE SCALAR CONSTANTS
23 25
24Simple scalar constants are values that are overloaded to act like simple 26Simple scalar constants are values that are overloaded to act like simple
25Perl values, but have (class) type to differentiate them from normal Perl 27Perl values, but have (class) type to differentiate them from normal Perl
… …
95 97
96=back 98=back
97 99
98=cut 100=cut
99 101
102BEGIN {
103 # for historical reasons, and to avoid extra dependencies in JSON::PP,
104 # we alias *Types::Serialiser::Boolean with JSON::PP::Boolean.
105 package JSON::PP::Boolean;
106
107 *Types::Serialiser::Boolean:: = *JSON::PP::Boolean::;
108}
109
110{
111 # this must done before blessing to work around bugs
112 # in perl < 5.18 (it seems to be fixed in 5.18).
113 package Types::Serialiser::BooleanBase;
114
115 use overload
116 "0+" => sub { ${$_[0]} },
117 "++" => sub { $_[0] = ${$_[0]} + 1 },
118 "--" => sub { $_[0] = ${$_[0]} - 1 },
119 fallback => 1;
120
121 @Types::Serialiser::Boolean::ISA = Types::Serialiser::BooleanBase::;
122}
123
100our $true = do { bless \(my $dummy = 1), Types::Serialiser::Boolean:: }; 124our $true = do { bless \(my $dummy = 1), Types::Serialiser::Boolean:: };
101our $false = do { bless \(my $dummy = 0), Types::Serialiser::Boolean:: }; 125our $false = do { bless \(my $dummy = 0), Types::Serialiser::Boolean:: };
102our $error = do { bless \(my $dummy ), Types::Serialiser::Error:: }; 126our $error = do { bless \(my $dummy ), Types::Serialiser::Error:: };
103 127
104sub true () { $true } 128sub true () { $true }
… …
107 131
108sub is_bool ($) { UNIVERSAL::isa $_[0], Types::Serialiser::Boolean:: } 132sub is_bool ($) { UNIVERSAL::isa $_[0], Types::Serialiser::Boolean:: }
109sub is_true ($) { $_[0] && UNIVERSAL::isa $_[0], Types::Serialiser::Boolean:: } 133sub is_true ($) { $_[0] && UNIVERSAL::isa $_[0], Types::Serialiser::Boolean:: }
110sub is_false ($) { !$_[0] && UNIVERSAL::isa $_[0], Types::Serialiser::Boolean:: } 134sub is_false ($) { !$_[0] && UNIVERSAL::isa $_[0], Types::Serialiser::Boolean:: }
111sub is_error ($) { UNIVERSAL::isa $_[0], Types::Serialiser::Error:: } 135sub is_error ($) { UNIVERSAL::isa $_[0], Types::Serialiser::Error:: }
112
113package Types::Serialiser::Boolean;
114
115use overload
116 "0+" => sub { ${$_[0]} },
117 "++" => sub { $_[0] = ${$_[0]} + 1 },
118 "--" => sub { $_[0] = ${$_[0]} - 1 },
119 fallback => 1;
120 136
121package Types::Serialiser::Error; 137package Types::Serialiser::Error;
122 138
123sub error { 139sub error {
124 require Carp; 140 require Carp;
… …
139see if it's C<1> (true), C<0> (false) or C<undef> (error). 155see if it's C<1> (true), C<0> (false) or C<undef> (error).
140 156
141While 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
142is faster and guaranteed to work. 158is faster and guaranteed to work.
143 159
160For historical reasons, the C<Types::Serialiser::Boolean> stash is
161just an alias for C<JSON::PP::Boolean>. When printed, the classname
162with usually be C<JSON::PP::Boolean>, but isa tests and stash pointer
163comparison will normally work correctly (i.e. Types::Serialiser::true ISA
164JSON::PP::Boolean, but also ISA Types::Serialiser::Boolean).
165
144=head1 A GENERIC OBJECT SERIALIATION PROTOCOL 166=head1 A GENERIC OBJECT SERIALIATION PROTOCOL
145 167
146This section explains the object serialisation protocol used by 168This section explains the object serialisation protocol used by
147L<CBOR::XS>. It is meant to be generic enough to support any kind of 169L<CBOR::XS>. It is meant to be generic enough to support any kind of
148generic object serialiser. 170generic object serialiser.
… …
155When the encoder encounters an object that it cannot otherwise encode (for 177When the encoder encounters an object that it cannot otherwise encode (for
156example, 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
157attempt to use the special C<TO_CBOR> serialisation protocol), it will 179attempt to use the special C<TO_CBOR> serialisation protocol), it will
158look up the C<FREEZE> method on the object. 180look up the C<FREEZE> method on the object.
159 181
160If 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,
161serialise, and a constant string that indicates the name of the 183and a constant string that indicates the name of the data model or data
162serialisationformat. 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>
163L<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.
164argument.
165 186
166The 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
167object instance. The serialiser is then supposed to encode the class name 188object instance. The serialiser is then supposed to encode the class name
168and 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)
169using 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
170registered tag number for encoded perl objects. 191registered tag number for encoded perl objects.
171 192
193The values that C<FREEZE> returns must be serialisable with the serialiser
194that calls it. Therefore, it is recommended to use simple types such as
195strings and numbers, and maybe array references and hashes (basically, the
196JSON data model). You can always use a more complex format for a specific
197data model by checking the second argument.
198
172=head2 DECODING 199=head2 DECODING
173 200
174When the decoder then encounters such an encoded perl object, it should 201When the decoder then encounters such an encoded perl object, it should
175look 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
176classname, the constant string to identify the format, and all the return 203classname, the constant string to identify the data model/data format, and
177values returned by C<FREEZE>. 204all the return values returned by C<FREEZE>.
178 205
179=head2 EXAMPLES 206=head2 EXAMPLES
180 207
181See 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
182more details, an example implementation, and code examples. 209more details, an example implementation, and code examples.
183 210
184Here is an example C<FREEZE>/C<THAW> method pair: 211Here is an example C<FREEZE>/C<THAW> method pair:
185 212
186 sub My::Object::FREEZE { 213 sub My::Object::FREEZE {
187 my ($self, $serialiser) = @_; 214 my ($self, $model) = @_;
188 215
189 ($self->{type}, $self->{id}, $self->{variant}) 216 ($self->{type}, $self->{id}, $self->{variant})
190 } 217 }
191 218
192 sub My::Object::THAW { 219 sub My::Object::THAW {
193 my ($class, $serialiser, $type, $id, $variant) = @_; 220 my ($class, $model, $type, $id, $variant) = @_;
194 221
195 $class-<new (type => $type, id => $id, variant => $variant) 222 $class->new (type => $type, id => $id, variant => $variant)
196 } 223 }
197 224
198=head1 BUGS 225=head1 BUGS
199 226
200The use of L<overload> makes this module much heavier than it should be 227The use of L<overload> makes this module much heavier than it should be

Diff Legend

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