This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Quote string argument in example -- necessary if using strict subs
[perl5.git] / lib / Tie / Scalar.pm
CommitLineData
64d0c973
RR
1package Tie::Scalar;
2
3=head1 NAME
4
5Tie::Scalar, Tie::StdScalar - base class definitions for tied scalars
6
7=head1 SYNOPSIS
8
9 package NewScalar;
10 require Tie::Scalar;
11
12 @ISA = (Tie::Scalar);
13
14 sub FETCH { ... } # Provide a needed method
15 sub TIESCALAR { ... } # Overrides inherited method
16
17
18 package NewStdScalar;
19 require Tie::Scalar;
20
21 @ISA = (Tie::StdScalar);
22
23 # All methods provided by default, so define only what needs be overridden
24 sub FETCH { ... }
25
26
27 package main;
28
c954a603
PP
29 tie $new_scalar, 'NewScalar';
30 tie $new_std_scalar, 'NewStdScalar';
64d0c973
RR
31
32=head1 DESCRIPTION
33
34This module provides some skeletal methods for scalar-tying classes. See
35L<perltie> for a list of the functions required in tying a scalar to a
36package. The basic B<Tie::Scalar> package provides a C<new> method, as well
37as methods C<TIESCALAR>, C<FETCH> and C<STORE>. The B<Tie::StdScalar>
38package provides all the methods specified in L<perltie>. It inherits from
39B<Tie::Scalar> and causes scalars tied to it to behave exactly like the
40built-in scalars, allowing for selective overloading of methods. The C<new>
41method is provided as a means of grandfathering, for classes that forget to
42provide their own C<TIESCALAR> method.
43
44For developers wishing to write their own tied-scalar classes, the methods
45are summarized below. The L<perltie> section not only documents these, but
46has sample code as well:
47
48=over
49
50=item TIESCALAR classname, LIST
51
52The method invoked by the command C<tie $scalar, classname>. Associates a new
53scalar instance with the specified class. C<LIST> would represent additional
54arguments (along the lines of L<AnyDBM_File> and compatriots) needed to
55complete the association.
56
57=item FETCH this
58
59Retrieve the value of the tied scalar referenced by I<this>.
60
61=item STORE this, value
62
63Store data I<value> in the tied scalar referenced by I<this>.
64
65=item DESTROY this
66
67Free the storage associated with the tied scalar referenced by I<this>.
68This is rarely needed, as Perl manages its memory quite well. But the
69option exists, should a class wish to perform specific actions upon the
70destruction of an instance.
71
72=back
73
74=head1 MORE INFORMATION
75
76The L<perltie> section uses a good example of tying scalars by associating
77process IDs with priority.
78
79=cut
80
81use Carp;
82
83sub new {
84 my $pkg = shift;
85 $pkg->TIESCALAR(@_);
86}
87
88# "Grandfather" the new, a la Tie::Hash
89
90sub TIESCALAR {
91 my $pkg = shift;
92 if (defined &{"{$pkg}::new"}) {
93 carp "WARNING: calling ${pkg}->new since ${pkg}->TIESCALAR is missing"
94 if $^W;
95 $pkg->new(@_);
96 }
97 else {
98 croak "$pkg doesn't define a TIESCALAR method";
99 }
100}
101
102sub FETCH {
103 my $pkg = ref $_[0];
104 croak "$pkg doesn't define a FETCH method";
105}
106
107sub STORE {
108 my $pkg = ref $_[0];
109 croak "$pkg doesn't define a STORE method";
110}
111
112#
113# The Tie::StdScalar package provides scalars that behave exactly like
114# Perl's built-in scalars. Good base to inherit from, if you're only going to
115# tweak a small bit.
116#
117package Tie::StdScalar;
118@ISA = (Tie::Scalar);
119
120sub TIESCALAR {
121 my $class = shift;
122 my $instance = shift || undef;
123 return bless \$instance => $class;
124}
125
126sub FETCH {
127 return ${$_[0]};
128}
129
130sub STORE {
131 ${$_[0]} = $_[1];
132}
133
134sub DESTROY {
135 undef ${$_[0]};
136}
137
1381;