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