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
1 package Tie::Scalar;
2
3 =head1 NAME
4
5 Tie::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     
29     tie $new_scalar, 'NewScalar';
30     tie $new_std_scalar, 'NewStdScalar';
31
32 =head1 DESCRIPTION
33
34 This module provides some skeletal methods for scalar-tying classes. See
35 L<perltie> for a list of the functions required in tying a scalar to a
36 package. The basic B<Tie::Scalar> package provides a C<new> method, as well
37 as methods C<TIESCALAR>, C<FETCH> and C<STORE>. The B<Tie::StdScalar>
38 package provides all the methods specified in  L<perltie>. It inherits from
39 B<Tie::Scalar> and causes scalars tied to it to behave exactly like the
40 built-in scalars, allowing for selective overloading of methods. The C<new>
41 method is provided as a means of grandfathering, for classes that forget to
42 provide their own C<TIESCALAR> method.
43
44 For developers wishing to write their own tied-scalar classes, the methods
45 are summarized below. The L<perltie> section not only documents these, but
46 has sample code as well:
47
48 =over
49
50 =item TIESCALAR classname, LIST
51
52 The method invoked by the command C<tie $scalar, classname>. Associates a new
53 scalar instance with the specified class. C<LIST> would represent additional
54 arguments (along the lines of L<AnyDBM_File> and compatriots) needed to
55 complete the association.
56
57 =item FETCH this
58
59 Retrieve the value of the tied scalar referenced by I<this>.
60
61 =item STORE this, value
62
63 Store data I<value> in the tied scalar referenced by I<this>.
64
65 =item DESTROY this
66
67 Free the storage associated with the tied scalar referenced by I<this>.
68 This is rarely needed, as Perl manages its memory quite well. But the
69 option exists, should a class wish to perform specific actions upon the
70 destruction of an instance.
71
72 =back
73
74 =head1 MORE INFORMATION
75
76 The L<perltie> section uses a good example of tying scalars by associating
77 process IDs with priority.
78
79 =cut
80
81 use Carp;
82
83 sub new {
84     my $pkg = shift;
85     $pkg->TIESCALAR(@_);
86 }
87
88 # "Grandfather" the new, a la Tie::Hash
89
90 sub 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
102 sub FETCH {
103     my $pkg = ref $_[0];
104     croak "$pkg doesn't define a FETCH method";
105 }
106
107 sub 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 #
117 package Tie::StdScalar;
118 @ISA = (Tie::Scalar);
119
120 sub TIESCALAR {
121     my $class = shift;
122     my $instance = shift || undef;
123     return bless \$instance => $class;
124 }
125
126 sub FETCH {
127     return ${$_[0]};
128 }
129
130 sub STORE {
131     ${$_[0]} = $_[1];
132 }
133
134 sub DESTROY {
135     undef ${$_[0]};
136 }
137
138 1;