NAME

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

VERSION

This documentation describes version 0.04 of Constant.pm, Mar 7, 2002. Re-versioned to 0.05 during deprecation.

Please note that this module is deprecated as of January 2003. You should look into the Readonly module, which is a newer incarnation of this module, more stable and with more features. Constant still works, but you are encouraged to migrate to Readonly.

SYNOPSIS

use Constant;

# Constant scalar
Constant::Scalar     $sca => $initial_value;
Constant::Scalar  my $sca => $initial_value;

# Constant array
Constant::Array      @arr => @values;
Constant::Array   my @arr => @values;

# Constant hash
Constant::Hash       %has => (key => value, key => value, ...);
Constant::Hash    my %has => (key => value, key => value, ...);

# You can use the constant 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 read-only scalar"
push @arr, 'seven';  # "Attempt to modify read-only array"
delete $has{key};    # "Attempt to modify read-only 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. This built-in pragma works only with Perl 5.5 or later, creates only scalars and lists, and creates variables that have no leading $ character, and which cannot be interpolated into strings. Also, it works only at compile time.

• Another popular way to create constant 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 constant array
  *a = { a => 'A'};    # Does NOT create a constant hash

• Constant.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, non-constant Perl variables. And Constant.pm works with Perl version 5.004 or greater.

  However, Constant.pm does impose a performance penalty. This is probably not an issue for most configuration variables. If this is a concern, however, you should use typeglob constants for scalar constants.

EXAMPLES

# SCALARS: 

# A plain old constant value
Constant::Scalar $a => "A string value";

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


# ARRAYS:

# A constant array:
Constant::Array @a => (1, 2, 3, 4);

# The parentheses are optional:
Constant::Array @a => 1, 2, 3, 4;

# You can use Perl's built-in array quoting syntax:
Constant::Array @a => qw/1 2 3 4/;

# You can initialize a constant array from a variable one:
Constant::Array @a => @computed_values;

# A constant array can be empty, too:
Constant::Array @a => ();
Constant::Array @a;        # equivalent


# HASHES

# Typical usage:
Constant::Hash %a => (key1 => 'value1', key2 => 'value2');
# Note: those are parentheses up there, not curly braces.

# A constant hash can be initialized from a variable one:
Constant::Hash %a => %computed_values;

# A constant hash can be empty:
Constant::Hash %a => ();
Constant::Hash %a;        # equivalent

# If you pass an odd number of values, the program will die:
Constant::Hash %a => (key1 => 'value1', key2);
    --> 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

BUGS / LIMITATIONS

Do not use this module under Windows or any other system that uses case-insensitive filenames. Perl on such systems cannot distinguish between "use Constant" and "use constant", because the system cannot distinguish between Constant.pm and constant.pm.

This module was renamed to Readonly in March of 2002, and that is where development has continued. You are strongly encouraged to use Readonly instead of Constant.

REQUIREMENTS

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