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;

our $VERSION = 0.01;

=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

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::Boolean;

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

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.

=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
serialisationformat. 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.

=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 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, $serialiser) = @_;

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

   sub My::Object::THAW {
      my ($class, $serialiser, $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.3
Committed:	Sun Oct 27 22:46:21 2013 UTC (10 years, 8 months ago) by root
Branch:	MAIN
Changes since 1.2:	+54 -0 lines
Log Message:	* empty log message *
#	Content
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	Carp::croak ("caught attempt to use the Types::Serialiser::error value");
126	};
127
128	use overload
129	"0+" => \&error,
130	"++" => \&error,
131	"--" => \&error,
132	fallback => 1;
133
134	=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	=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	=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