File Coverage

blib/lib/Scalar/Construct.pm
Criterion Covered Total %
statement 12 12 100.0
branch n/a
condition n/a
subroutine 4 4 100.0
pod n/a
total 16 16 100.0


line stmt bran cond sub pod time code
1             =head1 NAME
2              
3             Scalar::Construct - build custom kinds of scalar
4              
5             =head1 SYNOPSIS
6              
7             use Scalar::Construct qw(constant variable aliasref aliasobj);
8              
9             $ref = constant($value);
10             $ref = variable($value);
11             $ref = aliasref(\$array[0]);
12             $ref = aliasobj($array[0]);
13              
14             =head1 DESCRIPTION
15              
16             This module supplies functions to construct Perl scalar objects.
17             While writable (variable) scalars can easily be constructed using the
18             ordinary facilities of the Perl language, immutable (constant) scalars
19             require a library such as this.
20              
21             =cut
22              
23             package Scalar::Construct;
24              
25 5     5   117839 { use 5.006; }
  5         21  
  5         226  
26 5     5   27 use warnings;
  5         8  
  5         164  
27 5     5   40 use strict;
  5         26  
  5         293  
28              
29             our $VERSION = "0.000";
30              
31 5     5   7592 use parent "Exporter";
  5         1915  
  5         31  
32             our @EXPORT_OK = qw(constant ro variable rw aliasref ar aliasobj ao);
33              
34             require XSLoader;
35             XSLoader::load(__PACKAGE__, $VERSION);
36              
37             *ro = \&constant;
38             *rw = \&variable;
39             *ar = \&aliasref;
40             *ao = \&aliasobj;
41              
42             =head1 FUNCTIONS
43              
44             Each function has two names. There is a longer descriptive name, and
45             a shorter name to spare screen space and the programmer's fingers.
46              
47             =over
48              
49             =item constant(VALUE)
50              
51             =item ro(VALUE)
52              
53             Creates a fresh immutable scalar, with value I, and returns a
54             reference to it.
55              
56             If I is actually a compile-time constant that can be expressed
57             as a literal, such as C<123>, it would appear that a reference to a
58             constant object with that value can be created by a Perl expression
59             such as C<\123>. However, Perl has some bugs relating to compile-time
60             constants that prevent this working as intended. On Perls built for
61             threading (even if threading is not actually used), such a scalar will
62             be copied at surprising times, losing both its object identity and its
63             immutability. The function supplied by this module avoids these problems.
64              
65             =item variable(VALUE)
66              
67             =item rw(VALUE)
68              
69             Creates a fresh writable scalar, initialised to value I, and
70             returns a reference to it.
71              
72             =item aliasref(OBJECT_REF)
73              
74             =item ar(OBJECT_REF)
75              
76             I must be a reference to a scalar. Returns another reference
77             to the same scalar. (This is effectively an identity function, included
78             for completeness.)
79              
80             Due to the Perl bugs discussed above for L, it is unwise
81             to attempt to alias a compile-time constant. Instead use L
82             to create a well-behaved constant scalar.
83              
84             =item aliasobj(OBJECT)
85              
86             =item ao(OBJECT)
87              
88             Returns a reference to I.
89              
90             Due to the Perl bugs discussed above for L, it is unwise
91             to attempt to alias a compile-time constant. Instead use L
92             to create a well-behaved constant scalar.
93              
94             =back
95              
96             =head1 SEE ALSO
97              
98             L
99              
100             =head1 AUTHOR
101              
102             Andrew Main (Zefram)
103              
104             =head1 COPYRIGHT
105              
106             Copyright (C) 2012 Andrew Main (Zefram)
107              
108             =head1 LICENSE
109              
110             This module is free software; you can redistribute it and/or modify it
111             under the same terms as Perl itself.
112              
113             =cut
114              
115             1;