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