<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">package Tie::Scalar;

our $VERSION = '1.06';

=head1 NAME

Tie::Scalar, Tie::StdScalar - base class definitions for tied scalars

=head1 SYNOPSIS

    package NewScalar;
    require Tie::Scalar;

    @ISA = qw(Tie::Scalar);

    sub FETCH { ... }		# Provide a needed method
    sub TIESCALAR { ... }	# Overrides inherited method


    package NewStdScalar;
    require Tie::Scalar;

    @ISA = qw(Tie::StdScalar);

    # All methods provided by default, so define
    # only what needs be overridden
    sub FETCH { ... }


    package main;

    tie $new_scalar, 'NewScalar';
    tie $new_std_scalar, 'NewStdScalar';

=head1 DESCRIPTION

This module provides some skeletal methods for scalar-tying classes. See
L&lt;perltie&gt; for a list of the functions required in tying a scalar to a
package. The basic B&lt;Tie::Scalar&gt; package provides a C&lt;new&gt; method, as well
as methods C&lt;TIESCALAR&gt;, C&lt;FETCH&gt; and C&lt;STORE&gt;. The B&lt;Tie::StdScalar&gt;
package provides all the methods specified in  L&lt;perltie&gt;. It inherits from
B&lt;Tie::Scalar&gt; and causes scalars tied to it to behave exactly like the
built-in scalars, allowing for selective overloading of methods. The C&lt;new&gt;
method is provided as a means of legacy support for classes that forget to
provide their own C&lt;TIESCALAR&gt; method.

For developers wishing to write their own tied-scalar classes, the methods
are summarized below. The L&lt;perltie&gt; section not only documents these, but
has sample code as well:

=over 4

=item TIESCALAR classname, LIST

The method invoked by the command C&lt;tie $scalar, classname&gt;. Associates a new
scalar instance with the specified class. C&lt;LIST&gt; would represent additional
arguments (along the lines of L&lt;AnyDBM_File&gt; and compatriots) needed to
complete the association.

=item FETCH this

Retrieve the value of the tied scalar referenced by I&lt;this&gt;.

=item STORE this, value

Store data I&lt;value&gt; in the tied scalar referenced by I&lt;this&gt;.

=item DESTROY this

Free the storage associated with the tied scalar referenced by I&lt;this&gt;.
This is rarely needed, as Perl manages its memory quite well. But the
option exists, should a class wish to perform specific actions upon the
destruction of an instance.

=back

=head2 Tie::Scalar vs Tie::StdScalar

C&lt;&lt; Tie::Scalar &gt;&gt; provides all the necessary methods, but one should realize
they do not do anything useful. Calling C&lt;&lt; Tie::Scalar::FETCH &gt;&gt; or 
C&lt;&lt; Tie::Scalar::STORE &gt;&gt; results in a (trappable) croak. And if you inherit
from C&lt;&lt; Tie::Scalar &gt;&gt;, you I&lt;must&gt; provide either a C&lt;&lt; new &gt;&gt; or a
C&lt;&lt; TIESCALAR &gt;&gt; method. 

If you are looking for a class that does everything for you that you don't
define yourself, use the C&lt;&lt; Tie::StdScalar &gt;&gt; class, not the
C&lt;&lt; Tie::Scalar &gt;&gt; one.

=head1 MORE INFORMATION

The L&lt;perltie&gt; section uses a good example of tying scalars by associating
process IDs with priority.

=cut

use Carp;
use warnings::register;

sub new {
    my $pkg = shift;
    $pkg-&gt;TIESCALAR(@_);
}

# Legacy support for new(), a la Tie::Hash

sub TIESCALAR {
    my $pkg = shift;
    my $pkg_new = $pkg -&gt; can ('new');

    if ($pkg_new and $pkg ne __PACKAGE__) {
        my $my_new = __PACKAGE__ -&gt; can ('new');
        if ($pkg_new == $my_new) {  
            #
            # Prevent recursion
            #
            croak "$pkg must define either a TIESCALAR() or a new() method";
        }

	warnings::warnif ("WARNING: calling ${pkg}-&gt;new since " .
                          "${pkg}-&gt;TIESCALAR is missing");
	$pkg -&gt; new (@_);
    }
    else {
	croak "$pkg doesn't define a TIESCALAR method";
    }
}

sub FETCH {
    my $pkg = ref $_[0];
    croak "$pkg doesn't define a FETCH method";
}

sub STORE {
    my $pkg = ref $_[0];
    croak "$pkg doesn't define a STORE method";
}

#
# The Tie::StdScalar package provides scalars that behave exactly like
# Perl's built-in scalars. Good base to inherit from, if you're only going to
# tweak a small bit.
#
package Tie::StdScalar;
@ISA = qw(Tie::Scalar);

sub TIESCALAR {
    my $class = shift;
    my $instance = @_ ? shift : undef;
    return bless \$instance =&gt; $class;
}

sub FETCH {
    return ${$_[0]};
}

sub STORE {
    ${$_[0]} = $_[1];
}

sub DESTROY {
    undef ${$_[0]};
}

1;
</pre></body></html>