Commit | Line | Data |
64d0c973 |
1 | package Tie::Scalar; |
2 | |
3f89fda6 |
3 | our $VERSION = '1.02'; |
b75c8c73 |
4 | |
64d0c973 |
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 |
16 | sub FETCH { ... } # Provide a needed method |
17 | sub TIESCALAR { ... } # Overrides inherited method |
3cb6de81 |
18 | |
19 | |
64d0c973 |
20 | package NewStdScalar; |
21 | require Tie::Scalar; |
3cb6de81 |
22 | |
abc0156b |
23 | @ISA = qw(Tie::StdScalar); |
3cb6de81 |
24 | |
64d0c973 |
25 | # All methods provided by default, so define only what needs be overridden |
26 | sub FETCH { ... } |
3cb6de81 |
27 | |
28 | |
64d0c973 |
29 | package main; |
3cb6de81 |
30 | |
c954a603 |
31 | tie $new_scalar, 'NewScalar'; |
32 | tie $new_std_scalar, 'NewStdScalar'; |
64d0c973 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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; |