Commit | Line | Data |
---|---|---|
64d0c973 RR |
1 | package Tie::Scalar; |
2 | ||
3f89fda6 | 3 | our $VERSION = '1.02'; |
b75c8c73 | 4 | |
64d0c973 RR |
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; | |
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 | 31 | tie $new_scalar, 'NewScalar'; |
32 | tie $new_std_scalar, 'NewStdScalar'; | |
64d0c973 RR |
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 | ||
bbc7dcd2 | 50 | =over 4 |
64d0c973 RR |
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 | ||
b588e26b A |
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 | ||
64d0c973 RR |
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; | |
d3a7d8c7 | 96 | use warnings::register; |
64d0c973 RR |
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; | |
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 | ||
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; | |
abc0156b | 143 | @ISA = qw(Tie::Scalar); |
64d0c973 RR |
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; |