1Readonly(3) User Contributed Perl Documentation Readonly(3)
2- -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1
6
8 Readonly - Facility for creating read-only scalars, arrays, hashes.
9
11 This documentation describes version 1.03 of Readonly.pm, April 20,
12 2004.
13
15 use Readonly;
16 # Read-only scalar
18 Readonly::Scalar $sca => $initial_value;
19 Readonly::Scalar my $sca => $initial_value;
20 # Read-only array
22 Readonly::Array @arr => @values;
23 Readonly::Array my @arr => @values;
24 # 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 # 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 # 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 # 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
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 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 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
75 Perl provides a facility for creating constant values, via the "use
76 constant" pragma. There are several problems with this pragma.
77 · The constants created have no leading $ or @ character.
79 · These constants cannot be interpolated into strings.
81 · Syntax can get dicey sometimes. For example:
83 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 · You have to be very careful in places where barewords are allowed.
89 For example:
90 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 (who thinks to use a unary plus when using a hash?)
97 · "use constant" works for scalars and arrays, not hashes.
99 · These constants are global ot the package in which they're declared;
101 cannot be lexically scoped.
102 · Works only at compile time.
104 · Can be overridden:
106 use constant PI => 3.14159;
108 ...
109 use constant PI => 2.71828;
110 (this does generate a warning, however, if you have warnings
112 enabled).
113 · It is very difficult to make and use deep structures (complex data
115 structures) with "use constant".
116
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 *a = \'value';
122 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 *a = [1, 2, 3]; # Does NOT create a read-only array
128 *a = { a => 'A'}; # Does NOT create a read-only hash
129
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 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 Also, Readonly variables may not be reassigned. The following code
141 will die:
142 Readonly::Scalar $pi => 3.14159;
144 ...
145 Readonly::Scalar $pi => 2.71828;
146
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 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 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 # 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 # 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
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 A value must be supplied. If you want the variable to have "undef"
190 as its value, you must specify "undef".
191 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 If $var is already a Readonly variable, the program will die with
200 an error about reassigning Readonly variables.
201 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 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 If @arr is already a Readonly variable, the program will die with
216 an error about reassigning Readonly variables.
217 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 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 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 If %h is already a Readonly variable, the program will die with an
237 error about reassigning Readonly variables.
238 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 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 Readonly \$var => $value;
255 Readonly \@arr => (value, value, ...);
256 Readonly \%h => (key => value, ...);
257 Readonly \%h => {key => value, ...};
258 You may or may not consider this ugly.
260 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 Readonly::Array1 @shal => (1, 2, {perl=>'Rules', java=>'Bites'}, 4, 5);
269 Readonly::Array @deep => (1, 2, {perl=>'Rules', java=>'Bites'}, 4, 5);
270 $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
277 # SCALARS:
278 # A plain old read-only value
280 Readonly::Scalar $a => "A string value";
281 # The value need not be a compile-time constant:
283 Readonly::Scalar $a => $computed_value;
284 # ARRAYS:
287 # A read-only array:
289 Readonly::Array @a => (1, 2, 3, 4);
290 # The parentheses are optional:
292 Readonly::Array @a => 1, 2, 3, 4;
293 # You can use Perl's built-in array quoting syntax:
295 Readonly::Array @a => qw/1 2 3 4/;
296 # You can initialize a read-only array from a variable one:
298 Readonly::Array @a => @computed_values;
299 # A read-only array can be empty, too:
301 Readonly::Array @a => ();
302 Readonly::Array @a; # equivalent
303 # HASHES
306 # Typical usage:
308 Readonly::Hash %a => (key1 => 'value1', key2 => 'value2');
309 # A read-only hash can be initialized from a variable one:
311 Readonly::Hash %a => %computed_values;
312 # A read-only hash can be empty:
314 Readonly::Hash %a => ();
315 Readonly::Hash %a; # equivalent
316 # 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
322 By default, this module exports the following symbol into the calling
323 program's namespace:
324 Readonly
326 The following symbols are available for import into your program, if
328 you like:
329 Scalar Scalar1
331 Array Array1
332 Hash Hash1
333
335 Perl 5.000
336 Carp.pm (included with Perl)
337 Exporter.pm (included with Perl)
338 Readonly::XS is recommended but not required.
340
342 Thanks to Slaven Rezic for the idea of one common function (Readonly)
343 for all three types of variables (13 April 2002).
344 Thanks to Ernest Lergon for the idea (and initial code) for deeply-
346 Readonly data structures (21 May 2002).
347 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 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 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 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.
365perl v5.12.0 2004-04-20 Readonly(3)