Unix/Linux Go Back    


CentOS 7.0 - man page for readonly (centos section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


Readonly(3)		       User Contributed Perl Documentation		      Readonly(3)

- -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1

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

VERSION
       This documentation describes version 1.03 of Readonly.pm, April 20, 2004.

SYNOPSIS
	use Readonly;

	# Read-only scalar
	Readonly::Scalar     $sca => $initial_value;
	Readonly::Scalar  my $sca => $initial_value;

	# Read-only array
	Readonly::Array      @arr => @values;
	Readonly::Array   my @arr => @values;

	# 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, ...);
	# 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, ...);

DESCRIPTION
       This is a facility for creating non-modifiable variables.  This is useful for
       configuration files, headers, etc.  It can also be useful as a development and debugging
       tool, for catching updates to variables that should not be changed.

       If any of the values you pass to "Scalar", "Array", or "Hash" are references, then those
       functions recurse over the data structures, marking everything as Readonly.  Usually, this
       is what you want: the entire structure nonmodifiable.  If you want only the top level to
       be Readonly, use the alternate "Scalar1", "Array1" and "Hash1" functions.

       Please note that most users of Readonly will also want to install a companion module
       Readonly::XS.  See the "CONS" section below for more details.

COMPARISON WITH ";use constant"
       Perl provides a facility for creating constant values, via the "use constant" pragma.
       There are several problems with this pragma.

       o The constants created have no leading $ or @ character.

       o These constants cannot be interpolated into strings.

       o Syntax can get dicey sometimes.  For example:

	  use constant CARRAY => (2, 3, 5, 7, 11, 13);
	  $a_prime = CARRAY[2];        # wrong!
	  $a_prime = (CARRAY)[2];      # right -- MUST use parentheses

       o You have to be very careful in places where barewords are allowed.  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?)

       o "use constant" works for scalars and arrays, not hashes.

       o These constants are global ot the package in which they're declared; cannot be lexically
	 scoped.

       o Works only at compile time.

       o Can be overridden:

	  use constant PI => 3.14159;
	  ...
	  use constant PI => 2.71828;

	 (this does generate a warning, however, if you have warnings enabled).

       o It is very difficult to make and use deep structures (complex data structures) with "use
	 constant".

COMPARISON WITH TYPEGLOB CONSTANTS
       Another popular way to create read-only scalars is to modify the symbol table entry for
       the variable by using a typeglob:

	*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

PROS
       Readonly.pm, on the other hand, will work with global variables and with lexical ("my")
       variables.  It will create scalars, arrays, or hashes, all of which look and work like
       normal, read-write Perl variables.  You can use them in scalar context, in list context;
       you can take references to them, pass them to functions, anything.

       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;

CONS
       Readonly.pm does impose a performance penalty.  It's pretty slow.  How slow?  Run the
       "benchmark.pl" script that comes with Readonly.	On my test system, "use constant",
       typeglob constants, and regular read/write Perl variables were all about the same speed,
       and Readonly.pm constants were about 1/20 the speed.

       However, there is relief.  There is a companion module available, Readonly::XS.	If it is
       installed on your system, Readonly.pm uses it to make read-only scalars much faster.  With
       Readonly::XS, Readonly scalars are as fast as the other types of variables.  Readonly
       arrays and hashes will still be relatively slow.  But it's likely that most of your
       Readonly variables will be scalars.

       If you can't use Readonly::XS (for example, if you don't have a C compiler, or your perl
       is statically linked and you don't want to re-link it), you have to decide whether the
       benefits of Readonly variables outweigh the speed issue. For most configuration variables
       (and other things that Readonly is likely to be useful for), the speed issue is probably
       not really a big problem.  But benchmark your program if it might be.  If it turns out to
       be a problem, you may still want to use Readonly.pm during development, to catch changes
       to variables that should not be changed, and then remove it for production:

	# For testing:
	Readonly::Scalar  $Foo_Directory => '/usr/local/foo';
	Readonly::Scalar  $Bar_Directory => '/usr/local/bar';
	# $Foo_Directory = '/usr/local/foo';
	# $Bar_Directory = '/usr/local/bar';

	# For production:
	# Readonly::Scalar  $Foo_Directory => '/usr/local/foo';
	# Readonly::Scalar  $Bar_Directory => '/usr/local/bar';
	$Foo_Directory = '/usr/local/foo';
	$Bar_Directory = '/usr/local/bar';

FUNCTIONS
       Readonly::Scalar $var => $value;
	   Creates a nonmodifiable scalar, $var, and assigns a value of $value to it.
	   Thereafter, its value may not be changed.  Any attempt to modify the value will cause
	   your program to die.

	   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.

       Readonly::Array @arr => (value, value, ...);
	   Creates a nonmodifiable array, @arr, and assigns the specified list of values to it.
	   Thereafter, none of its values may be changed; the array may not be lengthened or
	   shortened or spliced.  Any attempt to do so will cause your program to die.

	   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.

       Readonly::Hash %h => (key => value, key => value, ...);
       Readonly::Hash %h => {key => value, key => value, ...};
	   Creates a nonmodifiable hash, %h, and assigns the specified keys and values to it.
	   Thereafter, its keys or values may not be changed.  Any attempt to do so will cause
	   your program to die.

	   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.

       Readonly $var => $value;
       Readonly @arr => (value, value, ...);
       Readonly %h => (key => value, ...);
       Readonly %h => {key => value, ...};
	   The "Readonly" function is an alternate to the "Scalar", "Array", and "Hash"
	   functions.  It has the advantage (if you consider it an advantage) of being one
	   function.  That may make your program look neater, if you're initializing a whole
	   bunch of constants at once.	You may or may not prefer this uniform style.

	   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.

       Readonly::Scalar1 $var => $value;
       Readonly::Array1 @arr => (value, value, ...);
       Readonly::Hash1 %h => (key => value, key => value, ...);
       Readonly::Hash1 %h => {key => value, key => value, ...};
	   These alternate functions create shallow Readonly variables, instead of deep ones.
	   For example:

	    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

EXAMPLES
	# SCALARS:

	# A plain old read-only value
	Readonly::Scalar $a => "A string value";

	# The value need not be a compile-time constant:
	Readonly::Scalar $a => $computed_value;

	# ARRAYS:

	# A read-only array:
	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

	# HASHES

	# Typical usage:
	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");
	    --> dies with "May not store an odd number of values in a hash"

EXPORTS
       By default, this module exports the following symbol into the calling program's namespace:

	Readonly

       The following symbols are available for import into your program, if you like:

	Scalar	Scalar1
	Array	Array1
	Hash	Hash1

REQUIREMENTS
	Perl 5.000
	Carp.pm (included with Perl)
	Exporter.pm (included with Perl)

	Readonly::XS is recommended but not required.

ACKNOWLEDGEMENTS
       Thanks to Slaven Rezic for the idea of one common function (Readonly) for all three types
       of variables (13 April 2002).

       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+.

AUTHOR / COPYRIGHT
       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.

       If you have suggestions for improvement, please drop me a line.	If you make improvements
       to this software, I ask that you please send me a copy of your changes. Thanks.

       Readonly.pm is made from 100% recycled electrons.  No animals were harmed during the
       development and testing of this module.	Not sold in stores!  Readonly::XS sold
       separately.  Void where prohibited.

perl v5.16.3				    2004-04-20				      Readonly(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 11:40 AM.