NAME

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

VERSION

This documentation describes version 0.05 of Readonly.pm, March 15, 2002.

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;            # "Attempt to modify readonly scalar"
push @arr, 'seven';  # "Attempt to modify readonly array"
delete $has{key};    # "Attempt to modify readonly hash"

DESCRIPTION

This is a facility for creating non-modifiable variables. This is useful for configuration files, headers, etc.

COMPARISON WITH "use constant" OR TYPEGLOB CONSTANTS

• Perl provides a facility for creating constant scalars, via the "use constant" pragma. That built-in pragma creates only scalars and lists; it creates variables that have no leading $ character and which cannot be interpolated into strings. It works only at compile time. You cannot take references to these 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

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

  However, Readonly.pm does impose a performance penalty. This is probably not an issue for most configuration variables. But benchmark your program if it might be.

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.

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.

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.

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 no symbols into the calling program's namespace. The following symbols are available for import into your program, if you like:

Scalar
Array
Hash

REQUIREMENTS

Perl 5.005
Carp.pm (included with Perl)
Exporter.pm (included with Perl)

AUTHOR / COPYRIGHT

Eric J. Roode, eric@myxa.com

Copyright (c) 2001-2002 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.