Cwd::fastcwd in File::Find
[perl.git] / pod / perltie.pod
1 =head1 NAME
2
3 perltie - how to hide an object class in a simple variable
4
5 =head1 SYNOPSIS
6
7  tie VARIABLE, CLASSNAME, LIST
8
9  $object = tied VARIABLE
10
11  untie VARIABLE
12
13 =head1 DESCRIPTION
14
15 Prior to release 5.0 of Perl, a programmer could use dbmopen()
16 to magically connect an on-disk database in the standard Unix dbm(3x)
17 format to a %HASH in their program.  However, their Perl was either
18 built with one particular dbm library or another, but not both, and
19 you couldn't extend this mechanism to other packages or types of variables.
20
21 Now you can.
22
23 The tie() function binds a variable to a class (package) that will provide
24 the implementation for access methods for that variable.  Once this magic
25 has been performed, accessing a tied variable automatically triggers
26 method calls in the proper class.  All of the complexity of the class is
27 hidden behind magic methods calls.  The method names are in ALL CAPS,
28 which is a convention that Perl uses to indicate that they're called
29 implicitly rather than explicitly--just like the BEGIN() and END()
30 functions.
31
32 In the tie() call, C<VARIABLE> is the name of the variable to be
33 enchanted.  C<CLASSNAME> is the name of a class implementing objects of
34 the correct type.  Any additional arguments in the C<LIST> are passed to
35 the appropriate constructor method for that class--meaning TIESCALAR(),
36 TIEARRAY(), TIEHASH() or TIEHANDLE().  (Typically these are arguments
37 such as might be passed to the dbminit() function of C.) The object
38 returned by the "new" method is also returned by the tie() function,
39 which would be useful if you wanted to access other methods in
40 C<CLASSNAME>. (You don't actually have to return a reference to a right
41 "type" (e.g. HASH or C<CLASSNAME>) so long as it's a properly blessed
42 object.)  You can also retrieve a reference to the underlying object
43 using the tied() function.
44
45 Unlike dbmopen(), the tie() function will not C<use> or C<require> a module
46 for you--you need to do that explicitly yourself.
47
48 =head2 Tying Scalars
49
50 A class implementing a tied scalar should define the following methods:
51 TIESCALAR, FETCH, STORE, and possibly DESTROY.
52
53 Let's look at each in turn, using as an example a tie class for
54 scalars that allows the user to do something like:
55
56     tie $his_speed, 'Nice', getppid();
57     tie $my_speed,  'Nice', $$;
58
59 And now whenever either of those variables is accessed, its current
60 system priority is retrieved and returned.  If those variables are set,
61 then the process's priority is changed!
62
63 We'll use Jarkko Hietaniemi F<E<lt>Jarkko.Hietaniemi@hut.fiE<gt>>'s
64 BSD::Resource class (not included) to access the PRIO_PROCESS, PRIO_MIN,
65 and PRIO_MAX constants from your system, as well as the getpriority() and
66 setpriority() system calls.  Here's the preamble of the class.
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
78 This is the constructor for the class.  That means it is
79 expected 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+$/) {
87             carp "Nice::Tie::Scalar got non-numeric pid $pid" if $^W;
88             return undef;
89         }
90
91         unless (kill 0, $pid) { # EPERM or ERSCH, no doubt
92             carp "Nice::Tie::Scalar got bad pid $pid: $!" if $^W;
93             return undef;
94         }
95
96         return bless \$pid, $class;
97     }
98
99 This tie class has chosen to return an error rather than raising an
100 exception if its constructor should fail.  While this is how dbmopen() works,
101 other classes may well not wish to be so forgiving.  It checks the global
102 variable C<$^W> to see whether to emit a bit of noise anyway.
103
104 =item FETCH this
105
106 This method will be triggered every time the tied variable is accessed
107 (read).  It takes no arguments beyond its self reference, which is the
108 object representing the scalar we're dealing with.  Since in this case
109 we're just using a SCALAR ref for the tied scalar object, a simple $$self
110 allows the method to get at the real value stored there.  In our example
111 below, 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
124 This time we've decided to blow up (raise an exception) if the renice
125 fails--there's no place for us to return an error otherwise, and it's
126 probably the right thing to do.
127
128 =item STORE this, value
129
130 This method will be triggered every time the tied variable is set
131 (assigned).  Beyond its self reference, it also expects one (and only one)
132 argument--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
162 This method will be triggered when the tied variable needs to be destructed.
163 As with other object classes, such a method is seldom necessary, since Perl
164 deallocates its moribund object's memory for you automatically--this isn't
165 C++, 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
175 That's about all there is to it.  Actually, it's more than all there
176 is to it, since we've done a few nice things here for the sake
177 of completeness, robustness, and general aesthetics.  Simpler
178 TIESCALAR classes are certainly possible.
179
180 =head2 Tying Arrays
181
182 A class implementing a tied ordinary array should define the following
183 methods: TIEARRAY, FETCH, STORE, and perhaps DESTROY.
184
185 B<WARNING>: Tied arrays are I<incomplete>.  They are also distinctly lacking
186 something for the C<$#ARRAY> access (which is hard, as it's an lvalue), as
187 well as the other obvious array functions, like push(), pop(), shift(),
188 unshift(), and splice().
189
190 For this discussion, we'll implement an array whose indices are fixed at
191 its creation.  If you try to access anything beyond those bounds, you'll
192 take an exception.  (Well, if you access an individual element; an
193 aggregate assignment would be missed.) For example:
194
195     require Bounded_Array;
196     tie @ary, 'Bounded_Array', 2;
197     $| = 1;
198     for $i (0 .. 10) {
199         print "setting index $i: ";
200         $ary[$i] = 10 * $i;
201         $ary[$i] = 10 * $i;
202         print "value of elt $i now $ary[$i]\n";
203     }
204
205 The preamble code for the class is as follows:
206
207     package Bounded_Array;
208     use Carp;
209     use strict;
210
211 =over
212
213 =item TIEARRAY classname, LIST
214
215 This is the constructor for the class.  That means it is expected to
216 return a blessed reference through which the new array (probably an
217 anonymous ARRAY ref) will be accessed.
218
219 In our example, just to show you that you don't I<really> have to return an
220 ARRAY reference, we'll choose a HASH reference to represent our object.
221 A HASH works out well as a generic record type: the C<{BOUND}> field will
222 store the maximum bound allowed, and the C<{ARRAY}> field will hold the
223 true ARRAY ref.  If someone outside the class tries to dereference the
224 object returned (doubtless thinking it an ARRAY ref), they'll blow up.
225 This just goes to show you that you should respect an object's privacy.
226
227     sub TIEARRAY {
228         my $class = shift;
229         my $bound = shift;
230         confess "usage: tie(\@ary, 'Bounded_Array', max_subscript)"
231             if @_ || $bound =~ /\D/;
232         return bless {
233             BOUND => $bound,
234             ARRAY => [],
235         }, $class;
236     }
237
238 =item FETCH this, index
239
240 This method will be triggered every time an individual element the tied array
241 is accessed (read).  It takes one argument beyond its self reference: the
242 index whose value we're trying to fetch.
243
244     sub FETCH {
245       my($self,$idx) = @_;
246       if ($idx > $self->{BOUND}) {
247         confess "Array OOB: $idx > $self->{BOUND}";
248       }
249       return $self->{ARRAY}[$idx];
250     }
251
252 As you may have noticed, the name of the FETCH method (et al.) is the same
253 for all accesses, even though the constructors differ in names (TIESCALAR
254 vs TIEARRAY).  While in theory you could have the same class servicing
255 several tied types, in practice this becomes cumbersome, and it's easiest
256 to simply keep them at one tie type per class.
257
258 =item STORE this, index, value
259
260 This method will be triggered every time an element in the tied array is set
261 (written).  It takes two arguments beyond its self reference: the index at
262 which we're trying to store something and the value we're trying to put
263 there.  For example:
264
265     sub STORE {
266       my($self, $idx, $value) = @_;
267       print "[STORE $value at $idx]\n" if _debug;
268       if ($idx > $self->{BOUND} ) {
269         confess "Array OOB: $idx > $self->{BOUND}";
270       }
271       return $self->{ARRAY}[$idx] = $value;
272     }
273
274 =item DESTROY this
275
276 This method will be triggered when the tied variable needs to be destructed.
277 As with the sclar tie class, this is almost never needed in a
278 language that does its own garbage collection, so this time we'll
279 just leave it out.
280
281 =back
282
283 The code we presented at the top of the tied array class accesses many
284 elements of the array, far more than we've set the bounds to.  Therefore,
285 it will blow up once they try to access beyond the 2nd element of @ary, as
286 the following output demonstrates:
287
288     setting index 0: value of elt 0 now 0
289     setting index 1: value of elt 1 now 10
290     setting index 2: value of elt 2 now 20
291     setting index 3: Array OOB: 3 > 2 at Bounded_Array.pm line 39
292             Bounded_Array::FETCH called at testba line 12
293
294 =head2 Tying Hashes
295
296 As the first Perl data type to be tied (see dbmopen()), associative arrays
297 have the most complete and useful tie() implementation.  A class
298 implementing a tied associative array should define the following
299 methods:  TIEHASH is the constructor.  FETCH and STORE access the key and
300 value pairs.  EXISTS reports whether a key is present in the hash, and
301 DELETE deletes one.  CLEAR empties the hash by deleting all the key and
302 value pairs.  FIRSTKEY and NEXTKEY implement the keys() and each()
303 functions to iterate over all the keys.  And DESTROY is called when the
304 tied variable is garbage collected.
305
306 If this seems like a lot, then feel free to merely inherit
307 from the standard Tie::Hash module for most of your methods, redefining only
308 the interesting ones.  See L<Tie::Hash> for details.
309
310 Remember that Perl distinguishes between a key not existing in the hash,
311 and the key existing in the hash but having a corresponding value of
312 C<undef>.  The two possibilities can be tested with the C<exists()> and
313 C<defined()> functions.
314
315 Here's an example of a somewhat interesting tied hash class:  it gives you
316 a hash representing a particular user's dotfiles.  You index into the hash
317 with the name of the file (minus the dot) and you get back that dotfile's
318 contents.  For example:
319
320     use DotFiles;
321     tie %dot, 'DotFiles';
322     if ( $dot{profile} =~ /MANPATH/ ||
323          $dot{login}   =~ /MANPATH/ ||
324          $dot{cshrc}   =~ /MANPATH/    )
325     {
326         print "you seem to set your manpath\n";
327     }
328
329 Or here's another sample of using our tied class:
330
331     tie %him, 'DotFiles', 'daemon';
332     foreach $f ( keys %him ) {
333         printf "daemon dot file %s is size %d\n",
334             $f, length $him{$f};
335     }
336
337 In our tied hash DotFiles example, we use a regular
338 hash for the object containing several important
339 fields, of which only the C<{LIST}> field will be what the
340 user thinks of as the real hash.
341
342 =over 5
343
344 =item USER
345
346 whose dot files this object represents
347
348 =item HOME
349
350 where those dotfiles live
351
352 =item CLOBBER
353
354 whether we should try to change or remove those dot files
355
356 =item LIST
357
358 the hash of dotfile names and content mappings
359
360 =back
361
362 Here's the start of F<Dotfiles.pm>:
363
364     package DotFiles;
365     use Carp;
366     sub whowasi { (caller(1))[3] . '()' }
367     my $DEBUG = 0;
368     sub debug { $DEBUG = @_ ? shift : 1 }
369
370 For our example, we want to able to emit debugging info to help in tracing
371 during development.  We keep also one convenience function around
372 internally to help print out warnings; whowasi() returns the function name
373 that calls it.
374
375 Here are the methods for the DotFiles tied hash.
376
377 =over
378
379 =item TIEHASH classname, LIST
380
381 This is the constructor for the class.  That means it is expected to
382 return a blessed reference through which the new object (probably but not
383 necessarily an anonymous hash) will be accessed.
384
385 Here's the constructor:
386
387     sub TIEHASH {
388         my $self = shift;
389         my $user = shift || $>;
390         my $dotdir = shift || '';
391         croak "usage: @{[&whowasi]} [USER [DOTDIR]]" if @_;
392         $user = getpwuid($user) if $user =~ /^\d+$/;
393         my $dir = (getpwnam($user))[7]
394                 || croak "@{[&whowasi]}: no user $user";
395         $dir .= "/$dotdir" if $dotdir;
396
397         my $node = {
398             USER    => $user,
399             HOME    => $dir,
400             LIST    => {},
401             CLOBBER => 0,
402         };
403
404         opendir(DIR, $dir)
405                 || croak "@{[&whowasi]}: can't opendir $dir: $!";
406         foreach $dot ( grep /^\./ && -f "$dir/$_", readdir(DIR)) {
407             $dot =~ s/^\.//;
408             $node->{LIST}{$dot} = undef;
409         }
410         closedir DIR;
411         return bless $node, $self;
412     }
413
414 It's probably worth mentioning that if you're going to filetest the
415 return values out of a readdir, you'd better prepend the directory
416 in question.  Otherwise, since we didn't chdir() there, it would
417 have been testing the wrong file.  
418
419 =item FETCH this, key
420
421 This method will be triggered every time an element in the tied hash is
422 accessed (read).  It takes one argument beyond its self reference: the key
423 whose value we're trying to fetch.
424
425 Here's the fetch for our DotFiles example.
426
427     sub FETCH {
428         carp &whowasi if $DEBUG;
429         my $self = shift;
430         my $dot = shift;
431         my $dir = $self->{HOME};
432         my $file = "$dir/.$dot";
433
434         unless (exists $self->{LIST}->{$dot} || -f $file) {
435             carp "@{[&whowasi]}: no $dot file" if $DEBUG;
436             return undef;
437         }
438
439         if (defined $self->{LIST}->{$dot}) {
440             return $self->{LIST}->{$dot};
441         } else {
442             return $self->{LIST}->{$dot} = `cat $dir/.$dot`;
443         }
444     }
445
446 It was easy to write by having it call the Unix cat(1) command, but it
447 would probably be more portable to open the file manually (and somewhat
448 more efficient).  Of course, since dot files are a Unixy concept, we're
449 not that concerned.
450
451 =item STORE this, key, value
452
453 This method will be triggered every time an element in the tied hash is set
454 (written).  It takes two arguments beyond its self reference: the index at
455 which we're trying to store something, and the value we're trying to put
456 there.
457
458 Here in our DotFiles example, we'll be careful not to let
459 them try to overwrite the file unless they've called the clobber()
460 method on the original object reference returned by tie().
461
462     sub STORE {
463         carp &whowasi if $DEBUG;
464         my $self = shift;
465         my $dot = shift;
466         my $value = shift;
467         my $file = $self->{HOME} . "/.$dot";
468         my $user = $self->{USER};
469
470         croak "@{[&whowasi]}: $file not clobberable"
471             unless $self->{CLOBBER};
472
473         open(F, "> $file") || croak "can't open $file: $!";
474         print F $value;
475         close(F);
476     }
477
478 If they wanted to clobber something, they might say:
479
480     $ob = tie %daemon_dots, 'daemon';
481     $ob->clobber(1);
482     $daemon_dots{signature} = "A true daemon\n";
483
484 Another way to lay hands on a reference to the underlying object is to
485 use the tied() function, so they might alternately have set clobber
486 using:
487
488     tie %daemon_dots, 'daemon';
489     tied(%daemon_dots)->clobber(1);
490
491 The clobber method is simply:
492
493     sub clobber {
494         my $self = shift;
495         $self->{CLOBBER} = @_ ? shift : 1;
496     }
497
498 =item DELETE this, key
499
500 This method is triggered when we remove an element from the hash,
501 typically by using the delete() function.  Again, we'll
502 be careful to check whether they really want to clobber files.
503
504     sub DELETE   {
505         carp &whowasi if $DEBUG;
506
507         my $self = shift;
508         my $dot = shift;
509         my $file = $self->{HOME} . "/.$dot";
510         croak "@{[&whowasi]}: won't remove file $file"
511             unless $self->{CLOBBER};
512         delete $self->{LIST}->{$dot};
513         my $success = unlink($file);
514         carp "@{[&whowasi]}: can't unlink $file: $!" unless $success;
515         $success;
516     }
517
518 The value returned by DELETE becomes the return value of the call
519 to delete().  If you want to emulate the normal behavior of delete(),
520 you should return whatever FETCH would have returned for this key.
521 In this example, we have chosen instead to return a value which tells
522 the caller whether the file was successfully deleted.
523
524 =item CLEAR this
525
526 This method is triggered when the whole hash is to be cleared, usually by
527 assigning the empty list to it.
528
529 In our example, that would remove all the user's dotfiles!  It's such a
530 dangerous thing that they'll have to set CLOBBER to something higher than
531 1 to make it happen.
532
533     sub CLEAR    {
534         carp &whowasi if $DEBUG;
535         my $self = shift;
536         croak "@{[&whowasi]}: won't remove all dotfiles for $self->{USER}"
537             unless $self->{CLOBBER} > 1;
538         my $dot;
539         foreach $dot ( keys %{$self->{LIST}}) {
540             $self->DELETE($dot);
541         }
542     }
543
544 =item EXISTS this, key
545
546 This method is triggered when the user uses the exists() function
547 on a particular hash.  In our example, we'll look at the C<{LIST}>
548 hash element for this:
549
550     sub EXISTS   {
551         carp &whowasi if $DEBUG;
552         my $self = shift;
553         my $dot = shift;
554         return exists $self->{LIST}->{$dot};
555     }
556
557 =item FIRSTKEY this
558
559 This method will be triggered when the user is going
560 to iterate through the hash, such as via a keys() or each()
561 call.
562
563     sub FIRSTKEY {
564         carp &whowasi if $DEBUG;
565         my $self = shift;
566         my $a = keys %{$self->{LIST}};          # reset each() iterator
567         each %{$self->{LIST}}
568     }
569
570 =item NEXTKEY this, lastkey
571
572 This method gets triggered during a keys() or each() iteration.  It has a
573 second argument which is the last key that had been accessed.  This is
574 useful if you're carrying about ordering or calling the iterator from more
575 than one sequence, or not really storing things in a hash anywhere.
576
577 For our example, we our using a real hash so we'll just do the simple
578 thing, but we'll have to indirect through the LIST field.
579
580     sub NEXTKEY  {
581         carp &whowasi if $DEBUG;
582         my $self = shift;
583         return each %{ $self->{LIST} }
584     }
585
586 =item DESTROY this
587
588 This method is triggered when a tied hash is about to go out of
589 scope.  You don't really need it unless you're trying to add debugging
590 or have auxiliary state to clean up.  Here's a very simple function:
591
592     sub DESTROY  {
593         carp &whowasi if $DEBUG;
594     }
595
596 =back
597
598 Note that functions such as keys() and values() may return huge array
599 values when used on large objects, like DBM files.  You may prefer to
600 use the each() function to iterate over such.  Example:
601
602     # print out history file offsets
603     use NDBM_File;
604     tie(%HIST, 'NDBM_File', '/usr/lib/news/history', 1, 0);
605     while (($key,$val) = each %HIST) {
606         print $key, ' = ', unpack('L',$val), "\n";
607     }
608     untie(%HIST);
609
610 =head2 Tying FileHandles
611
612 This is partially implemeted now.
613
614 A class implementing a tied scalar should define the folowing methods:
615 TIEHANDLE, PRINT, and possibly DESTROY.
616
617 In future READLINE, EOF and possibly others will be added.
618
619 It is especially useful when perl is embedded in some other program,
620 where output to STDOUT and STDERR may have to be redirected in some
621 special way. See nvi and the Apache module for examples.
622
623 In our example we're going to create a shouting handle.
624
625     package Shout;
626
627 =over
628
629 =item TIEHANDLE classname, LIST
630
631 This is the constructor for the class.  That means it is expected to
632 return a blessed reference of some sort. The refence can be used to
633 hold some internal information. We won't use it in out example.
634
635     sub TIEHANDLE { print "<shout>\n"; bless [], shift }
636
637 =item PRINT this, LIST
638
639 This method will be triggered every time the tied handle is printed to.
640 Beyond its self refence it also expects the list that was passed to
641 the print function.
642
643     sub PRINT { shift; for (@_) { print uc($_) } }
644
645 =item DESTROY this
646
647 As with the other types of ties, this method will be called when the
648 tied handle is about to be destroyed. This is useful for debugging and
649 possibly cleaning up.
650
651     sub DESTROY { print "</shout>\n" }
652
653 =back
654
655 Here's how to use our little example:
656
657     tie(*FOO,'Shout');
658     print FOO "hello\n";
659     $a = 4; $b = 6;
660     print FOO $a, " plus ", $b, " equals ", $a + $b, "\n";
661
662 =head1 SEE ALSO
663
664 See L<DB_File> or L<Config> for some interesting tie() implementations.
665
666 =head1 BUGS
667
668 Tied arrays are I<incomplete>.  They are also distinctly lacking something
669 for the C<$#ARRAY> access (which is hard, as it's an lvalue), as well as
670 the other obvious array functions, like push(), pop(), shift(), unshift(),
671 and splice().
672
673 You cannot easily tie a multilevel data structure (such as a hash of
674 hashes) to a dbm file.  The first problem is that all but GDBM and
675 Berkeley DB have size limitations, but beyond that, you also have problems
676 with how references are to be represented on disk.  One experimental
677 module that does attempt to partially address this need is the MLDBM
678 module.  Check your nearest CPAN site as described in L<perlmod> for
679 source code to MLDBM.
680
681 =head1 AUTHOR
682
683 Tom Christiansen
684
685 TIEHANDLE by Sven Verdoolaege <skimo@dns.ufsia.ac.be>