Commit | Line | Data |
64d0c973 |
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 | |
c954a603 |
29 | tie $new_scalar, 'NewScalar'; |
30 | tie $new_std_scalar, 'NewStdScalar'; |
64d0c973 |
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; |