Types-Serialiser/Serialiser.pm

=head1 NAME

Types::Serialiser - simple data types for common serialisation formats

=encoding utf-8

=head1 SYNOPSIS

=head1 DESCRIPTION

This module provides some extra datatypes that are used by common
serialisation formats such as JSON or CBOR. The idea is to have a
repository of simple/small constants and containers that can be shared by
different implementations so they become interoperable between each other.

=cut

package Types::Serialiser;

use common::sense; # required to suppress annoying warnings

our $VERSION = 0.03;

=head1 SIMPLE SCALAR CONSTANTS

Simple scalar constants are values that are overloaded to act like simple
Perl values, but have (class) type to differentiate them from normal Perl
scalars. This is necessary because these have different representations in
the serialisation formats.

=head2 BOOLEANS (Types::Serialiser::Boolean class)

This type has only two instances, true and false. A natural representation
for these in Perl is C<1> and C<0>, but serialisation formats need to be
able to differentiate between them and mere numbers.

=over 4

=item $Types::Serialiser::true, Types::Serialiser::true

This value represents the "true" value. In most contexts is acts like
the number C<1>. It is up to you whether you use the variable form
(C<$Types::Serialiser::true>) or the constant form (C<Types::Serialiser::true>).

The constant is represented as a reference to a scalar containing C<1> -
implementations are allowed to directly test for this.

=item $Types::Serialiser::false, Types::Serialiser::false

This value represents the "false" value. In most contexts is acts like
the number C<0>. It is up to you whether you use the variable form
(C<$Types::Serialiser::false>) or the constant form (C<Types::Serialiser::false>).

The constant is represented as a reference to a scalar containing C<0> -
implementations are allowed to directly test for this.

=item $is_bool = Types::Serialiser::is_bool $value

Returns true iff the C<$value> is either C<$Types::Serialiser::true> or
C<$Types::Serialiser::false>.

For example, you could differentiate between a perl true value and a
C<Types::Serialiser::true> by using this:

   $value && Types::Serialiser::is_bool $value

=item $is_true = Types::Serialiser::is_true $value

Returns true iff C<$value> is C<$Types::Serialiser::true>.

=item $is_false = Types::Serialiser::is_false $value

Returns false iff C<$value> is C<$Types::Serialiser::false>.

=back

=head2 ERROR (Types::Serialiser::Error class)

This class has only a single instance, C<error>. It is used to signal
an encoding or decoding error. In CBOR for example, and object that
couldn't be encoded will be represented by a CBOR undefined value, which
is represented by the error value in Perl.

=over 4

=item $Types::Serialiser::error, Types::Serialiser::error

This value represents the "error" value. Accessing values of this type
will throw an exception.

The constant is represented as a reference to a scalar containing C<undef>
- implementations are allowed to directly test for this.

=item $is_error = Types::Serialiser::is_error $value

Returns false iff C<$value> is C<$Types::Serialiser::error>.

=back

=cut

BEGIN {
   # for historical reasons, and to avoid extra dependencies in JSON::PP,
   # we alias *Types::Serialiser::Boolean with JSON::PP::Boolean.
   package JSON::PP::Boolean;

   *Types::Serialiser::Boolean:: = *JSON::PP::Boolean::;
}

{
   # this must done before blessing to work around bugs
   # in perl < 5.18 (it seems to be fixed in 5.18).
   package Types::Serialiser::BooleanBase;

   use overload
      "0+"     => sub { ${$_[0]} },
      "++"     => sub { $_[0] = ${$_[0]} + 1 },
      "--"     => sub { $_[0] = ${$_[0]} - 1 },
      fallback => 1;

   @Types::Serialiser::Boolean::ISA = Types::Serialiser::BooleanBase::;
}

our $true  = do { bless \(my $dummy = 1), Types::Serialiser::Boolean:: };
our $false = do { bless \(my $dummy = 0), Types::Serialiser::Boolean:: };
our $error = do { bless \(my $dummy    ), Types::Serialiser::Error::   };

sub true  () { $true  }
sub false () { $false }
sub error () { $error }

sub is_bool  ($) {           UNIVERSAL::isa $_[0], Types::Serialiser::Boolean:: }
sub is_true  ($) {  $_[0] && UNIVERSAL::isa $_[0], Types::Serialiser::Boolean:: }
sub is_false ($) { !$_[0] && UNIVERSAL::isa $_[0], Types::Serialiser::Boolean:: }
sub is_error ($) {           UNIVERSAL::isa $_[0], Types::Serialiser::Error::   }

package Types::Serialiser::Error;

sub error {
   require Carp;
   Carp::croak ("caught attempt to use the Types::Serialiser::error value");
};

use overload
   "0+"     => \&error,
   "++"     => \&error,
   "--"     => \&error,
   fallback => 1;

=head1 NOTES FOR XS USERS

The recommended way to detect whether a scalar is one of these objects
is to check whether the stash is the C<Types::Serialiser::Boolean> or
C<Types::Serialiser::Error> stash, and then follow the scalar reference to
see if it's C<1> (true), C<0> (false) or C<undef> (error).

While it is possible to use an isa test, directly comparing stash pointers
is faster and guaranteed to work.

For historical reasons, the C<Types::Serialiser::Boolean> stash is
just an alias for C<JSON::PP::Boolean>. When printed, the classname
with usually be C<JSON::PP::Boolean>, but isa tests and stash pointer
comparison will normally work correctly (i.e. Types::Serialiser::true ISA
JSON::PP::Boolean, but also ISA Types::Serialiser::Boolean).

=head1 A GENERIC OBJECT SERIALIATION PROTOCOL

This section explains the object serialisation protocol used by
L<CBOR::XS>. It is meant to be generic enough to support any kind of
generic object serialiser.

This protocol is called "the Types::Serialiser object serialisation
protocol".

=head2 ENCODING

When the encoder encounters an object that it cannot otherwise encode (for
example, L<CBOR::XS> can encode a few special types itself, and will first
attempt to use the special C<TO_CBOR> serialisation protocol), it will
look up the C<FREEZE> method on the object.

If it exists, it will call it with two arguments: the object to serialise,
and a constant string that indicates the name of the data model or data
format. For example L<CBOR::XS> uses C<CBOR>, and L<JSON> and L<JSON::XS>
(or any other JSON serialiser), would use C<JSON> as second argument.

The C<FREEZE> method can then return zero or more values to identify the
object instance. The serialiser is then supposed to encode the class name
and all of these return values (which must be encodable in the format)
using the relevant form for perl objects. In CBOR for example, there is a
registered tag number for encoded perl objects.

The values that C<FREEZE> returns must be serialisable with the serialiser
that calls it. Therefore, it is recommended to use simple types such as
strings and numbers, and maybe array references and hashes (basically, the
JSON data model). You can always use a more complex format for a specific
data model by checking the second argument.

=head2 DECODING

When the decoder then encounters such an encoded perl object, it should
look up the C<THAW> method on the stored classname, and invoke it with the
classname, the constant string to identify the data model/data format, and
all the return values returned by C<FREEZE>.

=head2 EXAMPLES

See the C<OBJECT SERIALISATION> section in the L<CBOR::XS> manpage for
more details, an example implementation, and code examples.

Here is an example C<FREEZE>/C<THAW> method pair:

   sub My::Object::FREEZE {
      my ($self, $model) = @_;

      ($self->{type}, $self->{id}, $self->{variant})
   }

   sub My::Object::THAW {
      my ($class, $model, $type, $id, $variant) = @_;

      $class->new (type => $type, id => $id, variant => $variant)
   }

=head1 BUGS

The use of L<overload> makes this module much heavier than it should be
(on my system, this module: 4kB RSS, overload: 260kB RSS).

=head1 SEE ALSO

Currently, L<JSON::XS> and L<CBOR::XS> use these types.

=head1 AUTHOR

 Marc Lehmann <schmorp@schmorp.de>
 http://home.schmorp.de/

=cut

1

Revision:	1.8
Committed:	Mon Nov 4 15:12:16 2013 UTC (10 years, 7 months ago) by root
Branch:	MAIN
Changes since 1.7:	+10 -11 lines
Log Message:	* empty log message *
#	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