/ 
tilefall-1.11
/ readonly

NAME

readonly - Perl pragma to create readonly scalars

SYNOPSIS

##### Compile time

use readonly 
        '$READONLY' => 57,
        '$TOPIC'    => 'computing',
        '$TRUE'     => 1,
        '$FALSE'    => 0,
        '$PI'       => 4 * atan2( 1, 1 ),

        '$ALPHA'    => 1.761,
        '$BETA'     => 2.814,
        '$GAMMA'    => 4.012,
        '$PATH'     => '/usr/local/lib/lout/include',
        '$EXE'      => '/usr/local/bin/lout',
        ;

# Have to use a separate readonly if we refer back.
use readonly '$RC'  => "$EXE/config" ;

##### Run time (possible but not recommended)

use readonly () ; # If no previous pragma calls.

readonly->new( 
    '$BACKGROUND'   => param( 'green' ),
    '$FOREGROUND'   => param( 'white' ),
    '$HIGHLIGHT'    => param( 'yellow' ),
    ) ;

DESCRIPTION

The readonly module can be used either as a compile-time pragma or a run-time class module.

This module creates readonly scalars in the current namespace. The scalars thus created may be used in all contexts where read/write scalars would be used with the exception that you will get an eval trappable run-time error "Modification of a read-only value attempted..." if you try to assign to a readonly scalar.

Of course there is already a pragma, constant, which provides this kind of functionality (and more, since constant also handles arrays, hashes etc). However constants must be used with different syntax in different contexts, whereas readonlys can be used with the same consistent scalar syntax throughout. Also readonlys may be created either at compile-time or at run-time.

String Interpolation

use constant PI    => 4 * atan2 1, 1 ; # Compile time
use readonly '$PI' => 4 * atan2 1, 1 ; # Compile time

We can print readonlys directly:

print "The value of pi is $PI and pi^2 is $PI2\n" ;

But for constants we must do this:

print "The value of pi is ", PI, "\n" ;

or this:

print "The value of pi is @{[PI]}\n" ;

Hash Keys

use constant TOPIC    => 'geology' ;
use readonly '$TOPIC' => 'geology' ;

my %topic = (
        geology   => 5,
        computing => 7,
        biology   => 9,
    ) ;

Using a readonly scalar we can simply write:

my $value = $topic{$TOPIC}

However, if we try to access one of the hash elements using the constant:

my $value = $topic{TOPIC} ;

we get an unwelcome surprise: $value is set to undef because perl will take TOPIC to be the literal string 'TOPIC' and since no hash element has that key the result is undef. Thus in this situation we would have to write:

my $value = $topic{TOPIC()} ;

or perhaps:

my $value = $topic{&TOPIC} ;

Compile-time vs Run-time

Creating readonly scalars at compile-time is the preferred approach. Sometimes however we only know what the readonly value will be after performing some of our execution; in such cases the run-time approach is possible. Be aware however that you may not be able to create a readonly scalar at run-time and that those you do create will almost certainly need to be used with their full package names.

Error Messages

Modification of a read-only value attempted

Eval trappable fatal error. The reason for this pragma's existence. This will occur if you try to assign to a readonly scalar, e.g. $PI = 3, or $PI++.

Using readonly scalar `$SCALAR' instead of bare `SCALAR'

Warning. The scalar name should begin with a $. (This is to allow the possibility of supporting readonly arrays and hashes in the future - if I can ever figure out how - suggestions welcome.)

Cannot change readonly scalar `$SCALAR'

Warning. This is why we use this pragma in the first place. If you write use readonly '$SOMESCALAR' => 42 ; somewhere and elsewhere write use readonly '$SOMESCALAR' => 'benji' ; you will get this warning.

usage: use readonly '$SCALAR' = value ; # Don't forget to single quote the scalar>

Fatal syntax error. The name of the scalar must be in single quotes, and you must separate it from the value with either => or a comma.

Readonly scalar `$SCALAR' has no value

Fatal error. Every scalar must be set to a defined scalar value.

Cannot make `$SCALAR' readonly

Fatal error. The name being used contains "illegal" characters or begins with two leading underscores or is in this list:

BEGIN INIT CHECK END DESTROY AUTOLOAD STDIN STDOUT STDERR ARGV ARGVOUT ENV INC SIG
Failed to create readonly scalar `$SCALAR'

Warning. This will occur for example if you try to set the value to be 'abc\' whose last character, \ might be problematic.

Global symbol "$SCALAR" requires explicit package name

Fatal error. For reasons I don't understand in some cases when you create a readonly scalar at run-time perl needs you to explicitly use the package name, e.g.

readonly->new( '$XCOORD' => 821, '$YCOORD' => 124 ) ;

If you get this error message then (assuming we're in package main) use:

print "x = $::XCOORD\n" ;
Noop

Warning. Occurs if you write no readonly which has no semantics.

Cannot undefine readonly scalar

Warning. Occurs if you write no readonly '$SCALAR'. Undefining a readonly value would change it and is therefore not permitted.

Do We Need It?

You can achieve the same effect as:

use readonly '$WEB_ADDRESS' => 'www.perlpress.com' ;

by coding:

use vars '$WEB_ADDRESS' ; *WEB_ADDRESS = \'www.perlpress.com' ;

Similarly:

use constant WEB_ADDRESS => 'www.perlpress.com' ;

can be coded as:

sub WEB_ADDRESS() { 'www.perlpress.com' } # No semi-colon.

However, readonly allows us to create many readonly scalars in one go with a compact syntax:

use readonly    # Compile time
        '$HOME' => '/home/summer',
        '$ROOT' => '/root',
        '$PERL' => '/usr/lib/perl',
        ;

BUGS

Only copes with scalars.

In some tests with 5.004 readonly->new lead to spurious warnings.

Sometimes with 5.004 when using eval exception handling you get "Use of uninitialized value at..." errors; the cure is to write:

eval {
    $@ = undef ;
    # rest as normal

AUTHOR

Mark Summerfield. I can be contacted as <summer@perlpress.com> - please include the word 'readonly' in the subject line.

I copied some ideas from constant.pm.

COPYRIGHT

Copyright (c) Mark Summerfield 2000. All Rights Reserved.

This module may be used/distributed/modified under the same terms as perl itself.