This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Document differences between Tie::Scalar and Tie::StdScalar
[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;
c6c73c78 107 if ($pkg->can('new') and $pkg ne __PACKAGE__) {
7e6d00f8 108 warnings::warnif("WARNING: calling ${pkg}->new since ${pkg}->TIESCALAR is missing");
64d0c973
RR
109 $pkg->new(@_);
110 }
111 else {
112 croak "$pkg doesn't define a TIESCALAR method";
113 }
114}
115
116sub FETCH {
117 my $pkg = ref $_[0];
118 croak "$pkg doesn't define a FETCH method";
119}
120
121sub STORE {
122 my $pkg = ref $_[0];
123 croak "$pkg doesn't define a STORE method";
124}
125
126#
127# The Tie::StdScalar package provides scalars that behave exactly like
128# Perl's built-in scalars. Good base to inherit from, if you're only going to
129# tweak a small bit.
130#
131package Tie::StdScalar;
abc0156b 132@ISA = qw(Tie::Scalar);
64d0c973
RR
133
134sub TIESCALAR {
135 my $class = shift;
136 my $instance = shift || undef;
137 return bless \$instance => $class;
138}
139
140sub FETCH {
141 return ${$_[0]};
142}
143
144sub STORE {
145 ${$_[0]} = $_[1];
146}
147
148sub DESTROY {
149 undef ${$_[0]};
150}
151
1521;