ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Types-Serialiser/Serialiser.pm
Revision: 1.3
Committed: Sun Oct 27 22:46:21 2013 UTC (11 years, 1 month ago) by root
Branch: MAIN
Changes since 1.2: +54 -0 lines
Log Message:
*** empty log message ***

File Contents

# User Rev Content
1 root 1.1 =head1 NAME
2    
3     Types::Serialiser - simple data types for common serialisation formats
4    
5     =encoding utf-8
6    
7     =head1 SYNOPSIS
8    
9     =head1 DESCRIPTION
10    
11     This module provides some extra datatypes that are used by common
12     serialisation formats such as JSON or CBOR. The idea is to have a
13     repository of simple/small constants and containers that can be shared by
14     different implementations so they become interoperable between each other.
15    
16     =cut
17    
18     package Types::Serialiser;
19    
20     our $VERSION = 0.01;
21    
22     =head1 SIMPLE SCALAR CONSTANTS
23    
24     Simple scalar constants are values that are overloaded to act like simple
25     Perl values, but have (class) type to differentiate them from normal Perl
26     scalars. This is necessary because these have different representations in
27     the serialisation formats.
28    
29     =head2 BOOLEANS (Types::Serialiser::Boolean class)
30    
31     This type has only two instances, true and false. A natural representation
32     for these in Perl is C<1> and C<0>, but serialisation formats need to be
33     able to differentiate between them and mere numbers.
34    
35     =over 4
36    
37     =item $Types::Serialiser::true, Types::Serialiser::true
38    
39     This value represents the "true" value. In most contexts is acts like
40     the number C<1>. It is up to you whether you use the variable form
41     (C<$Types::Serialiser::true>) or the constant form (C<Types::Serialiser::true>).
42    
43     The constant is represented as a reference to a scalar containing C<1> -
44     implementations are allowed to directly test for this.
45    
46     =item $Types::Serialiser::false, Types::Serialiser::false
47    
48     This value represents the "false" value. In most contexts is acts like
49     the number C<0>. It is up to you whether you use the variable form
50     (C<$Types::Serialiser::false>) or the constant form (C<Types::Serialiser::false>).
51    
52     The constant is represented as a reference to a scalar containing C<0> -
53     implementations are allowed to directly test for this.
54    
55     =item $is_bool = Types::Serialiser::is_bool $value
56    
57     Returns true iff the C<$value> is either C<$Types::Serialiser::true> or
58     C<$Types::Serialiser::false>.
59    
60     For example, you could differentiate between a perl true value and a
61     C<Types::Serialiser::true> by using this:
62    
63     $value && Types::Serialiser::is_bool $value
64    
65     =item $is_true = Types::Serialiser::is_true $value
66    
67     Returns true iff C<$value> is C<$Types::Serialiser::true>.
68    
69     =item $is_false = Types::Serialiser::is_false $value
70    
71     Returns false iff C<$value> is C<$Types::Serialiser::false>.
72    
73     =back
74    
75     =head2 ERROR (Types::Serialiser::Error class)
76    
77     This class has only a single instance, C<error>. It is used to signal
78     an encoding or decoding error. In CBOR for example, and object that
79     couldn't be encoded will be represented by a CBOR undefined value, which
80     is represented by the error value in Perl.
81    
82     =over 4
83    
84     =item $Types::Serialiser::error, Types::Serialiser::error
85    
86     This value represents the "error" value. Accessing values of this type
87     will throw an exception.
88    
89     The constant is represented as a reference to a scalar containing C<undef>
90     - implementations are allowed to directly test for this.
91    
92     =item $is_error = Types::Serialiser::is_error $value
93    
94     Returns false iff C<$value> is C<$Types::Serialiser::error>.
95    
96     =back
97    
98     =cut
99    
100     our $true = do { bless \(my $dummy = 1), Types::Serialiser::Boolean:: };
101     our $false = do { bless \(my $dummy = 0), Types::Serialiser::Boolean:: };
102     our $error = do { bless \(my $dummy ), Types::Serialiser::Error:: };
103    
104     sub true () { $true }
105     sub false () { $false }
106     sub error () { $error }
107    
108     sub is_bool ($) { UNIVERSAL::isa $_[0], Types::Serialiser::Boolean:: }
109     sub is_true ($) { $_[0] && UNIVERSAL::isa $_[0], Types::Serialiser::Boolean:: }
110     sub is_false ($) { !$_[0] && UNIVERSAL::isa $_[0], Types::Serialiser::Boolean:: }
111     sub is_error ($) { UNIVERSAL::isa $_[0], Types::Serialiser::Error:: }
112    
113     package Types::Serialiser::Boolean;
114    
115     use overload
116     "0+" => sub { ${$_[0]} },
117     "++" => sub { $_[0] = ${$_[0]} + 1 },
118     "--" => sub { $_[0] = ${$_[0]} - 1 },
119     fallback => 1;
120    
121     package Types::Serialiser::Error;
122    
123     sub error {
124     require Carp;
125 root 1.2 Carp::croak ("caught attempt to use the Types::Serialiser::error value");
126 root 1.1 };
127    
128     use overload
129     "0+" => \&error,
130     "++" => \&error,
131     "--" => \&error,
132     fallback => 1;
133    
134 root 1.2 =head1 NOTES FOR XS USERS
135    
136     The recommended way to detect whether a scalar is one of these objects
137     is to check whether the stash is the C<Types::Serialiser::Boolean> or
138     C<Types::Serialiser::Error> stash, and then follow the scalar reference to
139     see if it's C<1> (true), C<0> (false) or C<undef> (error).
140    
141     While it is possible to use an isa test, directly comparing stash pointers
142     is faster and guaranteed to work.
143    
144 root 1.3 =head1 A GENERIC OBJECT SERIALIATION PROTOCOL
145    
146     This section explains the object serialisation protocol used by
147     L<CBOR::XS>. It is meant to be generic enough to support any kind of
148     generic object serialiser.
149    
150     This protocol is called "the Types::Serialiser object serialisation
151     protocol".
152    
153     =head2 ENCODING
154    
155     When the encoder encounters an object that it cannot otherwise encode (for
156     example, L<CBOR::XS> can encode a few special types itself, and will first
157     attempt to use the special C<TO_CBOR> serialisation protocol), it will
158     look up the C<FREEZE> method on the object.
159    
160     If it exists, it will call it with two arguments: the object to
161     serialise, and a constant string that indicates the name of the
162     serialisationformat. For example L<CBOR::XS> uses C<CBOR>, and L<JSON> and
163     L<JSON::XS> (or any other JSON serialiser), would use C<JSON> as second
164     argument.
165    
166     The C<FREEZE> method can then return zero or more values to identify the
167     object instance. The serialiser is then supposed to encode the class name
168     and all of these return values (which must be encodable in the format)
169     using the relevant form for perl objects. In CBOR for example, there is a
170     registered tag number for encoded perl objects.
171    
172     =head2 DECODING
173    
174     When the decoder then encounters such an encoded perl object, it should
175     look up the C<THAW> method on the stored classname, and invoke it with the
176     classname, the constant string to identify the format, and all the return
177     values returned by C<FREEZE>.
178    
179     =head2 EXAMPLES
180    
181     See the C<OBJECT SERIALISATION> section in the L<CBOR::XS> manpage for
182     more details, an example implementation, and code examples.
183    
184     Here is an example C<FREEZE>/C<THAW> method pair:
185    
186     sub My::Object::FREEZE {
187     my ($self, $serialiser) = @_;
188    
189     ($self->{type}, $self->{id}, $self->{variant})
190     }
191    
192     sub My::Object::THAW {
193     my ($class, $serialiser, $type, $id, $variant) = @_;
194    
195     $class-<new (type => $type, id => $id, variant => $variant)
196     }
197    
198 root 1.1 =head1 BUGS
199    
200     The use of L<overload> makes this module much heavier than it should be
201     (on my system, this module: 4kB RSS, overload: 260kB RSS).
202    
203     =head1 SEE ALSO
204    
205     Currently, L<JSON::XS> and L<CBOR::XS> use these types.
206    
207     =head1 AUTHOR
208    
209     Marc Lehmann <schmorp@schmorp.de>
210     http://home.schmorp.de/
211    
212     =cut
213    
214     1
215