ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Types-Serialiser/Serialiser.pm
Revision: 1.2
Committed: Sun Oct 27 20:01:08 2013 UTC (11 years, 1 month ago) by root
Branch: MAIN
CVS Tags: rel-0_01
Changes since 1.1: +11 -3 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     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