ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Types-Serialiser/Serialiser.pm
Revision: 1.6
Committed: Tue Oct 29 13:08:35 2013 UTC (11 years, 1 month ago) by root
Branch: MAIN
CVS Tags: rel-0_03
Changes since 1.5: +16 -11 lines
Log Message:
0.03

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 root 1.4 use common::sense; # required to suppress annoying warnings
21    
22 root 1.6 our $VERSION = 0.03;
23 root 1.1
24     =head1 SIMPLE SCALAR CONSTANTS
25    
26     Simple scalar constants are values that are overloaded to act like simple
27     Perl values, but have (class) type to differentiate them from normal Perl
28     scalars. This is necessary because these have different representations in
29     the serialisation formats.
30    
31     =head2 BOOLEANS (Types::Serialiser::Boolean class)
32    
33     This type has only two instances, true and false. A natural representation
34     for these in Perl is C<1> and C<0>, but serialisation formats need to be
35     able to differentiate between them and mere numbers.
36    
37     =over 4
38    
39     =item $Types::Serialiser::true, Types::Serialiser::true
40    
41     This value represents the "true" value. In most contexts is acts like
42     the number C<1>. It is up to you whether you use the variable form
43     (C<$Types::Serialiser::true>) or the constant form (C<Types::Serialiser::true>).
44    
45     The constant is represented as a reference to a scalar containing C<1> -
46     implementations are allowed to directly test for this.
47    
48     =item $Types::Serialiser::false, Types::Serialiser::false
49    
50     This value represents the "false" value. In most contexts is acts like
51     the number C<0>. It is up to you whether you use the variable form
52     (C<$Types::Serialiser::false>) or the constant form (C<Types::Serialiser::false>).
53    
54     The constant is represented as a reference to a scalar containing C<0> -
55     implementations are allowed to directly test for this.
56    
57     =item $is_bool = Types::Serialiser::is_bool $value
58    
59     Returns true iff the C<$value> is either C<$Types::Serialiser::true> or
60     C<$Types::Serialiser::false>.
61    
62     For example, you could differentiate between a perl true value and a
63     C<Types::Serialiser::true> by using this:
64    
65     $value && Types::Serialiser::is_bool $value
66    
67     =item $is_true = Types::Serialiser::is_true $value
68    
69     Returns true iff C<$value> is C<$Types::Serialiser::true>.
70    
71     =item $is_false = Types::Serialiser::is_false $value
72    
73     Returns false iff C<$value> is C<$Types::Serialiser::false>.
74    
75     =back
76    
77     =head2 ERROR (Types::Serialiser::Error class)
78    
79     This class has only a single instance, C<error>. It is used to signal
80     an encoding or decoding error. In CBOR for example, and object that
81     couldn't be encoded will be represented by a CBOR undefined value, which
82     is represented by the error value in Perl.
83    
84     =over 4
85    
86     =item $Types::Serialiser::error, Types::Serialiser::error
87    
88     This value represents the "error" value. Accessing values of this type
89     will throw an exception.
90    
91     The constant is represented as a reference to a scalar containing C<undef>
92     - implementations are allowed to directly test for this.
93    
94     =item $is_error = Types::Serialiser::is_error $value
95    
96     Returns false iff C<$value> is C<$Types::Serialiser::error>.
97    
98     =back
99    
100     =cut
101    
102 root 1.4 BEGIN {
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 root 1.6
107 root 1.4 *Types::Serialiser::Boolean:: = *JSON::PP::Boolean::;
108     }
109    
110 root 1.6 {
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    
124 root 1.1 our $true = do { bless \(my $dummy = 1), Types::Serialiser::Boolean:: };
125     our $false = do { bless \(my $dummy = 0), Types::Serialiser::Boolean:: };
126     our $error = do { bless \(my $dummy ), Types::Serialiser::Error:: };
127    
128     sub true () { $true }
129     sub false () { $false }
130     sub error () { $error }
131    
132     sub is_bool ($) { UNIVERSAL::isa $_[0], Types::Serialiser::Boolean:: }
133     sub is_true ($) { $_[0] && UNIVERSAL::isa $_[0], Types::Serialiser::Boolean:: }
134     sub is_false ($) { !$_[0] && UNIVERSAL::isa $_[0], Types::Serialiser::Boolean:: }
135     sub is_error ($) { UNIVERSAL::isa $_[0], Types::Serialiser::Error:: }
136    
137     package Types::Serialiser::Error;
138    
139     sub error {
140     require Carp;
141 root 1.2 Carp::croak ("caught attempt to use the Types::Serialiser::error value");
142 root 1.1 };
143    
144     use overload
145     "0+" => \&error,
146     "++" => \&error,
147     "--" => \&error,
148     fallback => 1;
149    
150 root 1.2 =head1 NOTES FOR XS USERS
151    
152     The recommended way to detect whether a scalar is one of these objects
153     is to check whether the stash is the C<Types::Serialiser::Boolean> or
154     C<Types::Serialiser::Error> stash, and then follow the scalar reference to
155     see if it's C<1> (true), C<0> (false) or C<undef> (error).
156    
157     While it is possible to use an isa test, directly comparing stash pointers
158     is faster and guaranteed to work.
159    
160 root 1.4 For historical reasons, the C<Types::Serialiser::Boolean> stash is
161     just an alias for C<JSON::PP::Boolean>. When printed, the classname
162     withh usually be C<JSON::PP::Boolean>, but isa tests and stash pointer
163     comparison will normally work correctly (i.e. Types::Serialiser::true ISA
164     JSON::PP::Boolean, but also ISA Types::Serialiser::Boolean).
165    
166 root 1.3 =head1 A GENERIC OBJECT SERIALIATION PROTOCOL
167    
168     This section explains the object serialisation protocol used by
169     L<CBOR::XS>. It is meant to be generic enough to support any kind of
170     generic object serialiser.
171    
172     This protocol is called "the Types::Serialiser object serialisation
173     protocol".
174    
175     =head2 ENCODING
176    
177     When the encoder encounters an object that it cannot otherwise encode (for
178     example, L<CBOR::XS> can encode a few special types itself, and will first
179     attempt to use the special C<TO_CBOR> serialisation protocol), it will
180     look up the C<FREEZE> method on the object.
181    
182     If it exists, it will call it with two arguments: the object to
183     serialise, and a constant string that indicates the name of the
184     serialisationformat. For example L<CBOR::XS> uses C<CBOR>, and L<JSON> and
185     L<JSON::XS> (or any other JSON serialiser), would use C<JSON> as second
186     argument.
187    
188     The C<FREEZE> method can then return zero or more values to identify the
189     object instance. The serialiser is then supposed to encode the class name
190     and all of these return values (which must be encodable in the format)
191     using the relevant form for perl objects. In CBOR for example, there is a
192     registered tag number for encoded perl objects.
193    
194 root 1.5 The values that C<FREEZE> returns must be serialisable with the serialiser
195     that calls it. Therefore, it is recommended to use simple types such as
196     strings and numbers, and maybe array references and hashes (basically, the
197     JSON data model). You can always use a more complex format for a specific
198     serialiser by checking the second argument.
199    
200 root 1.3 =head2 DECODING
201    
202     When the decoder then encounters such an encoded perl object, it should
203     look up the C<THAW> method on the stored classname, and invoke it with the
204     classname, the constant string to identify the format, and all the return
205     values returned by C<FREEZE>.
206    
207     =head2 EXAMPLES
208    
209     See the C<OBJECT SERIALISATION> section in the L<CBOR::XS> manpage for
210     more details, an example implementation, and code examples.
211    
212     Here is an example C<FREEZE>/C<THAW> method pair:
213    
214     sub My::Object::FREEZE {
215     my ($self, $serialiser) = @_;
216    
217     ($self->{type}, $self->{id}, $self->{variant})
218     }
219    
220     sub My::Object::THAW {
221     my ($class, $serialiser, $type, $id, $variant) = @_;
222    
223     $class-<new (type => $type, id => $id, variant => $variant)
224     }
225    
226 root 1.1 =head1 BUGS
227    
228     The use of L<overload> makes this module much heavier than it should be
229     (on my system, this module: 4kB RSS, overload: 260kB RSS).
230    
231     =head1 SEE ALSO
232    
233     Currently, L<JSON::XS> and L<CBOR::XS> use these types.
234    
235     =head1 AUTHOR
236    
237     Marc Lehmann <schmorp@schmorp.de>
238     http://home.schmorp.de/
239    
240     =cut
241    
242     1
243