NAME

Tie::Static - create static lexicals

SYNOPSIS

# The tie-based approach
use Tie::Static;
sub foo {
  tie (my $static_scalar, 'Tie::Static');
  tie (my @static_array, 'Tie::Static');
  tie (my %static_hash, 'Tie::Static');
  # do whatever you want
}

# The function call approach
use Tie::Static qw(static);
sub bar {
  static \ my ($scalar, @array, %hash);
  # etc
}

DESCRIPTION

This module makes it easy to produce static variables.

A static variable is a variable whose value will remain constant from invocation to invocation. The usual way to produce this is to create an enclosing scope which contains a lexically scoped variable. For instance the first example could be written as:

{
  my $static_scalar;
  my @static_array;
  my %static_hash;
  
  sub foo {
    # Do whatever you want
  }
}

But while this works, many people find it cumbersome to have to produce new scopes manually just to get a static variables. This module provides an alternate solution by providing a way to make lexical variables be what they used to be.

There are two interfaces. The low-level interface is to tie your variable directly. But most of the time you will want to use the exportable static function.

If you tie and do not pass any arguments, it will use the feedback from caller() to decide whether to tie you to a fresh variable, or whether to hand you back an old one. If you pass the tie arguments, it will join them with "|" and use that key to decide what object to hand you back. This allows you to create static variables which are shared between functions in any way you want.

What static does is take a list of references to variables, tie them, and then report how many times they were previously tied. If the variables had not been tied before, static will initialize the tied variables to the values they had before being tied. Therefore if you want to have default values for your static variables you can either initialize them before calling static, or do the initialization if static returns a false value. Here are examples:

# Pre-initializing a static.
my @array = 1..10;
my %hash = (Hello => "World", Greetings => "Earthlings");
static \(@array, %hash);

# Testing the return of static
my $handle;
unless (static(\$handle)) {
  $handle = complex_initialization();
}

# Initializing while calling, only works with scalars
static \(my $foo = "Hello", my $bar = "World");

LIMITATIONS AND NOTES

This module relies on the output of [caller] to decide which value to give back. Specifically, it makes its decisions based on Perl's idea of the current package, filename, and line-number. Normally this is correct. But sometimes it is wrong. And occasionally it is very wrong. It is correct if there is only one call on any given line, and you want that call to always give you back the same values. It is wrong if you put 2 separate calls to static or try to tie the same data-type twice on one line. It is very wrong if you want to play with closures. It has no way to distinguish them.

This only allows static scalars, arrays, and hashes.

If you want to overload the implementation of a static, please note that scalars, arrays, and hashes are not tied to the package Tie::Static. Instead they are tied to the private packages Tie::Static::Scalar, Tie::Static::Array, and Tie::Static::Hash.

CREDITS

Thanks go to several people at http://www.perlmonks.org for discussions on how to implement this and what the API should look like. In particular "MeowChow" for analyzing the gotchas that people need to be aware of. Jeff "japhy" Pinyan (japhy@pobox.com) for discussion on implementations and the idea of static. And "HyperZonk" and Charles "Wog" Reiss for general discussion. The idea of initializing scalars as you call static is Wog's.

And a particular note should be made of all of the people on p5p, PerlMonks, and elsewhere who saw the behaviour of

my $foo if 0;

as a feature rather than a bug. Without you I would not have been inspired to write an (intentional) implementation of statics for Perl.

TODO

Add tests for the improvements since version 0.01.

ACKNOWLEDGEMENTS

My thanks for useful discussions on the API and features with posters at perlmonks, particularly including MeowChow and japhy. See http://www.perlmonks.org/index.pl?node_id=96832.

AUTHOR AND COPYRIGHT

Ben Tilly (btilly@gmail.com)

Copyright 2001-2003. This may be modified and distributed on the same terms as Perl.