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.1 by root, Sun Oct 27 19:49:33 2013 UTC vs.
Revision 1.5 by root, Mon Oct 28 21:52:22 2013 UTC

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

Diff Legend

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