1Tie::Watch(3) perl/Tk Documentation Tie::Watch(3)
2
6 Tie::Watch - place watchpoints on Perl variables.
7
9 use Tie::Watch;
10 $watch = Tie::Watch->new(
12 -variable => \$frog,
13 -debug => 1,
14 -shadow => 0,
15 -fetch => [\&fetch, 'arg1', 'arg2', ..., 'argn'],
16 -store => \&store,
17 -destroy => sub {print "Final value=$frog.\n"},
18 }
19 %vinfo = $watch->Info;
20 $args = $watch->Args(-fetch);
21 $val = $watch->Fetch;
22 print "val=", $watch->Say($val), ".\n";
23 $watch->Store('Hello');
24 $watch->Unwatch;
25
27 This class module binds one or more subroutines of your devising to a
28 Perl variable. All variables can have FETCH, STORE and DESTROY
29 callbacks. Additionally, arrays can define CLEAR, DELETE, EXISTS,
30 EXTEND, FETCHSIZE, POP, PUSH, SHIFT, SPLICE, STORESIZE and UNSHIFT
31 callbacks, and hashes can define CLEAR, DELETE, EXISTS, FIRSTKEY and
32 NEXTKEY callbacks. If these term are unfamiliar to you, I really
33 suggest you read perltie.
34 With Tie::Watch you can:
36 . alter a variable's value
38 . prevent a variable's value from being changed
39 . invoke a Perl/Tk callback when a variable changes
40 . trace references to a variable
41 Callback format is patterned after the Perl/Tk scheme: supply either a
43 code reference, or, supply an array reference and pass the callback
44 code reference in the first element of the array, followed by callback
45 arguments. (See examples in the Synopsis, above.)
46 Tie::Watch provides default callbacks for any that you fail to specify.
48 Other than negatively impacting performance, they perform the standard
49 action that you'd expect, so the variable behaves "normally". Once you
50 override a default callback, perhaps to insert debug code like print
51 statements, your callback normally finishes by calling the underlying
52 (overridden) method. But you don't have to!
53 To map a tied method name to a default callback name simply lowercase
55 the tied method name and uppercase its first character. So FETCH
56 becomes Fetch, NEXTKEY becomes Nextkey, etcetera.
57 Here are two callbacks for a scalar. The FETCH (read) callback does
59 nothing other than illustrate the fact that it returns the value to
60 assign the variable. The STORE (write) callback uppercases the
61 variable and returns it. In all cases the callback must return the
62 correct read or write value - typically, it does this by invoking the
63 underlying method.
64 my $fetch_scalar = sub {
66 my($self) = @_;
67 $self->Fetch;
68 };
69 my $store_scalar = sub {
71 my($self, $new_val) = @_;
72 $self->Store(uc $new_val);
73 };
74 Here are FETCH and STORE callbacks for either an array or hash. They
76 do essentially the same thing as the scalar callbacks, but provide a
77 little more information.
78 my $fetch = sub {
80 my($self, $key) = @_;
81 my $val = $self->Fetch($key);
82 print "In fetch callback, key=$key, val=", $self->Say($val);
83 my $args = $self->Args(-fetch);
84 print ", args=('", join("', '", @$args), "')" if $args;
85 print ".\n";
86 $val;
87 };
88 my $store = sub {
90 my($self, $key, $new_val) = @_;
91 my $val = $self->Fetch($key);
92 $new_val = uc $new_val;
93 $self->Store($key, $new_val);
94 print "In store callback, key=$key, val=", $self->Say($val),
95 ", new_val=", $self->Say($new_val);
96 my $args = $self->Args(-store);
97 print ", args=('", join("', '", @$args), "')" if $args;
98 print ".\n";
99 $new_val;
100 };
101 In all cases, the first parameter is a reference to the Watch object,
103 used to invoke the following class methods.
104
106 $watch = Tie::Watch->new(-options => values);
107 The watchpoint constructor method that accepts option/value pairs
108 to create and configure the Watch object. The only required option
109 is -variable.
110 -variable is a reference to a scalar, array or hash variable.
112 -debug (default 0) is 1 to activate debug print statements internal
114 to Tie::Watch.
115 -shadow (default 1) is 0 to disable array and hash shadowing. To
117 prevent infinite recursion Tie::Watch maintains parallel variables
118 for arrays and hashes. When the watchpoint is created the parallel
119 shadow variable is initialized with the watched variable's
120 contents, and when the watchpoint is deleted the shadow variable is
121 copied to the original variable. Thus, changes made during the
122 watch process are not lost. Shadowing is on my default. If you
123 disable shadowing any changes made to an array or hash are lost
124 when the watchpoint is deleted.
125 Specify any of the following relevant callback parameters, in the
127 format described above: -fetch, -store, -destroy. Additionally for
128 arrays: -clear, -extend, -fetchsize, -pop, -push, -shift, -splice,
129 -storesize and -unshift. Additionally for hashes: -clear, -delete,
130 -exists, -firstkey and -nextkey.
131 $args = $watch->Args(-fetch);
133 Returns a reference to a list of arguments for the specified
134 callback, or undefined if none.
135 $watch->Fetch(); $watch->Fetch($key);
137 Returns a variable's current value. $key is required for an array
138 or hash.
139 %vinfo = $watch->Info();
141 Returns a hash detailing the internals of the Watch object, with
142 these keys:
143 %vinfo = {
145 -variable => SCALAR(0x200737f8)
146 -debug => '0'
147 -shadow => '1'
148 -value => 'HELLO SCALAR'
149 -destroy => ARRAY(0x200f86cc)
150 -fetch => ARRAY(0x200f8558)
151 -store => ARRAY(0x200f85a0)
152 -legible => above data formatted as a list of string, for printing
153 }
154 For array and hash Watch objects, the -value key is replaced with a
156 -ptr key which is a reference to the parallel array or hash.
157 Additionally, for an array or hash, there are key/value pairs for
158 all the variable specific callbacks.
159 $watch->Say($val);
161 Used mainly for debugging, it returns $val in quotes if required,
162 or the string "undefined" for undefined values.
163 $watch->Store($new_val); $watch->Store($key, $new_val);
165 Store a variable's new value. $key is required for an array or
166 hash.
167 $watch->Unwatch();
169 Stop watching the variable.
170
172 If you can live using the class methods provided, please do so. You
173 can meddle with the object hash directly and improved watch
174 performance, at the risk of your code breaking in the future.
175
177 Stephen O. Lidie
178
180 lusol@Lehigh.EDU, LUCC, 96/05/30
181 . Original version 0.92 release, based on the Trace module from Hans Mulder,
182 and ideas from Tim Bunce.
183 lusol@Lehigh.EDU, LUCC, 96/12/25
185 . Version 0.96, release two inner references detected by Perl 5.004.
186 lusol@Lehigh.EDU, LUCC, 97/01/11
188 . Version 0.97, fix Makefile.PL and MANIFEST (thanks Andreas Koenig).
189 Make sure test.pl doesn't fail if Tk isn't installed.
190 Stephen.O.Lidie@Lehigh.EDU, Lehigh University Computing Center, 97/10/03
192 . Version 0.98, implement -shadow option for arrays and hashes.
193 Stephen.O.Lidie@Lehigh.EDU, Lehigh University Computing Center, 98/02/11
195 . Version 0.99, finally, with Perl 5.004_57, we can completely watch arrays.
196 With tied array support this module is essentially complete, so its been
197 optimized for speed at the expense of clarity - sorry about that. The
198 Delete() method has been renamed Unwatch() because it conflicts with the
199 builtin delete().
200 Stephen.O.Lidie@Lehigh.EDU, Lehigh University Computing Center, 99/04/04
202 . Version 1.0, for Perl 5.005_03, update Makefile.PL for ActiveState, and
203 add two examples (one for Perl/Tk).
204 sol0@lehigh.edu, Lehigh University Computing Center, 2003/06/07
206 . Version 1.1, for Perl 5.8, can trace a reference now, patch from Slaven
207 Rezic.
208 sol0@lehigh.edu, Lehigh University Computing Center, 2005/05/17
210 . Version 1.2, for Perl 5.8, per Rob Seegel's suggestion, support array
211 DELETE and EXISTS.
212
214 Copyright (C) 1996 - 2005 Stephen O. Lidie. All rights reserved.
215 This program is free software; you can redistribute it and/or modify it
217 under the same terms as Perl itself.
218Tk804.036 2022-01-21 Tie::Watch(3)