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 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.2
Committed:	Sun Oct 27 20:01:08 2013 UTC (10 years, 8 months ago) by root
Branch:	MAIN
CVS Tags:	rel-0_01
Changes since 1.1:	+11 -3 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			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.1	=head1 BUGS
145
146			The use of L<overload> makes this module much heavier than it should be
147			(on my system, this module: 4kB RSS, overload: 260kB RSS).
148
149			=head1 SEE ALSO
150
151			Currently, L<JSON::XS> and L<CBOR::XS> use these types.
152
153			=head1 AUTHOR
154
155			Marc Lehmann <schmorp@schmorp.de>
156			http://home.schmorp.de/
157
158			=cut
159
160			1
161