use Readonly; # Deep Read-only scalar Readonly::Scalar $sca => $initial_value; Readonly::Scalar my $sca => $initial_value; # Deep Read-only array Readonly::Array @arr => @values; Readonly::Array my @arr => @values; # Deep Read-only hash Readonly::Hash %has => (key => value, key => value, ...); Readonly::Hash my %has => (key => value, key => value, ...); # or: Readonly::Hash %has => {key => value, key => value, ...}; # You can use the read-only variables like any regular variables: print $sca; $something = $sca + $arr[2]; next if $has{$some_key}; # But if you try to modify a value, your program will die: $sca = 7; push @arr, 'seven'; delete $has{key}; # The error message is "Modification of a read-only value attempted" # Alternate form (Perl 5.8 and later) Readonly $sca => $initial_value; Readonly my $sca => $initial_value; Readonly @arr => @values; Readonly my @arr => @values; Readonly %has => (key => value, key => value, ...); Readonly my %has => (key => value, key => value, ...); Readonly my $sca; # Implicit undef, readonly value # Alternate form (for Perls earlier than v5.8) Readonly \$sca => $initial_value; Readonly \my $sca => $initial_value; Readonly \@arr => @values; Readonly \my @arr => @values; Readonly \%has => (key => value, key => value, ...); Readonly \my %has => (key => value, key => value, ...);
If you pass a $ref, an @array or a %hash to corresponding functions "::Scalar()", "::Array()" and "::Hash()", then those functions recurse over the data structure, marking everything as readonly. The entire structure is then non-modifiable. This is normally what you want.
If you want only the top level to be readonly, use the alternate (and poorly named) "::Scalar1()", "::Array1()", and "::Hash1()" functions.
Plain "Readonly()" creates what the original author calls a ``shallow'' readonly variable, which is great if you don't plan to use it on anything but only one dimensional scalar values.
"Readonly::Scalar()" makes the variable 'deeply' readonly, so the following snippet kills over as you expect:
use Readonly; Readonly::Scalar my $ref => { 1 => 'a' }; $ref->{1} = 'b'; $ref->{2} = 'b';
While the following snippet does not make your structure 'deeply' readonly:
use Readonly; Readonly my $ref => { 1 => 'a' }; $ref->{1} = 'b'; $ref->{2} = 'b';
use constant CARRAY => (2, 3, 5, 7, 11, 13); $a_prime = CARRAY[2]; # wrong! $a_prime = (CARRAY)[2]; # right -- MUST use parentheses
For example:
use constant SOME_KEY => 'key'; %hash = (key => 'value', other_key => 'other_value'); $some_value = $hash{SOME_KEY}; # wrong! $some_value = $hash{+SOME_KEY}; # right
(who thinks to use a unary plus when using a hash to scalarize the key?)
use constant PI => 3.14159; ... use constant PI => 2.71828;
(this does generate a warning, however, if you have warnings enabled).
*a = \'value';
This works fine, but it only works for global variables (``my'' variables have no symbol table entry). Also, the following similar constructs do not work:
*a = [1, 2, 3]; # Does NOT create a read-only array *a = { a => 'A'}; # Does NOT create a read-only hash
Readonly.pm also works well with complex data structures, allowing you to tag the whole structure as nonmodifiable, or just the top level.
Also, Readonly variables may not be reassigned. The following code will die:
Readonly::Scalar $pi => 3.14159; ... Readonly::Scalar $pi => 2.71828;
However, there is relief. There is a companion module available, Readonly::XS. You won't need this if you're using Perl 5.8.x or higher.
I repeat, you do not need Readonly::XS if your environment has perl 5.8.x or higher. Please see section entitled Internals for more.
A value must be supplied. If you want the variable to have "undef" as its value, you must specify "undef".
If $value is a reference to a scalar, array, or hash, then this function will mark the scalar, array, or hash it points to as being Readonly as well, and it will recursively traverse the structure, marking the whole thing as Readonly. Usually, this is what you want. However, if you want only the $value marked as Readonly, use "Scalar1".
If $var is already a Readonly variable, the program will die with an error about reassigning Readonly variables.
If any of the values passed is a reference to a scalar, array, or hash, then this function will mark the scalar, array, or hash it points to as being Readonly as well, and it will recursively traverse the structure, marking the whole thing as Readonly. Usually, this is what you want. However, if you want only the hash %@arr itself marked as Readonly, use "Array1".
If @arr is already a Readonly variable, the program will die with an error about reassigning Readonly variables.
A list of keys and values may be specified (with parentheses in the synopsis above), or a hash reference may be specified (curly braces in the synopsis above). If a list is specified, it must have an even number of elements, or the function will die.
If any of the values is a reference to a scalar, array, or hash, then this function will mark the scalar, array, or hash it points to as being Readonly as well, and it will recursively traverse the structure, marking the whole thing as Readonly. Usually, this is what you want. However, if you want only the hash %h itself marked as Readonly, use "Hash1".
If %h is already a Readonly variable, the program will die with an error about reassigning Readonly variables.
It has the disadvantage of having a slightly different syntax for versions of Perl prior to 5.8. For earlier versions, you must supply a backslash, because it requires a reference as the first parameter.
Readonly \$var => $value; Readonly \@arr => (value, value, ...); Readonly \%h => (key => value, ...); Readonly \%h => {key => value, ...};
You may or may not consider this ugly.
Note that you can create implicit undefined variables with this function like so "Readonly my $var;" while a verbose undefined value must be passed to the standard "Scalar", "Array", and "Hash" functions.
Readonly::Array1 @shal => (1, 2, {perl=>'Rules', java=>'Bites'}, 4, 5); Readonly::Array @deep => (1, 2, {perl=>'Rules', java=>'Bites'}, 4, 5); $shal[1] = 7; # error $shal[2]{APL}='Weird'; # Allowed! since the hash isn't Readonly $deep[1] = 7; # error $deep[2]{APL}='Weird'; # error, since the hash is Readonly
Readonly::Scalar my $scalar => {qw[this that]}; # $scalar->{'eh'} = 'foo'; # Modification of a read-only value attempted my $scalar_clone = Readonly::Clone $scalar; $scalar_clone->{'eh'} = 'foo'; # $scalar_clone is now {this => 'that', eh => 'foo'};
The new variable ($scalar_clone) is a mutable clone of the original $scalar.
Readonly::Scalar $a => "A string value";
The value need not be a compile-time constant:
Readonly::Scalar $a => $computed_value;
Readonly::Array @a => (1, 2, 3, 4);
The parentheses are optional:
Readonly::Array @a => 1, 2, 3, 4;
You can use Perl's built-in array quoting syntax:
Readonly::Array @a => qw/1 2 3 4/;
You can initialize a read-only array from a variable one:
Readonly::Array @a => @computed_values;
A read-only array can be empty, too:
Readonly::Array @a => (); Readonly::Array @a; # equivalent
Readonly::Hash %a => (key1 => 'value1', key2 => 'value2');
A read-only hash can be initialized from a variable one:
Readonly::Hash %a => %computed_values;
A read-only hash can be empty:
Readonly::Hash %a => (); Readonly::Hash %a; # equivalent
If you pass an odd number of values, the program will die:
Readonly::Hash %a => (key1 => 'value1', "value2"); # This dies with "May not store an odd number of values in a hash"
In the past, Readonly's ``magic'' was performed by "tie()"-ing variables to the "Readonly::Scalar", "Readonly::Array", and "Readonly::Hash" packages (not to be confused with the functions of the same names) and acting on "WRITE", "READ", et. al. While this worked well, it was slow. Very slow. Like 20-30 times slower than accessing variables directly or using one of the other const-related modules that have cropped up since Readonly was released in 2003.
To 'fix' this, Readonly::XS was written. If installed, Readonly::XS used the internal methods "SvREADONLY" and "SvREADONLY_on" to lock simple scalars. On the surface, everything was peachy but things weren't the same behind the scenes. In edge cases, code performed very differently if Readonly::XS was installed and because it wasn't a required dependency in most code, it made downstream bugs very hard to track.
In the years since Readonly::XS was released, the then private internal methods have been exposed and can be used in pure perl. Similar modules were written to take advantage of this and a patch to Readonly was created. We no longer need to build and install another module to make Readonly useful on modern builds of perl.
There are no non-core requirements.
Thanks to Ernest Lergon for the idea (and initial code) for deeply-Readonly data structures (21 May 2002).
Thanks to Damian Conway for the idea (and code) for making the Readonly function work a lot smoother under perl 5.8+.
CPAN ID: SANKO
Original author: Eric J. Roode, roode@cpan.org
Copyright (c) 2001-2004 by Eric J. Roode. All Rights Reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.