1Readonly(3)           User Contributed Perl Documentation          Readonly(3)
2
3
4
5- -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1
6

NAME

8       Readonly - Facility for creating read-only scalars, arrays, hashes.
9

VERSION

11       This documentation describes version 1.03 of Readonly.pm, April 20,
12       2004.
13

SYNOPSIS

15        use Readonly;
16
17        # Read-only scalar
18        Readonly::Scalar     $sca => $initial_value;
19        Readonly::Scalar  my $sca => $initial_value;
20
21        # Read-only array
22        Readonly::Array      @arr => @values;
23        Readonly::Array   my @arr => @values;
24
25        # Read-only hash
26        Readonly::Hash       %has => (key => value, key => value, ...);
27        Readonly::Hash    my %has => (key => value, key => value, ...);
28        # or:
29        Readonly::Hash       %has => {key => value, key => value, ...};
30
31        # You can use the read-only variables like any regular variables:
32        print $sca;
33        $something = $sca + $arr[2];
34        next if $has{$some_key};
35
36        # But if you try to modify a value, your program will die:
37        $sca = 7;
38        push @arr, 'seven';
39        delete $has{key};
40        # The error message is "Modification of a read-only value
41       attempted"
42
43        # Alternate form (Perl 5.8 and later)
44        Readonly    $sca => $initial_value;
45        Readonly my $sca => $initial_value;
46        Readonly    @arr => @values;
47        Readonly my @arr => @values;
48        Readonly    %has => (key => value, key => value, ...);
49        Readonly my %has => (key => value, key => value, ...);
50        # Alternate form (for Perls earlier than v5.8)
51        Readonly    \$sca => $initial_value;
52        Readonly \my $sca => $initial_value;
53        Readonly    \@arr => @values;
54        Readonly \my @arr => @values;
55        Readonly    \%has => (key => value, key => value, ...);
56        Readonly \my %has => (key => value, key => value, ...);
57

DESCRIPTION

59       This is a facility for creating non-modifiable variables.  This is
60       useful for configuration files, headers, etc.  It can also be useful as
61       a development and debugging tool, for catching updates to variables
62       that should not be changed.
63
64       If any of the values you pass to "Scalar", "Array", or "Hash" are
65       references, then those functions recurse over the data structures,
66       marking everything as Readonly.  Usually, this is what you want: the
67       entire structure nonmodifiable.  If you want only the top level to be
68       Readonly, use the alternate "Scalar1", "Array1" and "Hash1" functions.
69
70       Please note that most users of Readonly will also want to install a
71       companion module Readonly::XS.  See the "CONS" section below for more
72       details.
73

COMPARISON WITH "use constant"

75       Perl provides a facility for creating constant values, via the "use
76       constant" pragma.  There are several problems with this pragma.
77
78       · The constants created have no leading $ or @ character.
79
80       · These constants cannot be interpolated into strings.
81
82       · Syntax can get dicey sometimes.  For example:
83
84          use constant CARRAY => (2, 3, 5, 7, 11, 13);
85          $a_prime = CARRAY[2];        # wrong!
86          $a_prime = (CARRAY)[2];      # right -- MUST use parentheses
87
88       · You have to be very careful in places where barewords are allowed.
89         For example:
90
91          use constant SOME_KEY => 'key';
92          %hash = (key => 'value', other_key => 'other_value');
93          $some_value = $hash{SOME_KEY};        # wrong!
94          $some_value = $hash{+SOME_KEY};       # right
95
96         (who thinks to use a unary plus when using a hash?)
97
98       · "use constant" works for scalars and arrays, not hashes.
99
100       · These constants are global ot the package in which they're declared;
101         cannot be lexically scoped.
102
103       · Works only at compile time.
104
105       · Can be overridden:
106
107          use constant PI => 3.14159;
108          ...
109          use constant PI => 2.71828;
110
111         (this does generate a warning, however, if you have warnings
112         enabled).
113
114       · It is very difficult to make and use deep structures (complex data
115         structures) with "use constant".
116

COMPARISON WITH TYPEGLOB CONSTANTS

118       Another popular way to create read-only scalars is to modify the symbol
119       table entry for the variable by using a typeglob:
120
121        *a = \'value';
122
123       This works fine, but it only works for global variables ("my" variables
124       have no symbol table entry).  Also, the following similar constructs do
125       not work:
126
127        *a = [1, 2, 3];      # Does NOT create a read-only array
128        *a = { a => 'A'};    # Does NOT create a read-only hash
129

PROS

131       Readonly.pm, on the other hand, will work with global variables and
132       with lexical ("my") variables.  It will create scalars, arrays, or
133       hashes, all of which look and work like normal, read-write Perl
134       variables.  You can use them in scalar context, in list context; you
135       can take references to them, pass them to functions, anything.
136
137       Readonly.pm also works well with complex data structures, allowing you
138       to tag the whole structure as nonmodifiable, or just the top level.
139
140       Also, Readonly variables may not be reassigned.  The following code
141       will die:
142
143        Readonly::Scalar $pi => 3.14159;
144        ...
145        Readonly::Scalar $pi => 2.71828;
146

CONS

148       Readonly.pm does impose a performance penalty.  It's pretty slow.  How
149       slow?  Run the "benchmark.pl" script that comes with Readonly.  On my
150       test system, "use constant", typeglob constants, and regular read/write
151       Perl variables were all about the same speed, and Readonly.pm constants
152       were about 1/20 the speed.
153
154       However, there is relief.  There is a companion module available,
155       Readonly::XS.  If it is installed on your system, Readonly.pm uses it
156       to make read-only scalars much faster.  With Readonly::XS, Readonly
157       scalars are as fast as the other types of variables.  Readonly arrays
158       and hashes will still be relatively slow.  But it's likely that most of
159       your Readonly variables will be scalars.
160
161       If you can't use Readonly::XS (for example, if you don't have a C
162       compiler, or your perl is statically linked and you don't want to re-
163       link it), you have to decide whether the benefits of Readonly variables
164       outweigh the speed issue. For most configuration variables (and other
165       things that Readonly is likely to be useful for), the speed issue is
166       probably not really a big problem.  But benchmark your program if it
167       might be.  If it turns out to be a problem, you may still want to use
168       Readonly.pm during development, to catch changes to variables that
169       should not be changed, and then remove it for production:
170
171        # For testing:
172        Readonly::Scalar  $Foo_Directory => '/usr/local/foo';
173        Readonly::Scalar  $Bar_Directory => '/usr/local/bar';
174        # $Foo_Directory = '/usr/local/foo';
175        # $Bar_Directory = '/usr/local/bar';
176
177        # For production:
178        # Readonly::Scalar  $Foo_Directory => '/usr/local/foo';
179        # Readonly::Scalar  $Bar_Directory => '/usr/local/bar';
180        $Foo_Directory = '/usr/local/foo';
181        $Bar_Directory = '/usr/local/bar';
182

FUNCTIONS

184       Readonly::Scalar $var => $value;
185           Creates a nonmodifiable scalar, $var, and assigns a value of $value
186           to it.  Thereafter, its value may not be changed.  Any attempt to
187           modify the value will cause your program to die.
188
189           A value must be supplied.  If you want the variable to have "undef"
190           as its value, you must specify "undef".
191
192           If $value is a reference to a scalar, array, or hash, then this
193           function will mark the scalar, array, or hash it points to as being
194           Readonly as well, and it will recursively traverse the structure,
195           marking the whole thing as Readonly.  Usually, this is what you
196           want.  However, if you want only the $value marked as Readonly, use
197           "Scalar1".
198
199           If $var is already a Readonly variable, the program will die with
200           an error about reassigning Readonly variables.
201
202       Readonly::Array @arr => (value, value, ...);
203           Creates a nonmodifiable array, @arr, and assigns the specified list
204           of values to it.  Thereafter, none of its values may be changed;
205           the array may not be lengthened or shortened or spliced.  Any
206           attempt to do so will cause your program to die.
207
208           If any of the values passed is a reference to a scalar, array, or
209           hash, then this function will mark the scalar, array, or hash it
210           points to as being Readonly as well, and it will recursively
211           traverse the structure, marking the whole thing as Readonly.
212           Usually, this is what you want.  However, if you want only the hash
213           %@arr itself marked as Readonly, use "Array1".
214
215           If @arr is already a Readonly variable, the program will die with
216           an error about reassigning Readonly variables.
217
218       Readonly::Hash %h => (key => value, key => value, ...);
219       Readonly::Hash %h => {key => value, key => value, ...};
220           Creates a nonmodifiable hash, %h, and assigns the specified keys
221           and values to it.  Thereafter, its keys or values may not be
222           changed.  Any attempt to do so will cause your program to die.
223
224           A list of keys and values may be specified (with parentheses in the
225           synopsis above), or a hash reference may be specified (curly braces
226           in the synopsis above).  If a list is specified, it must have an
227           even number of elements, or the function will die.
228
229           If any of the values is a reference to a scalar, array, or hash,
230           then this function will mark the scalar, array, or hash it points
231           to as being Readonly as well, and it will recursively traverse the
232           structure, marking the whole thing as Readonly.  Usually, this is
233           what you want.  However, if you want only the hash %h itself marked
234           as Readonly, use "Hash1".
235
236           If %h is already a Readonly variable, the program will die with an
237           error about reassigning Readonly variables.
238
239       Readonly $var => $value;
240       Readonly @arr => (value, value, ...);
241       Readonly %h => (key => value, ...);
242       Readonly %h => {key => value, ...};
243           The "Readonly" function is an alternate to the "Scalar", "Array",
244           and "Hash" functions.  It has the advantage (if you consider it an
245           advantage) of being one function.  That may make your program look
246           neater, if you're initializing a whole bunch of constants at once.
247           You may or may not prefer this uniform style.
248
249           It has the disadvantage of having a slightly different syntax for
250           versions of Perl prior to 5.8.  For earlier versions, you must
251           supply a backslash, because it requires a reference as the first
252           parameter.
253
254             Readonly \$var => $value;
255             Readonly \@arr => (value, value, ...);
256             Readonly \%h => (key => value, ...);
257             Readonly \%h => {key => value, ...};
258
259           You may or may not consider this ugly.
260
261       Readonly::Scalar1 $var => $value;
262       Readonly::Array1 @arr => (value, value, ...);
263       Readonly::Hash1 %h => (key => value, key => value, ...);
264       Readonly::Hash1 %h => {key => value, key => value, ...};
265           These alternate functions create shallow Readonly variables,
266           instead of deep ones.  For example:
267
268            Readonly::Array1 @shal => (1, 2, {perl=>'Rules', java=>'Bites'}, 4, 5);
269            Readonly::Array  @deep => (1, 2, {perl=>'Rules', java=>'Bites'}, 4, 5);
270
271            $shal[1] = 7;           # error
272            $shal[2]{APL}='Weird';  # Allowed! since the hash isn't Readonly
273            $deep[1] = 7;           # error
274            $deep[2]{APL}='Weird';  # error, since the hash is Readonly
275

EXAMPLES

277        # SCALARS:
278
279        # A plain old read-only value
280        Readonly::Scalar $a => "A string value";
281
282        # The value need not be a compile-time constant:
283        Readonly::Scalar $a => $computed_value;
284
285
286        # ARRAYS:
287
288        # A read-only array:
289        Readonly::Array @a => (1, 2, 3, 4);
290
291        # The parentheses are optional:
292        Readonly::Array @a => 1, 2, 3, 4;
293
294        # You can use Perl's built-in array quoting syntax:
295        Readonly::Array @a => qw/1 2 3 4/;
296
297        # You can initialize a read-only array from a variable one:
298        Readonly::Array @a => @computed_values;
299
300        # A read-only array can be empty, too:
301        Readonly::Array @a => ();
302        Readonly::Array @a;        # equivalent
303
304
305        # HASHES
306
307        # Typical usage:
308        Readonly::Hash %a => (key1 => 'value1', key2 => 'value2');
309
310        # A read-only hash can be initialized from a variable one:
311        Readonly::Hash %a => %computed_values;
312
313        # A read-only hash can be empty:
314        Readonly::Hash %a => ();
315        Readonly::Hash %a;        # equivalent
316
317        # If you pass an odd number of values, the program will die:
318        Readonly::Hash %a => (key1 => 'value1', "value2");
319            --> dies with "May not store an odd number of values in a hash"
320

EXPORTS

322       By default, this module exports the following symbol into the calling
323       program's namespace:
324
325        Readonly
326
327       The following symbols are available for import into your program, if
328       you like:
329
330        Scalar  Scalar1
331        Array   Array1
332        Hash    Hash1
333

REQUIREMENTS

335        Perl 5.000
336        Carp.pm (included with Perl)
337        Exporter.pm (included with Perl)
338
339        Readonly::XS is recommended but not required.
340

ACKNOWLEDGEMENTS

342       Thanks to Slaven Rezic for the idea of one common function (Readonly)
343       for all three types of variables (13 April 2002).
344
345       Thanks to Ernest Lergon for the idea (and initial code) for deeply-
346       Readonly data structures (21 May 2002).
347
348       Thanks to Damian Conway for the idea (and code) for making the Readonly
349       function work a lot smoother under perl 5.8+.
350
352       Eric J. Roode, roode@cpan.org
353
354       Copyright (c) 2001-2004 by Eric J. Roode. All Rights Reserved.  This
355       module is free software; you can redistribute it and/or modify it under
356       the same terms as Perl itself.
357
358       If you have suggestions for improvement, please drop me a line.  If you
359       make improvements to this software, I ask that you please send me a
360       copy of your changes. Thanks.
361
362       Readonly.pm is made from 100% recycled electrons.  No animals were
363       harmed during the development and testing of this module.  Not sold in
364       stores!  Readonly::XS sold separately.  Void where prohibited.
365
366
367
368perl v5.12.0                      2004-04-20                       Readonly(3)
Impressum