Readonly.pm
Go to the documentation of this file.
00001 =for gpg 00002 -----BEGIN PGP SIGNED MESSAGE----- 00003 Hash: SHA1 00004 00005 - -----BEGIN PGP SIGNED MESSAGE----- 00006 Hash: SHA1 00007 00008 =head1 NAME 00009 00010 Readonly - Facility for creating read-only scalars, arrays, hashes. 00011 00012 =head1 VERSION 00013 00014 This documentation describes version 1.03 of Readonly.pm, April 20, 2004. 00015 00016 =cut 00017 00018 # Rest of documentation is after __END__. 00019 00020 use 5.005; 00021 use strict; 00022 #use warnings; 00023 #no warnings 'uninitialized'; 00024 00025 package Readonly; 00026 $Readonly::VERSION = '1.03'; # Also change in the documentation! 00027 00028 # Autocroak (Thanks, MJD) 00029 # Only load Carp.pm if module is croaking. 00030 sub croak 00031 { 00032 require Carp; 00033 goto &Carp::croak; 00034 } 00035 00036 # These functions may be overridden by Readonly::XS, if installed. 00037 sub is_sv_readonly ($) { 0 } 00038 sub make_sv_readonly ($) { die "make_sv_readonly called but not overridden" } 00039 use vars qw/$XSokay/; # Set to true in Readonly::XS, if available 00040 00041 # Common error messages, or portions thereof 00042 use vars qw/$MODIFY $REASSIGN $ODDHASH/; 00043 $MODIFY = 'Modification of a read-only value attempted'; 00044 $REASSIGN = 'Attempt to reassign a readonly'; 00045 $ODDHASH = 'May not store an odd number of values in a hash'; 00046 00047 # See if we can use the XS stuff. 00048 $Readonly::XS::MAGIC_COOKIE = "Do NOT use or require Readonly::XS unless you're me."; 00049 eval 'use Readonly::XS'; 00050 00051 00052 # ---------------- 00053 # Read-only scalars 00054 # ---------------- 00055 package Readonly::Scalar; 00056 00057 sub TIESCALAR 00058 { 00059 my $whence = (caller 2)[3]; # Check if naughty user is trying to tie directly. 00060 Readonly::croak "Invalid tie" unless $whence && $whence =~ /^Readonly::(?:Scalar1?|Readonly)$/; 00061 my $class = shift; 00062 Readonly::croak "No value specified for readonly scalar" unless @_; 00063 Readonly::croak "Too many values specified for readonly scalar" unless @_ == 1; 00064 00065 my $value = shift; 00066 return bless \$value, $class; 00067 } 00068 00069 sub FETCH 00070 { 00071 my $self = shift; 00072 return $$self; 00073 } 00074 00075 *STORE = *UNTIE = 00076 sub {Readonly::croak $Readonly::MODIFY}; 00077 00078 00079 # ---------------- 00080 # Read-only arrays 00081 # ---------------- 00082 package Readonly::Array; 00083 00084 sub TIEARRAY 00085 { 00086 my $whence = (caller 1)[3]; # Check if naughty user is trying to tie directly. 00087 Readonly::croak "Invalid tie" unless $whence =~ /^Readonly::Array1?$/; 00088 my $class = shift; 00089 my @self = @_; 00090 00091 return bless \@self, $class; 00092 } 00093 00094 sub FETCH 00095 { 00096 my $self = shift; 00097 my $index = shift; 00098 return $self->[$index]; 00099 } 00100 00101 sub FETCHSIZE 00102 { 00103 my $self = shift; 00104 return scalar @$self; 00105 } 00106 00107 BEGIN { 00108 eval q{ 00109 sub EXISTS 00110 { 00111 my $self = shift; 00112 my $index = shift; 00113 return exists $self->[$index]; 00114 } 00115 } if $] >= 5.006; # couldn't do "exists" on arrays before then 00116 } 00117 00118 *STORE = *STORESIZE = *EXTEND = *PUSH = *POP = *UNSHIFT = *SHIFT = *SPLICE = *CLEAR = *UNTIE = 00119 sub {Readonly::croak $Readonly::MODIFY}; 00120 00121 00122 # ---------------- 00123 # Read-only hashes 00124 # ---------------- 00125 package Readonly::Hash; 00126 00127 sub TIEHASH 00128 { 00129 my $whence = (caller 1)[3]; # Check if naughty user is trying to tie directly. 00130 Readonly::croak "Invalid tie" unless $whence =~ /^Readonly::Hash1?$/; 00131 00132 my $class = shift; 00133 # must have an even number of values 00134 Readonly::croak $Readonly::ODDHASH unless (@_ %2 == 0); 00135 00136 my %self = @_; 00137 return bless \%self, $class; 00138 } 00139 00140 sub FETCH 00141 { 00142 my $self = shift; 00143 my $key = shift; 00144 00145 return $self->{$key}; 00146 } 00147 00148 sub EXISTS 00149 { 00150 my $self = shift; 00151 my $key = shift; 00152 return exists $self->{$key}; 00153 } 00154 00155 sub FIRSTKEY 00156 { 00157 my $self = shift; 00158 my $dummy = keys %$self; 00159 return scalar each %$self; 00160 } 00161 00162 sub NEXTKEY 00163 { 00164 my $self = shift; 00165 return scalar each %$self; 00166 } 00167 00168 *STORE = *DELETE = *CLEAR = *UNTIE = 00169 sub {Readonly::croak $Readonly::MODIFY}; 00170 00171 00172 # ---------------------------------------------------------------- 00173 # Main package, containing convenience functions (so callers won't 00174 # have to explicitly tie the variables themselves). 00175 # ---------------------------------------------------------------- 00176 package Readonly; 00177 use Exporter; 00178 use vars qw/@ISA @EXPORT @EXPORT_OK %EXPORT_TAGS/; 00179 push @ISA, 'Exporter'; 00180 push @EXPORT, qw/Readonly/; 00181 push @EXPORT_OK, qw/Scalar Array Hash Scalar1 Array1 Hash1/; 00182 00183 # Predeclare the following, so we can use them recursively 00184 sub Scalar ($$); 00185 sub Array (\@;@); 00186 sub Hash (\%;@); 00187 00188 # Returns true if a string begins with "Readonly::" 00189 # Used to prevent reassignment of Readonly variables. 00190 sub _is_badtype 00191 { 00192 my $type = $_[0]; 00193 return lc $type if $type =~ s/^Readonly:://; 00194 return; 00195 } 00196 00197 # Shallow Readonly scalar 00198 sub Scalar1 ($$) 00199 { 00200 croak "$REASSIGN scalar" if is_sv_readonly $_[0]; 00201 my $badtype = _is_badtype (ref tied $_[0]); 00202 croak "$REASSIGN $badtype" if $badtype; 00203 00204 # xs method: flag scalar as readonly 00205 if ($XSokay) 00206 { 00207 $_[0] = $_[1]; 00208 make_sv_readonly $_[0]; 00209 return; 00210 } 00211 00212 # pure-perl method: tied scalar 00213 my $tieobj = eval {tie $_[0], 'Readonly::Scalar', $_[1]}; 00214 if ($@) 00215 { 00216 croak "$REASSIGN scalar" if substr($@,0,43) eq $MODIFY; 00217 die $@; # some other error? 00218 } 00219 return $tieobj; 00220 } 00221 00222 # Shallow Readonly array 00223 sub Array1 (\@;@) 00224 { 00225 my $badtype = _is_badtype (ref tied $_[0]); 00226 croak "$REASSIGN $badtype" if $badtype; 00227 00228 my $aref = shift; 00229 return tie @$aref, 'Readonly::Array', @_; 00230 } 00231 00232 # Shallow Readonly hash 00233 sub Hash1 (\%;@) 00234 { 00235 my $badtype = _is_badtype (ref tied $_[0]); 00236 croak "$REASSIGN $badtype" if $badtype; 00237 00238 my $href = shift; 00239 00240 # If only one value, and it's a hashref, expand it 00241 if (@_ == 1 && ref $_[0] eq 'HASH') 00242 { 00243 return tie %$href, 'Readonly::Hash', %{$_[0]}; 00244 } 00245 00246 # otherwise, must have an even number of values 00247 croak $ODDHASH unless (@_%2 == 0); 00248 00249 return tie %$href, 'Readonly::Hash', @_; 00250 } 00251 00252 # Deep Readonly scalar 00253 sub Scalar ($$) 00254 { 00255 croak "$REASSIGN scalar" if is_sv_readonly $_[0]; 00256 my $badtype = _is_badtype (ref tied $_[0]); 00257 croak "$REASSIGN $badtype" if $badtype; 00258 00259 my $value = $_[1]; 00260 00261 # Recursively check passed element for references; if any, make them Readonly 00262 foreach ($value) 00263 { 00264 if (ref eq 'SCALAR') {Scalar my $v => $$_; $_ = \$v} 00265 elsif (ref eq 'ARRAY') {Array my @v => @$_; $_ = \@v} 00266 elsif (ref eq 'HASH') {Hash my %v => $_; $_ = \%v} 00267 } 00268 00269 # xs method: flag scalar as readonly 00270 if ($XSokay) 00271 { 00272 $_[0] = $value; 00273 make_sv_readonly $_[0]; 00274 return; 00275 } 00276 00277 # pure-perl method: tied scalar 00278 my $tieobj = eval {tie $_[0], 'Readonly::Scalar', $value}; 00279 if ($@) 00280 { 00281 croak "$REASSIGN scalar" if substr($@,0,43) eq $MODIFY; 00282 die $@; # some other error? 00283 } 00284 return $tieobj; 00285 } 00286 00287 # Deep Readonly array 00288 sub Array (\@;@) 00289 { 00290 my $badtype = _is_badtype (ref tied @{$_[0]}); 00291 croak "$REASSIGN $badtype" if $badtype; 00292 00293 my $aref = shift; 00294 my @values = @_; 00295 00296 # Recursively check passed elements for references; if any, make them Readonly 00297 foreach (@values) 00298 { 00299 if (ref eq 'SCALAR') {Scalar my $v => $$_; $_ = \$v} 00300 elsif (ref eq 'ARRAY') {Array my @v => @$_; $_ = \@v} 00301 elsif (ref eq 'HASH') {Hash my %v => $_; $_ = \%v} 00302 } 00303 # Lastly, tie the passed reference 00304 return tie @$aref, 'Readonly::Array', @values; 00305 } 00306 00307 # Deep Readonly hash 00308 sub Hash (\%;@) 00309 { 00310 my $badtype = _is_badtype (ref tied %{$_[0]}); 00311 croak "$REASSIGN $badtype" if $badtype; 00312 00313 my $href = shift; 00314 my @values = @_; 00315 00316 # If only one value, and it's a hashref, expand it 00317 if (@_ == 1 && ref $_[0] eq 'HASH') 00318 { 00319 @values = %{$_[0]}; 00320 } 00321 00322 # otherwise, must have an even number of values 00323 croak $ODDHASH unless (@values %2 == 0); 00324 00325 # Recursively check passed elements for references; if any, make them Readonly 00326 foreach (@values) 00327 { 00328 if (ref eq 'SCALAR') {Scalar my $v => $$_; $_ = \$v} 00329 elsif (ref eq 'ARRAY') {Array my @v => @$_; $_ = \@v} 00330 elsif (ref eq 'HASH') {Hash my %v => $_; $_ = \%v} 00331 } 00332 00333 return tie %$href, 'Readonly::Hash', @values; 00334 } 00335 00336 00337 # Common entry-point for all supported data types 00338 eval q{sub Readonly} . ( $] < 5.008 ? '' : '(\[$@%]@)' ) . <<'SUB_READONLY'; 00339 { 00340 if (ref $_[0] eq 'SCALAR') 00341 { 00342 croak $MODIFY if is_sv_readonly ${$_[0]}; 00343 my $badtype = _is_badtype (ref tied ${$_[0]}); 00344 croak "$REASSIGN $badtype" if $badtype; 00345 croak "Readonly scalar must have only one value" if @_ > 2; 00346 00347 my $tieobj = eval {tie ${$_[0]}, 'Readonly::Scalar', $_[1]}; 00348 # Tie may have failed because user tried to tie a constant, or we screwed up somehow. 00349 if ($@) 00350 { 00351 croak $MODIFY if $@ =~ /^$MODIFY at/; # Point the finger at the user. 00352 die "$@\n"; # Not a modify read-only message; must be our fault. 00353 } 00354 return $tieobj; 00355 } 00356 elsif (ref $_[0] eq 'ARRAY') 00357 { 00358 my $aref = shift; 00359 return Array @$aref, @_; 00360 } 00361 elsif (ref $_[0] eq 'HASH') 00362 { 00363 my $href = shift; 00364 croak $ODDHASH if @_%2 != 0 && !(@_ == 1 && ref $_[0] eq 'HASH'); 00365 return Hash %$href, @_; 00366 } 00367 elsif (ref $_[0]) 00368 { 00369 croak "Readonly only supports scalar, array, and hash variables."; 00370 } 00371 else 00372 { 00373 croak "First argument to Readonly must be a reference."; 00374 } 00375 } 00376 SUB_READONLY 00377 00378 00379 1; 00380 __END__ 00381 00382 =head1 SYNOPSIS 00383 00384 use Readonly; 00385 00386 # Read-only scalar 00387 Readonly::Scalar $sca => $initial_value; 00388 Readonly::Scalar my $sca => $initial_value; 00389 00390 # Read-only array 00391 Readonly::Array @arr => @values; 00392 Readonly::Array my @arr => @values; 00393 00394 # Read-only hash 00395 Readonly::Hash %has => (key => value, key => value, ...); 00396 Readonly::Hash my %has => (key => value, key => value, ...); 00397 # or: 00398 Readonly::Hash %has => {key => value, key => value, ...}; 00399 00400 # You can use the read-only variables like any regular variables: 00401 print $sca; 00402 $something = $sca + $arr[2]; 00403 next if $has{$some_key}; 00404 00405 # But if you try to modify a value, your program will die: 00406 $sca = 7; 00407 push @arr, 'seven'; 00408 delete $has{key}; 00409 # The error message is "Modification of a read-only value 00410 attempted" 00411 00412 # Alternate form (Perl 5.8 and later) 00413 Readonly $sca => $initial_value; 00414 Readonly my $sca => $initial_value; 00415 Readonly @arr => @values; 00416 Readonly my @arr => @values; 00417 Readonly %has => (key => value, key => value, ...); 00418 Readonly my %has => (key => value, key => value, ...); 00419 # Alternate form (for Perls earlier than v5.8) 00420 Readonly \$sca => $initial_value; 00421 Readonly \my $sca => $initial_value; 00422 Readonly \@arr => @values; 00423 Readonly \my @arr => @values; 00424 Readonly \%has => (key => value, key => value, ...); 00425 Readonly \my %has => (key => value, key => value, ...); 00426 00427 00428 =head1 DESCRIPTION 00429 00430 This is a facility for creating non-modifiable variables. This is 00431 useful for configuration files, headers, etc. It can also be useful 00432 as a development and debugging tool, for catching updates to variables 00433 that should not be changed. 00434 00435 If any of the values you pass to C<Scalar>, C<Array>, or C<Hash> are 00436 references, then those functions recurse over the data structures, 00437 marking everything as Readonly. Usually, this is what you want: the 00438 entire structure nonmodifiable. If you want only the top level to be 00439 Readonly, use the alternate C<Scalar1>, C<Array1> and C<Hash1> 00440 functions. 00441 00442 Please note that most users of Readonly will also want to install a 00443 companion module Readonly::XS. See the L</CONS> section below for more 00444 details. 00445 00446 =head1 COMPARISON WITH "use constant" 00447 00448 Perl provides a facility for creating constant values, via the "use 00449 constant" pragma. There are several problems with this pragma. 00450 00451 =over 2 00452 00453 =item * 00454 00455 The constants created have no leading $ or @ character. 00456 00457 =item * 00458 00459 These constants cannot be interpolated into strings. 00460 00461 =item * 00462 00463 Syntax can get dicey sometimes. For example: 00464 00465 use constant CARRAY => (2, 3, 5, 7, 11, 13); 00466 $a_prime = CARRAY[2]; # wrong! 00467 $a_prime = (CARRAY)[2]; # right -- MUST use parentheses 00468 00469 =item * 00470 00471 You have to be very careful in places where barewords are allowed. 00472 For example: 00473 00474 use constant SOME_KEY => 'key'; 00475 %hash = (key => 'value', other_key => 'other_value'); 00476 $some_value = $hash{SOME_KEY}; # wrong! 00477 $some_value = $hash{+SOME_KEY}; # right 00478 00479 (who thinks to use a unary plus when using a hash?) 00480 00481 =item * 00482 00483 C<use constant> works for scalars and arrays, not hashes. 00484 00485 =item * 00486 00487 These constants are global ot the package in which they're declared; 00488 cannot be lexically scoped. 00489 00490 =item * 00491 00492 Works only at compile time. 00493 00494 =item * 00495 00496 Can be overridden: 00497 00498 use constant PI => 3.14159; 00499 ... 00500 use constant PI => 2.71828; 00501 00502 (this does generate a warning, however, if you have warnings enabled). 00503 00504 =item * 00505 00506 It is very difficult to make and use deep structures (complex data 00507 structures) with C<use constant>. 00508 00509 =back 00510 00511 =head1 COMPARISON WITH TYPEGLOB CONSTANTS 00512 00513 Another popular way to create read-only scalars is to modify the symbol 00514 table entry for the variable by using a typeglob: 00515 00516 *a = \'value'; 00517 00518 This works fine, but it only works for global variables ("my" 00519 variables have no symbol table entry). Also, the following similar 00520 constructs do B<not> work: 00521 00522 *a = [1, 2, 3]; # Does NOT create a read-only array 00523 *a = { a => 'A'}; # Does NOT create a read-only hash 00524 00525 =head1 PROS 00526 00527 Readonly.pm, on the other hand, will work with global variables and 00528 with lexical ("my") variables. It will create scalars, arrays, or 00529 hashes, all of which look and work like normal, read-write Perl 00530 variables. You can use them in scalar context, in list context; you 00531 can take references to them, pass them to functions, anything. 00532 00533 Readonly.pm also works well with complex data structures, allowing you 00534 to tag the whole structure as nonmodifiable, or just the top level. 00535 00536 Also, Readonly variables may not be reassigned. The following code 00537 will die: 00538 00539 Readonly::Scalar $pi => 3.14159; 00540 ... 00541 Readonly::Scalar $pi => 2.71828; 00542 00543 =head1 CONS 00544 00545 Readonly.pm does impose a performance penalty. It's pretty slow. How 00546 slow? Run the C<benchmark.pl> script that comes with Readonly. On my 00547 test system, "use constant", typeglob constants, and regular 00548 read/write Perl variables were all about the same speed, and 00549 Readonly.pm constants were about 1/20 the speed. 00550 00551 However, there is relief. There is a companion module available, 00552 Readonly::XS. If it is installed on your system, Readonly.pm uses it 00553 to make read-only scalars much faster. With Readonly::XS, Readonly 00554 scalars are as fast as the other types of variables. Readonly arrays 00555 and hashes will still be relatively slow. But it's likely that most 00556 of your Readonly variables will be scalars. 00557 00558 If you can't use Readonly::XS (for example, if you don't have a C 00559 compiler, or your perl is statically linked and you don't want to 00560 re-link it), you have to decide whether the benefits of Readonly 00561 variables outweigh the speed issue. For most configuration variables 00562 (and other things that Readonly is likely to be useful for), the speed 00563 issue is probably not really a big problem. But benchmark your 00564 program if it might be. If it turns out to be a problem, you may 00565 still want to use Readonly.pm during development, to catch changes to 00566 variables that should not be changed, and then remove it for 00567 production: 00568 00569 # For testing: 00570 Readonly::Scalar $Foo_Directory => '/usr/local/foo'; 00571 Readonly::Scalar $Bar_Directory => '/usr/local/bar'; 00572 # $Foo_Directory = '/usr/local/foo'; 00573 # $Bar_Directory = '/usr/local/bar'; 00574 00575 # For production: 00576 # Readonly::Scalar $Foo_Directory => '/usr/local/foo'; 00577 # Readonly::Scalar $Bar_Directory => '/usr/local/bar'; 00578 $Foo_Directory = '/usr/local/foo'; 00579 $Bar_Directory = '/usr/local/bar'; 00580 00581 00582 =head1 FUNCTIONS 00583 00584 =over 4 00585 00586 =item Readonly::Scalar $var => $value; 00587 00588 Creates a nonmodifiable scalar, C<$var>, and assigns a value of 00589 C<$value> to it. Thereafter, its value may not be changed. Any 00590 attempt to modify the value will cause your program to die. 00591 00592 A value I<must> be supplied. If you want the variable to have 00593 C<undef> as its value, you must specify C<undef>. 00594 00595 If C<$value> is a reference to a scalar, array, or hash, then this 00596 function will mark the scalar, array, or hash it points to as being 00597 Readonly as well, and it will recursively traverse the structure, 00598 marking the whole thing as Readonly. Usually, this is what you want. 00599 However, if you want only the C<$value> marked as Readonly, use 00600 C<Scalar1>. 00601 00602 If $var is already a Readonly variable, the program will die with 00603 an error about reassigning Readonly variables. 00604 00605 =item Readonly::Array @arr => (value, value, ...); 00606 00607 Creates a nonmodifiable array, C<@arr>, and assigns the specified list 00608 of values to it. Thereafter, none of its values may be changed; the 00609 array may not be lengthened or shortened or spliced. Any attempt to 00610 do so will cause your program to die. 00611 00612 If any of the values passed is a reference to a scalar, array, or hash, 00613 then this function will mark the scalar, array, or hash it points to as 00614 being Readonly as well, and it will recursively traverse the structure, 00615 marking the whole thing as Readonly. Usually, this is what you want. 00616 However, if you want only the hash C<%@arr> itself marked as Readonly, 00617 use C<Array1>. 00618 00619 If @arr is already a Readonly variable, the program will die with 00620 an error about reassigning Readonly variables. 00621 00622 =item Readonly::Hash %h => (key => value, key => value, ...); 00623 00624 =item Readonly::Hash %h => {key => value, key => value, ...}; 00625 00626 Creates a nonmodifiable hash, C<%h>, and assigns the specified keys 00627 and values to it. Thereafter, its keys or values may not be changed. 00628 Any attempt to do so will cause your program to die. 00629 00630 A list of keys and values may be specified (with parentheses in the 00631 synopsis above), or a hash reference may be specified (curly braces in 00632 the synopsis above). If a list is specified, it must have an even 00633 number of elements, or the function will die. 00634 00635 If any of the values is a reference to a scalar, array, or hash, then 00636 this function will mark the scalar, array, or hash it points to as 00637 being Readonly as well, and it will recursively traverse the 00638 structure, marking the whole thing as Readonly. Usually, this is what 00639 you want. However, if you want only the hash C<%h> itself marked as 00640 Readonly, use C<Hash1>. 00641 00642 If %h is already a Readonly variable, the program will die with 00643 an error about reassigning Readonly variables. 00644 00645 =item Readonly $var => $value; 00646 00647 =item Readonly @arr => (value, value, ...); 00648 00649 =item Readonly %h => (key => value, ...); 00650 00651 =item Readonly %h => {key => value, ...}; 00652 00653 The C<Readonly> function is an alternate to the C<Scalar>, C<Array>, 00654 and C<Hash> functions. It has the advantage (if you consider it an 00655 advantage) of being one function. That may make your program look 00656 neater, if you're initializing a whole bunch of constants at once. 00657 You may or may not prefer this uniform style. 00658 00659 It has the disadvantage of having a slightly different syntax for 00660 versions of Perl prior to 5.8. For earlier versions, you must supply 00661 a backslash, because it requires a reference as the first parameter. 00662 00663 Readonly \$var => $value; 00664 Readonly \@arr => (value, value, ...); 00665 Readonly \%h => (key => value, ...); 00666 Readonly \%h => {key => value, ...}; 00667 00668 You may or may not consider this ugly. 00669 00670 =item Readonly::Scalar1 $var => $value; 00671 00672 =item Readonly::Array1 @arr => (value, value, ...); 00673 00674 =item Readonly::Hash1 %h => (key => value, key => value, ...); 00675 00676 =item Readonly::Hash1 %h => {key => value, key => value, ...}; 00677 00678 These alternate functions create shallow Readonly variables, instead 00679 of deep ones. For example: 00680 00681 Readonly::Array1 @shal => (1, 2, {perl=>'Rules', java=>'Bites'}, 4, 5); 00682 Readonly::Array @deep => (1, 2, {perl=>'Rules', java=>'Bites'}, 4, 5); 00683 00684 $shal[1] = 7; # error 00685 $shal[2]{APL}='Weird'; # Allowed! since the hash isn't Readonly 00686 $deep[1] = 7; # error 00687 $deep[2]{APL}='Weird'; # error, since the hash is Readonly 00688 00689 00690 =back 00691 00692 00693 =head1 EXAMPLES 00694 00695 # SCALARS: 00696 00697 # A plain old read-only value 00698 Readonly::Scalar $a => "A string value"; 00699 00700 # The value need not be a compile-time constant: 00701 Readonly::Scalar $a => $computed_value; 00702 00703 00704 # ARRAYS: 00705 00706 # A read-only array: 00707 Readonly::Array @a => (1, 2, 3, 4); 00708 00709 # The parentheses are optional: 00710 Readonly::Array @a => 1, 2, 3, 4; 00711 00712 # You can use Perl's built-in array quoting syntax: 00713 Readonly::Array @a => qw/1 2 3 4/; 00714 00715 # You can initialize a read-only array from a variable one: 00716 Readonly::Array @a => @computed_values; 00717 00718 # A read-only array can be empty, too: 00719 Readonly::Array @a => (); 00720 Readonly::Array @a; # equivalent 00721 00722 00723 # HASHES 00724 00725 # Typical usage: 00726 Readonly::Hash %a => (key1 => 'value1', key2 => 'value2'); 00727 00728 # A read-only hash can be initialized from a variable one: 00729 Readonly::Hash %a => %computed_values; 00730 00731 # A read-only hash can be empty: 00732 Readonly::Hash %a => (); 00733 Readonly::Hash %a; # equivalent 00734 00735 # If you pass an odd number of values, the program will die: 00736 Readonly::Hash %a => (key1 => 'value1', "value2"); 00737 --> dies with "May not store an odd number of values in a hash" 00738 00739 00740 =head1 EXPORTS 00741 00742 By default, this module exports the following symbol into the calling 00743 program's namespace: 00744 00745 Readonly 00746 00747 The following symbols are available for import into your program, if 00748 you like: 00749 00750 Scalar Scalar1 00751 Array Array1 00752 Hash Hash1 00753 00754 00755 =head1 REQUIREMENTS 00756 00757 Perl 5.000 00758 Carp.pm (included with Perl) 00759 Exporter.pm (included with Perl) 00760 00761 Readonly::XS is recommended but not required. 00762 00763 =head1 ACKNOWLEDGEMENTS 00764 00765 Thanks to Slaven Rezic for the idea of one common function 00766 (Readonly) for all three types of variables (13 April 2002). 00767 00768 Thanks to Ernest Lergon for the idea (and initial code) for 00769 deeply-Readonly data structures (21 May 2002). 00770 00771 Thanks to Damian Conway for the idea (and code) for making the 00772 Readonly function work a lot smoother under perl 5.8+. 00773 00774 00775 =head1 AUTHOR / COPYRIGHT 00776 00777 Eric J. Roode, roode@cpan.org 00778 00779 Copyright (c) 2001-2004 by Eric J. Roode. All Rights Reserved. This 00780 module is free software; you can redistribute it and/or modify it under 00781 the same terms as Perl itself. 00782 00783 If you have suggestions for improvement, please drop me a line. If 00784 you make improvements to this software, I ask that you please send me 00785 a copy of your changes. Thanks. 00786 00787 Readonly.pm is made from 100% recycled electrons. No animals were 00788 harmed during the development and testing of this module. Not sold 00789 in stores! Readonly::XS sold separately. Void where prohibited. 00790 00791 =cut 00792 00793 =begin gpg 00794 00795 -----BEGIN PGP SIGNATURE----- 00796 Version: GnuPG v1.2.4 (MingW32) 00797 00798 iD8DBQFAhaGCY96i4h5M0egRAg++AJ0ar4ncojbOp0OOc2wo+E/1cBn5cQCg9eP9 00799 qTzAC87PuyKB+vrcRykrDbo= 00800 =39Ny 00801 -----END PGP SIGNATURE----- 00802 00803 =cut