ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Types-Serialiser/Serialiser.pm
Revision: 1.8
Committed: Mon Nov 4 15:12:16 2013 UTC (11 years, 1 month ago) by root
Branch: MAIN
Changes since 1.7: +10 -11 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 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 root 1.8 with usually be C<JSON::PP::Boolean>, but isa tests and stash pointer
163 root 1.4 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 root 1.8 If it exists, it will call it with two arguments: the object to serialise,
183     and a constant string that indicates the name of the data model or data
184     format. For example L<CBOR::XS> uses C<CBOR>, and L<JSON> and L<JSON::XS>
185     (or any other JSON serialiser), would use C<JSON> as second argument.
186 root 1.3
187     The C<FREEZE> method can then return zero or more values to identify the
188     object instance. The serialiser is then supposed to encode the class name
189     and all of these return values (which must be encodable in the format)
190     using the relevant form for perl objects. In CBOR for example, there is a
191     registered tag number for encoded perl objects.
192    
193 root 1.5 The values that C<FREEZE> returns must be serialisable with the serialiser
194     that calls it. Therefore, it is recommended to use simple types such as
195     strings and numbers, and maybe array references and hashes (basically, the
196     JSON data model). You can always use a more complex format for a specific
197 root 1.8 data model by checking the second argument.
198 root 1.5
199 root 1.3 =head2 DECODING
200    
201     When the decoder then encounters such an encoded perl object, it should
202     look up the C<THAW> method on the stored classname, and invoke it with the
203 root 1.8 classname, the constant string to identify the data model/data format, and
204     all the return values returned by C<FREEZE>.
205 root 1.3
206     =head2 EXAMPLES
207    
208     See the C<OBJECT SERIALISATION> section in the L<CBOR::XS> manpage for
209     more details, an example implementation, and code examples.
210    
211     Here is an example C<FREEZE>/C<THAW> method pair:
212    
213     sub My::Object::FREEZE {
214 root 1.8 my ($self, $model) = @_;
215 root 1.3
216     ($self->{type}, $self->{id}, $self->{variant})
217     }
218    
219     sub My::Object::THAW {
220 root 1.8 my ($class, $model, $type, $id, $variant) = @_;
221 root 1.3
222 root 1.7 $class->new (type => $type, id => $id, variant => $variant)
223 root 1.3 }
224    
225 root 1.1 =head1 BUGS
226    
227     The use of L<overload> makes this module much heavier than it should be
228     (on my system, this module: 4kB RSS, overload: 260kB RSS).
229    
230     =head1 SEE ALSO
231    
232     Currently, L<JSON::XS> and L<CBOR::XS> use these types.
233    
234     =head1 AUTHOR
235    
236     Marc Lehmann <schmorp@schmorp.de>
237     http://home.schmorp.de/
238    
239     =cut
240    
241     1
242