This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
avoid warnings in diagnostics.pm; pod tweaks (from Peter Prymmer
[perl5.git] / pod / perltie.pod
CommitLineData
cb1a09d0
AD
1=head1 NAME
2
3perltie - how to hide an object class in a simple variable
4
5=head1 SYNOPSIS
6
7 tie VARIABLE, CLASSNAME, LIST
8
6fdf61fb
PP
9 $object = tied VARIABLE
10
cb1a09d0
AD
11 untie VARIABLE
12
13=head1 DESCRIPTION
14
15Prior to release 5.0 of Perl, a programmer could use dbmopen()
5f05dabc
PP
16to connect an on-disk database in the standard Unix dbm(3x)
17format magically to a %HASH in their program. However, their Perl was either
cb1a09d0
AD
18built with one particular dbm library or another, but not both, and
19you couldn't extend this mechanism to other packages or types of variables.
20
21Now you can.
22
23The tie() function binds a variable to a class (package) that will provide
24the implementation for access methods for that variable. Once this magic
25has been performed, accessing a tied variable automatically triggers
5a964f20 26method calls in the proper class. The complexity of the class is
cb1a09d0
AD
27hidden behind magic methods calls. The method names are in ALL CAPS,
28which is a convention that Perl uses to indicate that they're called
29implicitly rather than explicitly--just like the BEGIN() and END()
30functions.
31
32In the tie() call, C<VARIABLE> is the name of the variable to be
33enchanted. C<CLASSNAME> is the name of a class implementing objects of
34the correct type. Any additional arguments in the C<LIST> are passed to
35the appropriate constructor method for that class--meaning TIESCALAR(),
5f05dabc 36TIEARRAY(), TIEHASH(), or TIEHANDLE(). (Typically these are arguments
a7adf1f0
PP
37such as might be passed to the dbminit() function of C.) The object
38returned by the "new" method is also returned by the tie() function,
39which would be useful if you wanted to access other methods in
40C<CLASSNAME>. (You don't actually have to return a reference to a right
5f05dabc 41"type" (e.g., HASH or C<CLASSNAME>) so long as it's a properly blessed
a7adf1f0
PP
42object.) You can also retrieve a reference to the underlying object
43using the tied() function.
cb1a09d0
AD
44
45Unlike dbmopen(), the tie() function will not C<use> or C<require> a module
46for you--you need to do that explicitly yourself.
47
48=head2 Tying Scalars
49
50A class implementing a tied scalar should define the following methods:
51TIESCALAR, FETCH, STORE, and possibly DESTROY.
52
53Let's look at each in turn, using as an example a tie class for
54scalars that allows the user to do something like:
55
56 tie $his_speed, 'Nice', getppid();
57 tie $my_speed, 'Nice', $$;
58
59And now whenever either of those variables is accessed, its current
60system priority is retrieved and returned. If those variables are set,
61then the process's priority is changed!
62
5aabfad6
PP
63We'll use Jarkko Hietaniemi <F<jhi@iki.fi>>'s BSD::Resource class (not
64included) to access the PRIO_PROCESS, PRIO_MIN, and PRIO_MAX constants
65from your system, as well as the getpriority() and setpriority() system
66calls. Here's the preamble of the class.
cb1a09d0
AD
67
68 package Nice;
69 use Carp;
70 use BSD::Resource;
71 use strict;
72 $Nice::DEBUG = 0 unless defined $Nice::DEBUG;
73
74=over
75
76=item TIESCALAR classname, LIST
77
78This is the constructor for the class. That means it is
79expected to return a blessed reference to a new scalar
80(probably anonymous) that it's creating. For example:
81
82 sub TIESCALAR {
83 my $class = shift;
84 my $pid = shift || $$; # 0 means me
85
86 if ($pid !~ /^\d+$/) {
6fdf61fb 87 carp "Nice::Tie::Scalar got non-numeric pid $pid" if $^W;
cb1a09d0
AD
88 return undef;
89 }
90
91 unless (kill 0, $pid) { # EPERM or ERSCH, no doubt
6fdf61fb 92 carp "Nice::Tie::Scalar got bad pid $pid: $!" if $^W;
cb1a09d0
AD
93 return undef;
94 }
95
96 return bless \$pid, $class;
97 }
98
99This tie class has chosen to return an error rather than raising an
100exception if its constructor should fail. While this is how dbmopen() works,
101other classes may well not wish to be so forgiving. It checks the global
102variable C<$^W> to see whether to emit a bit of noise anyway.
103
104=item FETCH this
105
106This method will be triggered every time the tied variable is accessed
107(read). It takes no arguments beyond its self reference, which is the
5f05dabc
PP
108object representing the scalar we're dealing with. Because in this case
109we're using just a SCALAR ref for the tied scalar object, a simple $$self
cb1a09d0
AD
110allows the method to get at the real value stored there. In our example
111below, that real value is the process ID to which we've tied our variable.
112
113 sub FETCH {
114 my $self = shift;
115 confess "wrong type" unless ref $self;
116 croak "usage error" if @_;
117 my $nicety;
118 local($!) = 0;
119 $nicety = getpriority(PRIO_PROCESS, $$self);
120 if ($!) { croak "getpriority failed: $!" }
121 return $nicety;
122 }
123
124This time we've decided to blow up (raise an exception) if the renice
125fails--there's no place for us to return an error otherwise, and it's
126probably the right thing to do.
127
128=item STORE this, value
129
130This method will be triggered every time the tied variable is set
131(assigned). Beyond its self reference, it also expects one (and only one)
132argument--the new value the user is trying to assign.
133
134 sub STORE {
135 my $self = shift;
136 confess "wrong type" unless ref $self;
137 my $new_nicety = shift;
138 croak "usage error" if @_;
139
140 if ($new_nicety < PRIO_MIN) {
141 carp sprintf
142 "WARNING: priority %d less than minimum system priority %d",
143 $new_nicety, PRIO_MIN if $^W;
144 $new_nicety = PRIO_MIN;
145 }
146
147 if ($new_nicety > PRIO_MAX) {
148 carp sprintf
149 "WARNING: priority %d greater than maximum system priority %d",
150 $new_nicety, PRIO_MAX if $^W;
151 $new_nicety = PRIO_MAX;
152 }
153
154 unless (defined setpriority(PRIO_PROCESS, $$self, $new_nicety)) {
155 confess "setpriority failed: $!";
156 }
157 return $new_nicety;
158 }
159
160=item DESTROY this
161
162This method will be triggered when the tied variable needs to be destructed.
5f05dabc 163As with other object classes, such a method is seldom necessary, because Perl
cb1a09d0
AD
164deallocates its moribund object's memory for you automatically--this isn't
165C++, you know. We'll use a DESTROY method here for debugging purposes only.
166
167 sub DESTROY {
168 my $self = shift;
169 confess "wrong type" unless ref $self;
170 carp "[ Nice::DESTROY pid $$self ]" if $Nice::DEBUG;
171 }
172
173=back
174
175That's about all there is to it. Actually, it's more than all there
5f05dabc 176is to it, because we've done a few nice things here for the sake
cb1a09d0
AD
177of completeness, robustness, and general aesthetics. Simpler
178TIESCALAR classes are certainly possible.
179
180=head2 Tying Arrays
181
182A class implementing a tied ordinary array should define the following
a60c0954 183methods: TIEARRAY, FETCH, STORE, FETCHSIZE, STORESIZE and perhaps DESTROY.
cb1a09d0 184
a60c0954
NIS
185FETCHSIZE and STORESIZE are used to provide C<$#array> and
186equivalent C<scalar(@array)> access.
c47ff5f1 187
01020589
GS
188The methods POP, PUSH, SHIFT, UNSHIFT, SPLICE, DELETE, and EXISTS are
189required if the perl operator with the corresponding (but lowercase) name
190is to operate on the tied array. The B<Tie::Array> class can be used as a
191base class to implement the first five of these in terms of the basic
192methods above. The default implementations of DELETE and EXISTS in
193B<Tie::Array> simply C<croak>.
a60c0954
NIS
194
195In addition EXTEND will be called when perl would have pre-extended
196allocation in a real array.
197
198This means that tied arrays are now I<complete>. The example below needs
199upgrading to illustrate this. (The documentation in B<Tie::Array> is more
200complete.)
cb1a09d0
AD
201
202For this discussion, we'll implement an array whose indices are fixed at
203its creation. If you try to access anything beyond those bounds, you'll
a60c0954 204take an exception. For example:
cb1a09d0
AD
205
206 require Bounded_Array;
1f57c600 207 tie @ary, 'Bounded_Array', 2;
cb1a09d0
AD
208 $| = 1;
209 for $i (0 .. 10) {
210 print "setting index $i: ";
211 $ary[$i] = 10 * $i;
212 $ary[$i] = 10 * $i;
213 print "value of elt $i now $ary[$i]\n";
214 }
215
216The preamble code for the class is as follows:
217
218 package Bounded_Array;
219 use Carp;
220 use strict;
221
222=over
223
224=item TIEARRAY classname, LIST
225
226This is the constructor for the class. That means it is expected to
227return a blessed reference through which the new array (probably an
228anonymous ARRAY ref) will be accessed.
229
230In our example, just to show you that you don't I<really> have to return an
231ARRAY reference, we'll choose a HASH reference to represent our object.
232A HASH works out well as a generic record type: the C<{BOUND}> field will
03dc9dad 233store the maximum bound allowed, and the C<{ARRAY}> field will hold the
cb1a09d0
AD
234true ARRAY ref. If someone outside the class tries to dereference the
235object returned (doubtless thinking it an ARRAY ref), they'll blow up.
236This just goes to show you that you should respect an object's privacy.
237
238 sub TIEARRAY {
239 my $class = shift;
240 my $bound = shift;
241 confess "usage: tie(\@ary, 'Bounded_Array', max_subscript)"
242 if @_ || $bound =~ /\D/;
243 return bless {
244 BOUND => $bound,
245 ARRAY => [],
246 }, $class;
247 }
248
249=item FETCH this, index
250
251This method will be triggered every time an individual element the tied array
252is accessed (read). It takes one argument beyond its self reference: the
253index whose value we're trying to fetch.
254
255 sub FETCH {
256 my($self,$idx) = @_;
257 if ($idx > $self->{BOUND}) {
258 confess "Array OOB: $idx > $self->{BOUND}";
259 }
260 return $self->{ARRAY}[$idx];
261 }
262
263As you may have noticed, the name of the FETCH method (et al.) is the same
264for all accesses, even though the constructors differ in names (TIESCALAR
265vs TIEARRAY). While in theory you could have the same class servicing
266several tied types, in practice this becomes cumbersome, and it's easiest
5f05dabc 267to keep them at simply one tie type per class.
cb1a09d0
AD
268
269=item STORE this, index, value
270
271This method will be triggered every time an element in the tied array is set
272(written). It takes two arguments beyond its self reference: the index at
273which we're trying to store something and the value we're trying to put
274there. For example:
275
276 sub STORE {
277 my($self, $idx, $value) = @_;
278 print "[STORE $value at $idx]\n" if _debug;
279 if ($idx > $self->{BOUND} ) {
280 confess "Array OOB: $idx > $self->{BOUND}";
281 }
282 return $self->{ARRAY}[$idx] = $value;
283 }
284
285=item DESTROY this
286
287This method will be triggered when the tied variable needs to be destructed.
184e9718 288As with the scalar tie class, this is almost never needed in a
cb1a09d0
AD
289language that does its own garbage collection, so this time we'll
290just leave it out.
291
292=back
293
294The code we presented at the top of the tied array class accesses many
295elements of the array, far more than we've set the bounds to. Therefore,
296it will blow up once they try to access beyond the 2nd element of @ary, as
297the following output demonstrates:
298
299 setting index 0: value of elt 0 now 0
300 setting index 1: value of elt 1 now 10
301 setting index 2: value of elt 2 now 20
302 setting index 3: Array OOB: 3 > 2 at Bounded_Array.pm line 39
303 Bounded_Array::FETCH called at testba line 12
304
305=head2 Tying Hashes
306
aa689395
PP
307As the first Perl data type to be tied (see dbmopen()), hashes have the
308most complete and useful tie() implementation. A class implementing a
309tied hash should define the following methods: TIEHASH is the constructor.
310FETCH and STORE access the key and value pairs. EXISTS reports whether a
311key is present in the hash, and DELETE deletes one. CLEAR empties the
312hash by deleting all the key and value pairs. FIRSTKEY and NEXTKEY
313implement the keys() and each() functions to iterate over all the keys.
314And DESTROY is called when the tied variable is garbage collected.
315
316If this seems like a lot, then feel free to inherit from merely the
317standard Tie::Hash module for most of your methods, redefining only the
318interesting ones. See L<Tie::Hash> for details.
cb1a09d0
AD
319
320Remember that Perl distinguishes between a key not existing in the hash,
321and the key existing in the hash but having a corresponding value of
322C<undef>. The two possibilities can be tested with the C<exists()> and
323C<defined()> functions.
324
325Here's an example of a somewhat interesting tied hash class: it gives you
5f05dabc
PP
326a hash representing a particular user's dot files. You index into the hash
327with the name of the file (minus the dot) and you get back that dot file's
cb1a09d0
AD
328contents. For example:
329
330 use DotFiles;
1f57c600 331 tie %dot, 'DotFiles';
cb1a09d0
AD
332 if ( $dot{profile} =~ /MANPATH/ ||
333 $dot{login} =~ /MANPATH/ ||
334 $dot{cshrc} =~ /MANPATH/ )
335 {
5f05dabc 336 print "you seem to set your MANPATH\n";
cb1a09d0
AD
337 }
338
339Or here's another sample of using our tied class:
340
1f57c600 341 tie %him, 'DotFiles', 'daemon';
cb1a09d0
AD
342 foreach $f ( keys %him ) {
343 printf "daemon dot file %s is size %d\n",
344 $f, length $him{$f};
345 }
346
347In our tied hash DotFiles example, we use a regular
348hash for the object containing several important
349fields, of which only the C<{LIST}> field will be what the
350user thinks of as the real hash.
351
352=over 5
353
354=item USER
355
356whose dot files this object represents
357
358=item HOME
359
5f05dabc 360where those dot files live
cb1a09d0
AD
361
362=item CLOBBER
363
364whether we should try to change or remove those dot files
365
366=item LIST
367
5f05dabc 368the hash of dot file names and content mappings
cb1a09d0
AD
369
370=back
371
372Here's the start of F<Dotfiles.pm>:
373
374 package DotFiles;
375 use Carp;
376 sub whowasi { (caller(1))[3] . '()' }
377 my $DEBUG = 0;
378 sub debug { $DEBUG = @_ ? shift : 1 }
379
5f05dabc 380For our example, we want to be able to emit debugging info to help in tracing
cb1a09d0
AD
381during development. We keep also one convenience function around
382internally to help print out warnings; whowasi() returns the function name
383that calls it.
384
385Here are the methods for the DotFiles tied hash.
386
387=over
388
389=item TIEHASH classname, LIST
390
391This is the constructor for the class. That means it is expected to
392return a blessed reference through which the new object (probably but not
393necessarily an anonymous hash) will be accessed.
394
395Here's the constructor:
396
397 sub TIEHASH {
398 my $self = shift;
399 my $user = shift || $>;
400 my $dotdir = shift || '';
401 croak "usage: @{[&whowasi]} [USER [DOTDIR]]" if @_;
402 $user = getpwuid($user) if $user =~ /^\d+$/;
403 my $dir = (getpwnam($user))[7]
404 || croak "@{[&whowasi]}: no user $user";
405 $dir .= "/$dotdir" if $dotdir;
406
407 my $node = {
408 USER => $user,
409 HOME => $dir,
410 LIST => {},
411 CLOBBER => 0,
412 };
413
414 opendir(DIR, $dir)
415 || croak "@{[&whowasi]}: can't opendir $dir: $!";
416 foreach $dot ( grep /^\./ && -f "$dir/$_", readdir(DIR)) {
417 $dot =~ s/^\.//;
418 $node->{LIST}{$dot} = undef;
419 }
420 closedir DIR;
421 return bless $node, $self;
422 }
423
424It's probably worth mentioning that if you're going to filetest the
425return values out of a readdir, you'd better prepend the directory
5f05dabc 426in question. Otherwise, because we didn't chdir() there, it would
2ae324a7 427have been testing the wrong file.
cb1a09d0
AD
428
429=item FETCH this, key
430
431This method will be triggered every time an element in the tied hash is
432accessed (read). It takes one argument beyond its self reference: the key
433whose value we're trying to fetch.
434
435Here's the fetch for our DotFiles example.
436
437 sub FETCH {
438 carp &whowasi if $DEBUG;
439 my $self = shift;
440 my $dot = shift;
441 my $dir = $self->{HOME};
442 my $file = "$dir/.$dot";
443
444 unless (exists $self->{LIST}->{$dot} || -f $file) {
445 carp "@{[&whowasi]}: no $dot file" if $DEBUG;
446 return undef;
447 }
448
449 if (defined $self->{LIST}->{$dot}) {
450 return $self->{LIST}->{$dot};
451 } else {
452 return $self->{LIST}->{$dot} = `cat $dir/.$dot`;
453 }
454 }
455
456It was easy to write by having it call the Unix cat(1) command, but it
457would probably be more portable to open the file manually (and somewhat
5f05dabc 458more efficient). Of course, because dot files are a Unixy concept, we're
cb1a09d0
AD
459not that concerned.
460
461=item STORE this, key, value
462
463This method will be triggered every time an element in the tied hash is set
464(written). It takes two arguments beyond its self reference: the index at
465which we're trying to store something, and the value we're trying to put
466there.
467
468Here in our DotFiles example, we'll be careful not to let
469them try to overwrite the file unless they've called the clobber()
470method on the original object reference returned by tie().
471
472 sub STORE {
473 carp &whowasi if $DEBUG;
474 my $self = shift;
475 my $dot = shift;
476 my $value = shift;
477 my $file = $self->{HOME} . "/.$dot";
478 my $user = $self->{USER};
479
480 croak "@{[&whowasi]}: $file not clobberable"
481 unless $self->{CLOBBER};
482
483 open(F, "> $file") || croak "can't open $file: $!";
484 print F $value;
485 close(F);
486 }
487
488If they wanted to clobber something, they might say:
489
490 $ob = tie %daemon_dots, 'daemon';
491 $ob->clobber(1);
492 $daemon_dots{signature} = "A true daemon\n";
493
6fdf61fb
PP
494Another way to lay hands on a reference to the underlying object is to
495use the tied() function, so they might alternately have set clobber
496using:
497
498 tie %daemon_dots, 'daemon';
499 tied(%daemon_dots)->clobber(1);
500
501The clobber method is simply:
cb1a09d0
AD
502
503 sub clobber {
504 my $self = shift;
505 $self->{CLOBBER} = @_ ? shift : 1;
506 }
507
508=item DELETE this, key
509
510This method is triggered when we remove an element from the hash,
511typically by using the delete() function. Again, we'll
512be careful to check whether they really want to clobber files.
513
514 sub DELETE {
515 carp &whowasi if $DEBUG;
516
517 my $self = shift;
518 my $dot = shift;
519 my $file = $self->{HOME} . "/.$dot";
520 croak "@{[&whowasi]}: won't remove file $file"
521 unless $self->{CLOBBER};
522 delete $self->{LIST}->{$dot};
1f57c600
PP
523 my $success = unlink($file);
524 carp "@{[&whowasi]}: can't unlink $file: $!" unless $success;
525 $success;
cb1a09d0
AD
526 }
527
1f57c600
PP
528The value returned by DELETE becomes the return value of the call
529to delete(). If you want to emulate the normal behavior of delete(),
530you should return whatever FETCH would have returned for this key.
531In this example, we have chosen instead to return a value which tells
532the caller whether the file was successfully deleted.
533
cb1a09d0
AD
534=item CLEAR this
535
536This method is triggered when the whole hash is to be cleared, usually by
537assigning the empty list to it.
538
5f05dabc 539In our example, that would remove all the user's dot files! It's such a
cb1a09d0
AD
540dangerous thing that they'll have to set CLOBBER to something higher than
5411 to make it happen.
542
543 sub CLEAR {
544 carp &whowasi if $DEBUG;
545 my $self = shift;
5f05dabc 546 croak "@{[&whowasi]}: won't remove all dot files for $self->{USER}"
cb1a09d0
AD
547 unless $self->{CLOBBER} > 1;
548 my $dot;
549 foreach $dot ( keys %{$self->{LIST}}) {
550 $self->DELETE($dot);
551 }
552 }
553
554=item EXISTS this, key
555
556This method is triggered when the user uses the exists() function
557on a particular hash. In our example, we'll look at the C<{LIST}>
558hash element for this:
559
560 sub EXISTS {
561 carp &whowasi if $DEBUG;
562 my $self = shift;
563 my $dot = shift;
564 return exists $self->{LIST}->{$dot};
565 }
566
567=item FIRSTKEY this
568
569This method will be triggered when the user is going
570to iterate through the hash, such as via a keys() or each()
571call.
572
573 sub FIRSTKEY {
574 carp &whowasi if $DEBUG;
575 my $self = shift;
6fdf61fb 576 my $a = keys %{$self->{LIST}}; # reset each() iterator
cb1a09d0
AD
577 each %{$self->{LIST}}
578 }
579
580=item NEXTKEY this, lastkey
581
582This method gets triggered during a keys() or each() iteration. It has a
583second argument which is the last key that had been accessed. This is
584useful if you're carrying about ordering or calling the iterator from more
585than one sequence, or not really storing things in a hash anywhere.
586
5f05dabc
PP
587For our example, we're using a real hash so we'll do just the simple
588thing, but we'll have to go through the LIST field indirectly.
cb1a09d0
AD
589
590 sub NEXTKEY {
591 carp &whowasi if $DEBUG;
592 my $self = shift;
593 return each %{ $self->{LIST} }
594 }
595
596=item DESTROY this
597
598This method is triggered when a tied hash is about to go out of
599scope. You don't really need it unless you're trying to add debugging
600or have auxiliary state to clean up. Here's a very simple function:
601
602 sub DESTROY {
603 carp &whowasi if $DEBUG;
604 }
605
606=back
607
1d2dff63
GS
608Note that functions such as keys() and values() may return huge lists
609when used on large objects, like DBM files. You may prefer to use the
610each() function to iterate over such. Example:
cb1a09d0
AD
611
612 # print out history file offsets
613 use NDBM_File;
1f57c600 614 tie(%HIST, 'NDBM_File', '/usr/lib/news/history', 1, 0);
cb1a09d0
AD
615 while (($key,$val) = each %HIST) {
616 print $key, ' = ', unpack('L',$val), "\n";
617 }
618 untie(%HIST);
619
620=head2 Tying FileHandles
621
184e9718 622This is partially implemented now.
a7adf1f0 623
2ae324a7 624A class implementing a tied filehandle should define the following
1d603a67 625methods: TIEHANDLE, at least one of PRINT, PRINTF, WRITE, READLINE, GETC,
4592e6ca
NIS
626READ, and possibly CLOSE and DESTROY. The class can also provide: BINMODE,
627OPEN, EOF, FILENO, SEEK, TELL - if the corresponding perl operators are
628used on the handle.
a7adf1f0
PP
629
630It is especially useful when perl is embedded in some other program,
631where output to STDOUT and STDERR may have to be redirected in some
632special way. See nvi and the Apache module for examples.
633
634In our example we're going to create a shouting handle.
635
636 package Shout;
637
638=over
639
640=item TIEHANDLE classname, LIST
641
642This is the constructor for the class. That means it is expected to
184e9718 643return a blessed reference of some sort. The reference can be used to
5f05dabc 644hold some internal information.
a7adf1f0 645
7e1af8bc 646 sub TIEHANDLE { print "<shout>\n"; my $i; bless \$i, shift }
a7adf1f0 647
1d603a67
GB
648=item WRITE this, LIST
649
650This method will be called when the handle is written to via the
651C<syswrite> function.
652
653 sub WRITE {
654 $r = shift;
655 my($buf,$len,$offset) = @_;
656 print "WRITE called, \$buf=$buf, \$len=$len, \$offset=$offset";
657 }
658
a7adf1f0
PP
659=item PRINT this, LIST
660
46fc3d4c
PP
661This method will be triggered every time the tied handle is printed to
662with the C<print()> function.
184e9718 663Beyond its self reference it also expects the list that was passed to
a7adf1f0
PP
664the print function.
665
58f51617
SV
666 sub PRINT { $r = shift; $$r++; print join($,,map(uc($_),@_)),$\ }
667
46fc3d4c
PP
668=item PRINTF this, LIST
669
670This method will be triggered every time the tied handle is printed to
671with the C<printf()> function.
672Beyond its self reference it also expects the format and list that was
673passed to the printf function.
674
675 sub PRINTF {
676 shift;
677 my $fmt = shift;
678 print sprintf($fmt, @_)."\n";
679 }
680
1d603a67 681=item READ this, LIST
2ae324a7
PP
682
683This method will be called when the handle is read from via the C<read>
684or C<sysread> functions.
685
686 sub READ {
889a76e8
GS
687 my $self = shift;
688 my $$bufref = \$_[0];
689 my(undef,$len,$offset) = @_;
690 print "READ called, \$buf=$bufref, \$len=$len, \$offset=$offset";
691 # add to $$bufref, set $len to number of characters read
692 $len;
2ae324a7
PP
693 }
694
58f51617
SV
695=item READLINE this
696
2ae324a7
PP
697This method will be called when the handle is read from via <HANDLE>.
698The method should return undef when there is no more data.
58f51617 699
889a76e8 700 sub READLINE { $r = shift; "READLINE called $$r times\n"; }
a7adf1f0 701
2ae324a7
PP
702=item GETC this
703
704This method will be called when the C<getc> function is called.
705
706 sub GETC { print "Don't GETC, Get Perl"; return "a"; }
707
1d603a67
GB
708=item CLOSE this
709
710This method will be called when the handle is closed via the C<close>
711function.
712
713 sub CLOSE { print "CLOSE called.\n" }
714
a7adf1f0
PP
715=item DESTROY this
716
717As with the other types of ties, this method will be called when the
718tied handle is about to be destroyed. This is useful for debugging and
719possibly cleaning up.
720
721 sub DESTROY { print "</shout>\n" }
722
723=back
724
725Here's how to use our little example:
726
727 tie(*FOO,'Shout');
728 print FOO "hello\n";
729 $a = 4; $b = 6;
730 print FOO $a, " plus ", $b, " equals ", $a + $b, "\n";
58f51617 731 print <FOO>;
cb1a09d0 732
2752eb9f
PM
733=head2 The C<untie> Gotcha
734
735If you intend making use of the object returned from either tie() or
736tied(), and if the tie's target class defines a destructor, there is a
737subtle gotcha you I<must> guard against.
738
739As setup, consider this (admittedly rather contrived) example of a
740tie; all it does is use a file to keep a log of the values assigned to
741a scalar.
742
743 package Remember;
744
745 use strict;
9f1b1f2d 746 use warnings;
2752eb9f
PM
747 use IO::File;
748
749 sub TIESCALAR {
750 my $class = shift;
751 my $filename = shift;
752 my $handle = new IO::File "> $filename"
753 or die "Cannot open $filename: $!\n";
754
755 print $handle "The Start\n";
756 bless {FH => $handle, Value => 0}, $class;
757 }
758
759 sub FETCH {
760 my $self = shift;
761 return $self->{Value};
762 }
763
764 sub STORE {
765 my $self = shift;
766 my $value = shift;
767 my $handle = $self->{FH};
768 print $handle "$value\n";
769 $self->{Value} = $value;
770 }
771
772 sub DESTROY {
773 my $self = shift;
774 my $handle = $self->{FH};
775 print $handle "The End\n";
776 close $handle;
777 }
778
779 1;
780
781Here is an example that makes use of this tie:
782
783 use strict;
784 use Remember;
785
786 my $fred;
787 tie $fred, 'Remember', 'myfile.txt';
788 $fred = 1;
789 $fred = 4;
790 $fred = 5;
791 untie $fred;
792 system "cat myfile.txt";
793
794This is the output when it is executed:
795
796 The Start
797 1
798 4
799 5
800 The End
801
802So far so good. Those of you who have been paying attention will have
803spotted that the tied object hasn't been used so far. So lets add an
804extra method to the Remember class to allow comments to be included in
805the file -- say, something like this:
806
807 sub comment {
808 my $self = shift;
809 my $text = shift;
810 my $handle = $self->{FH};
811 print $handle $text, "\n";
812 }
813
814And here is the previous example modified to use the C<comment> method
815(which requires the tied object):
816
817 use strict;
818 use Remember;
819
820 my ($fred, $x);
821 $x = tie $fred, 'Remember', 'myfile.txt';
822 $fred = 1;
823 $fred = 4;
824 comment $x "changing...";
825 $fred = 5;
826 untie $fred;
827 system "cat myfile.txt";
828
829When this code is executed there is no output. Here's why:
830
831When a variable is tied, it is associated with the object which is the
832return value of the TIESCALAR, TIEARRAY, or TIEHASH function. This
833object normally has only one reference, namely, the implicit reference
834from the tied variable. When untie() is called, that reference is
835destroyed. Then, as in the first example above, the object's
836destructor (DESTROY) is called, which is normal for objects that have
837no more valid references; and thus the file is closed.
838
839In the second example, however, we have stored another reference to
19799a22 840the tied object in $x. That means that when untie() gets called
2752eb9f
PM
841there will still be a valid reference to the object in existence, so
842the destructor is not called at that time, and thus the file is not
843closed. The reason there is no output is because the file buffers
844have not been flushed to disk.
845
846Now that you know what the problem is, what can you do to avoid it?
847Well, the good old C<-w> flag will spot any instances where you call
848untie() and there are still valid references to the tied object. If
9f1b1f2d
GS
849the second script above this near the top C<use warnings 'untie'>
850or was run with the C<-w> flag, Perl prints this
2752eb9f
PM
851warning message:
852
853 untie attempted while 1 inner references still exist
854
855To get the script to work properly and silence the warning make sure
856there are no valid references to the tied object I<before> untie() is
857called:
858
859 undef $x;
860 untie $fred;
861
cb1a09d0
AD
862=head1 SEE ALSO
863
864See L<DB_File> or L<Config> for some interesting tie() implementations.
3d0ae7ba
GS
865A good starting point for many tie() implementations is with one of the
866modules L<Tie::Scalar>, L<Tie::Array>, L<Tie::Hash>, or L<Tie::Handle>.
cb1a09d0
AD
867
868=head1 BUGS
869
c07a80fd
PP
870You cannot easily tie a multilevel data structure (such as a hash of
871hashes) to a dbm file. The first problem is that all but GDBM and
872Berkeley DB have size limitations, but beyond that, you also have problems
873with how references are to be represented on disk. One experimental
5f05dabc 874module that does attempt to address this need partially is the MLDBM
f102b883 875module. Check your nearest CPAN site as described in L<perlmodlib> for
c07a80fd
PP
876source code to MLDBM.
877
cb1a09d0
AD
878=head1 AUTHOR
879
880Tom Christiansen
a7adf1f0 881
46fc3d4c 882TIEHANDLE by Sven Verdoolaege <F<skimo@dns.ufsia.ac.be>> and Doug MacEachern <F<dougm@osf.org>>