.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Readonly 3pm"
.TH Readonly 3pm "2012-06-11" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Readonly \- Facility for creating read\-only scalars, arrays, hashes.
.SH "VERSION"
.IX Header "VERSION"
This documentation describes version 1.03 of Readonly.pm, April 20, 2004.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& 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, \*(Aqseven\*(Aq;
\& 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    \e$sca => $initial_value;
\& Readonly \emy $sca => $initial_value;
\& Readonly    \e@arr => @values;
\& Readonly \emy @arr => @values;
\& Readonly    \e%has => (key => value, key => value, ...);
\& Readonly \emy %has => (key => value, key => value, ...);
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
If any of the values you pass to \f(CW\*(C`Scalar\*(C'\fR, \f(CW\*(C`Array\*(C'\fR, or \f(CW\*(C`Hash\*(C'\fR 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 \f(CW\*(C`Scalar1\*(C'\fR, \f(CW\*(C`Array1\*(C'\fR and \f(CW\*(C`Hash1\*(C'\fR
functions.
.PP
Please note that most users of Readonly will also want to install a
companion module Readonly::XS.  See the \*(L"\s-1CONS\s0\*(R" section below for more
details.
.ie n .SH "COMPARISON WITH ""use constant"""
.el .SH "COMPARISON WITH ``use constant''"
.IX Header "COMPARISON WITH use constant"
Perl provides a facility for creating constant values, via the \*(L"use
constant\*(R" pragma.  There are several problems with this pragma.
.IP "\(bu" 2
The constants created have no leading $ or @ character.
.IP "\(bu" 2
These constants cannot be interpolated into strings.
.IP "\(bu" 2
Syntax can get dicey sometimes.  For example:
.Sp
.Vb 3
\& use constant CARRAY => (2, 3, 5, 7, 11, 13);
\& $a_prime = CARRAY[2];        # wrong!
\& $a_prime = (CARRAY)[2];      # right \-\- MUST use parentheses
.Ve
.IP "\(bu" 2
You have to be very careful in places where barewords are allowed.
For example:
.Sp
.Vb 4
\& use constant SOME_KEY => \*(Aqkey\*(Aq;
\& %hash = (key => \*(Aqvalue\*(Aq, other_key => \*(Aqother_value\*(Aq);
\& $some_value = $hash{SOME_KEY};        # wrong!
\& $some_value = $hash{+SOME_KEY};       # right
.Ve
.Sp
(who thinks to use a unary plus when using a hash?)
.IP "\(bu" 2
\&\f(CW\*(C`use constant\*(C'\fR works for scalars and arrays, not hashes.
.IP "\(bu" 2
These constants are global ot the package in which they're declared;
cannot be lexically scoped.
.IP "\(bu" 2
Works only at compile time.
.IP "\(bu" 2
Can be overridden:
.Sp
.Vb 3
\& use constant PI => 3.14159;
\& ...
\& use constant PI => 2.71828;
.Ve
.Sp
(this does generate a warning, however, if you have warnings enabled).
.IP "\(bu" 2
It is very difficult to make and use deep structures (complex data
structures) with \f(CW\*(C`use constant\*(C'\fR.
.SH "COMPARISON WITH TYPEGLOB CONSTANTS"
.IX Header "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:
.PP
.Vb 1
\& *a = \e\*(Aqvalue\*(Aq;
.Ve
.PP
This works fine, but it only works for global variables (\*(L"my\*(R"
variables have no symbol table entry).  Also, the following similar
constructs do \fBnot\fR work:
.PP
.Vb 2
\& *a = [1, 2, 3];      # Does NOT create a read\-only array
\& *a = { a => \*(AqA\*(Aq};    # Does NOT create a read\-only hash
.Ve
.SH "PROS"
.IX Header "PROS"
Readonly.pm, on the other hand, will work with global variables and
with lexical (\*(L"my\*(R") 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.
.PP
Readonly.pm also works well with complex data structures, allowing you
to tag the whole structure as nonmodifiable, or just the top level.
.PP
Also, Readonly variables may not be reassigned.  The following code
will die:
.PP
.Vb 3
\& Readonly::Scalar $pi => 3.14159;
\& ...
\& Readonly::Scalar $pi => 2.71828;
.Ve
.SH "CONS"
.IX Header "CONS"
Readonly.pm does impose a performance penalty.  It's pretty slow.  How
slow?  Run the \f(CW\*(C`benchmark.pl\*(C'\fR script that comes with Readonly.  On my
test system, \*(L"use constant\*(R", typeglob constants, and regular
read/write Perl variables were all about the same speed, and
Readonly.pm constants were about 1/20 the speed.
.PP
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.
.PP
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:
.PP
.Vb 5
\& # For testing:
\& Readonly::Scalar  $Foo_Directory => \*(Aq/usr/local/foo\*(Aq;
\& Readonly::Scalar  $Bar_Directory => \*(Aq/usr/local/bar\*(Aq;
\& # $Foo_Directory = \*(Aq/usr/local/foo\*(Aq;
\& # $Bar_Directory = \*(Aq/usr/local/bar\*(Aq;
\&
\& # For production:
\& # Readonly::Scalar  $Foo_Directory => \*(Aq/usr/local/foo\*(Aq;
\& # Readonly::Scalar  $Bar_Directory => \*(Aq/usr/local/bar\*(Aq;
\& $Foo_Directory = \*(Aq/usr/local/foo\*(Aq;
\& $Bar_Directory = \*(Aq/usr/local/bar\*(Aq;
.Ve
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.ie n .IP "Readonly::Scalar $var => $value;" 4
.el .IP "Readonly::Scalar \f(CW$var\fR => \f(CW$value\fR;" 4
.IX Item "Readonly::Scalar $var => $value;"
Creates a nonmodifiable scalar, \f(CW$var\fR, and assigns a value of
\&\f(CW$value\fR to it.  Thereafter, its value may not be changed.  Any
attempt to modify the value will cause your program to die.
.Sp
A value \fImust\fR be supplied.  If you want the variable to have
\&\f(CW\*(C`undef\*(C'\fR as its value, you must specify \f(CW\*(C`undef\*(C'\fR.
.Sp
If \f(CW$value\fR 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 \f(CW$value\fR marked as Readonly, use
\&\f(CW\*(C`Scalar1\*(C'\fR.
.Sp
If \f(CW$var\fR is already a Readonly variable, the program will die with
an error about reassigning Readonly variables.
.ie n .IP "Readonly::Array @arr => (value, value, ...);" 4
.el .IP "Readonly::Array \f(CW@arr\fR => (value, value, ...);" 4
.IX Item "Readonly::Array @arr => (value, value, ...);"
Creates a nonmodifiable array, \f(CW@arr\fR, 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.
.Sp
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 \f(CW%@arr\fR itself marked as Readonly,
use \f(CW\*(C`Array1\*(C'\fR.
.Sp
If \f(CW@arr\fR is already a Readonly variable, the program will die with
an error about reassigning Readonly variables.
.ie n .IP "Readonly::Hash %h => (key => value, key => value, ...);" 4
.el .IP "Readonly::Hash \f(CW%h\fR => (key => value, key => value, ...);" 4
.IX Item "Readonly::Hash %h => (key => value, key => value, ...);"
.PD 0
.ie n .IP "Readonly::Hash %h => {key => value, key => value, ...};" 4
.el .IP "Readonly::Hash \f(CW%h\fR => {key => value, key => value, ...};" 4
.IX Item "Readonly::Hash %h => {key => value, key => value, ...};"
.PD
Creates a nonmodifiable hash, \f(CW%h\fR, 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.
.Sp
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.
.Sp
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 \f(CW%h\fR itself marked as
Readonly, use \f(CW\*(C`Hash1\*(C'\fR.
.Sp
If \f(CW%h\fR is already a Readonly variable, the program will die with
an error about reassigning Readonly variables.
.ie n .IP "Readonly $var => $value;" 4
.el .IP "Readonly \f(CW$var\fR => \f(CW$value\fR;" 4
.IX Item "Readonly $var => $value;"
.PD 0
.ie n .IP "Readonly @arr => (value, value, ...);" 4
.el .IP "Readonly \f(CW@arr\fR => (value, value, ...);" 4
.IX Item "Readonly @arr => (value, value, ...);"
.ie n .IP "Readonly %h => (key => value, ...);" 4
.el .IP "Readonly \f(CW%h\fR => (key => value, ...);" 4
.IX Item "Readonly %h => (key => value, ...);"
.ie n .IP "Readonly %h => {key => value, ...};" 4
.el .IP "Readonly \f(CW%h\fR => {key => value, ...};" 4
.IX Item "Readonly %h => {key => value, ...};"
.PD
The \f(CW\*(C`Readonly\*(C'\fR function is an alternate to the \f(CW\*(C`Scalar\*(C'\fR, \f(CW\*(C`Array\*(C'\fR,
and \f(CW\*(C`Hash\*(C'\fR 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.
.Sp
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.
.Sp
.Vb 4
\&  Readonly \e$var => $value;
\&  Readonly \e@arr => (value, value, ...);
\&  Readonly \e%h => (key => value, ...);
\&  Readonly \e%h => {key => value, ...};
.Ve
.Sp
You may or may not consider this ugly.
.ie n .IP "Readonly::Scalar1 $var => $value;" 4
.el .IP "Readonly::Scalar1 \f(CW$var\fR => \f(CW$value\fR;" 4
.IX Item "Readonly::Scalar1 $var => $value;"
.PD 0
.ie n .IP "Readonly::Array1 @arr => (value, value, ...);" 4
.el .IP "Readonly::Array1 \f(CW@arr\fR => (value, value, ...);" 4
.IX Item "Readonly::Array1 @arr => (value, value, ...);"
.ie n .IP "Readonly::Hash1 %h => (key => value, key => value, ...);" 4
.el .IP "Readonly::Hash1 \f(CW%h\fR => (key => value, key => value, ...);" 4
.IX Item "Readonly::Hash1 %h => (key => value, key => value, ...);"
.ie n .IP "Readonly::Hash1 %h => {key => value, key => value, ...};" 4
.el .IP "Readonly::Hash1 \f(CW%h\fR => {key => value, key => value, ...};" 4
.IX Item "Readonly::Hash1 %h => {key => value, key => value, ...};"
.PD
These alternate functions create shallow Readonly variables, instead
of deep ones.  For example:
.Sp
.Vb 2
\& Readonly::Array1 @shal => (1, 2, {perl=>\*(AqRules\*(Aq, java=>\*(AqBites\*(Aq}, 4, 5);
\& Readonly::Array  @deep => (1, 2, {perl=>\*(AqRules\*(Aq, java=>\*(AqBites\*(Aq}, 4, 5);
\&
\& $shal[1] = 7;           # error
\& $shal[2]{APL}=\*(AqWeird\*(Aq;  # Allowed! since the hash isn\*(Aqt Readonly
\& $deep[1] = 7;           # error
\& $deep[2]{APL}=\*(AqWeird\*(Aq;  # error, since the hash is Readonly
.Ve
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.Vb 1
\& # 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\*(Aqs 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 => \*(Aqvalue1\*(Aq, key2 => \*(Aqvalue2\*(Aq);
\&
\& # 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 => \*(Aqvalue1\*(Aq, "value2");
\&     \-\-> dies with "May not store an odd number of values in a hash"
.Ve
.SH "EXPORTS"
.IX Header "EXPORTS"
By default, this module exports the following symbol into the calling
program's namespace:
.PP
.Vb 1
\& Readonly
.Ve
.PP
The following symbols are available for import into your program, if
you like:
.PP
.Vb 3
\& Scalar  Scalar1
\& Array   Array1
\& Hash    Hash1
.Ve
.SH "REQUIREMENTS"
.IX Header "REQUIREMENTS"
.Vb 3
\& Perl 5.000
\& Carp.pm (included with Perl)
\& Exporter.pm (included with Perl)
\&
\& Readonly::XS is recommended but not required.
.Ve
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
Thanks to Slaven Rezic for the idea of one common function
(Readonly) for all three types of variables (13 April 2002).
.PP
Thanks to Ernest Lergon for the idea (and initial code) for
deeply-Readonly data structures (21 May 2002).
.PP
Thanks to Damian Conway for the idea (and code) for making the
Readonly function work a lot smoother under perl 5.8+.
.SH "AUTHOR / COPYRIGHT"
.IX Header "AUTHOR / COPYRIGHT"
Eric J. Roode, roode@cpan.org
.PP
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.
.PP
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.
.PP
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.