3 perltie - how to hide an object class in a simple variable
7 tie VARIABLE, CLASSNAME, LIST
9 $object = tied VARIABLE
15 Prior to release 5.0 of Perl, a programmer could use dbmopen()
16 to connect an on-disk database in the standard Unix dbm(3x)
17 format magically 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.
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. 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()
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.
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.
50 A class implementing a tied scalar should define the following methods:
51 TIESCALAR, FETCH, STORE, and possibly DESTROY.
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:
56 tie $his_speed, 'Nice', getppid();
57 tie $my_speed, 'Nice', $$;
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!
63 We'll use Jarkko Hietaniemi <F<jhi@iki.fi>>'s BSD::Resource class (not
64 included) to access the PRIO_PROCESS, PRIO_MIN, and PRIO_MAX constants
65 from your system, as well as the getpriority() and setpriority() system
66 calls. Here's the preamble of the class.
72 $Nice::DEBUG = 0 unless defined $Nice::DEBUG;
76 =item TIESCALAR classname, LIST
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:
84 my $pid = shift || $$; # 0 means me
86 if ($pid !~ /^\d+$/) {
87 carp "Nice::Tie::Scalar got non-numeric pid $pid" if $^W;
91 unless (kill 0, $pid) { # EPERM or ERSCH, no doubt
92 carp "Nice::Tie::Scalar got bad pid $pid: $!" if $^W;
96 return bless \$pid, $class;
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.
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. Because in this case
109 we're using just 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.
115 confess "wrong type" unless ref $self;
116 croak "usage error" if @_;
119 $nicety = getpriority(PRIO_PROCESS, $$self);
120 if ($!) { croak "getpriority failed: $!" }
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.
128 =item STORE this, value
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.
136 confess "wrong type" unless ref $self;
137 my $new_nicety = shift;
138 croak "usage error" if @_;
140 if ($new_nicety < PRIO_MIN) {
142 "WARNING: priority %d less than minimum system priority %d",
143 $new_nicety, PRIO_MIN if $^W;
144 $new_nicety = PRIO_MIN;
147 if ($new_nicety > PRIO_MAX) {
149 "WARNING: priority %d greater than maximum system priority %d",
150 $new_nicety, PRIO_MAX if $^W;
151 $new_nicety = PRIO_MAX;
154 unless (defined setpriority(PRIO_PROCESS, $$self, $new_nicety)) {
155 confess "setpriority failed: $!";
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, because 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.
169 confess "wrong type" unless ref $self;
170 carp "[ Nice::DESTROY pid $$self ]" if $Nice::DEBUG;
175 That's about all there is to it. Actually, it's more than all there
176 is to it, because 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.
182 A class implementing a tied ordinary array should define the following
183 methods: TIEARRAY, FETCH, STORE, FETCHSIZE, STORESIZE and perhaps DESTROY.
185 FETCHSIZE and STORESIZE are used to provide C<$#array> and
186 equivalent C<scalar(@array)> access.
188 The methods POP, PUSH, SHIFT, UNSHIFT, SPLICE are required if the perl
189 operator with the corresponding (but lowercase) name is to operate on the
190 tied array. The B<Tie::Array> class can be used as a base class to implement
191 these in terms of the basic five methods above.
193 In addition EXTEND will be called when perl would have pre-extended
194 allocation in a real array.
196 This means that tied arrays are now I<complete>. The example below needs
197 upgrading to illustrate this. (The documentation in B<Tie::Array> is more
200 For this discussion, we'll implement an array whose indices are fixed at
201 its creation. If you try to access anything beyond those bounds, you'll
202 take an exception. For example:
204 require Bounded_Array;
205 tie @ary, 'Bounded_Array', 2;
208 print "setting index $i: ";
211 print "value of elt $i now $ary[$i]\n";
214 The preamble code for the class is as follows:
216 package Bounded_Array;
222 =item TIEARRAY classname, LIST
224 This is the constructor for the class. That means it is expected to
225 return a blessed reference through which the new array (probably an
226 anonymous ARRAY ref) will be accessed.
228 In our example, just to show you that you don't I<really> have to return an
229 ARRAY reference, we'll choose a HASH reference to represent our object.
230 A HASH works out well as a generic record type: the C<{BOUND}> field will
231 store the maximum bound allowed, and the C<{ARRAY}> field will hold the
232 true ARRAY ref. If someone outside the class tries to dereference the
233 object returned (doubtless thinking it an ARRAY ref), they'll blow up.
234 This just goes to show you that you should respect an object's privacy.
239 confess "usage: tie(\@ary, 'Bounded_Array', max_subscript)"
240 if @_ || $bound =~ /\D/;
247 =item FETCH this, index
249 This method will be triggered every time an individual element the tied array
250 is accessed (read). It takes one argument beyond its self reference: the
251 index whose value we're trying to fetch.
255 if ($idx > $self->{BOUND}) {
256 confess "Array OOB: $idx > $self->{BOUND}";
258 return $self->{ARRAY}[$idx];
261 As you may have noticed, the name of the FETCH method (et al.) is the same
262 for all accesses, even though the constructors differ in names (TIESCALAR
263 vs TIEARRAY). While in theory you could have the same class servicing
264 several tied types, in practice this becomes cumbersome, and it's easiest
265 to keep them at simply one tie type per class.
267 =item STORE this, index, value
269 This method will be triggered every time an element in the tied array is set
270 (written). It takes two arguments beyond its self reference: the index at
271 which we're trying to store something and the value we're trying to put
275 my($self, $idx, $value) = @_;
276 print "[STORE $value at $idx]\n" if _debug;
277 if ($idx > $self->{BOUND} ) {
278 confess "Array OOB: $idx > $self->{BOUND}";
280 return $self->{ARRAY}[$idx] = $value;
285 This method will be triggered when the tied variable needs to be destructed.
286 As with the scalar tie class, this is almost never needed in a
287 language that does its own garbage collection, so this time we'll
292 The code we presented at the top of the tied array class accesses many
293 elements of the array, far more than we've set the bounds to. Therefore,
294 it will blow up once they try to access beyond the 2nd element of @ary, as
295 the following output demonstrates:
297 setting index 0: value of elt 0 now 0
298 setting index 1: value of elt 1 now 10
299 setting index 2: value of elt 2 now 20
300 setting index 3: Array OOB: 3 > 2 at Bounded_Array.pm line 39
301 Bounded_Array::FETCH called at testba line 12
305 As the first Perl data type to be tied (see dbmopen()), hashes have the
306 most complete and useful tie() implementation. A class implementing a
307 tied hash should define the following methods: TIEHASH is the constructor.
308 FETCH and STORE access the key and value pairs. EXISTS reports whether a
309 key is present in the hash, and DELETE deletes one. CLEAR empties the
310 hash by deleting all the key and value pairs. FIRSTKEY and NEXTKEY
311 implement the keys() and each() functions to iterate over all the keys.
312 And DESTROY is called when the tied variable is garbage collected.
314 If this seems like a lot, then feel free to inherit from merely the
315 standard Tie::Hash module for most of your methods, redefining only the
316 interesting ones. See L<Tie::Hash> for details.
318 Remember that Perl distinguishes between a key not existing in the hash,
319 and the key existing in the hash but having a corresponding value of
320 C<undef>. The two possibilities can be tested with the C<exists()> and
321 C<defined()> functions.
323 Here's an example of a somewhat interesting tied hash class: it gives you
324 a hash representing a particular user's dot files. You index into the hash
325 with the name of the file (minus the dot) and you get back that dot file's
326 contents. For example:
329 tie %dot, 'DotFiles';
330 if ( $dot{profile} =~ /MANPATH/ ||
331 $dot{login} =~ /MANPATH/ ||
332 $dot{cshrc} =~ /MANPATH/ )
334 print "you seem to set your MANPATH\n";
337 Or here's another sample of using our tied class:
339 tie %him, 'DotFiles', 'daemon';
340 foreach $f ( keys %him ) {
341 printf "daemon dot file %s is size %d\n",
345 In our tied hash DotFiles example, we use a regular
346 hash for the object containing several important
347 fields, of which only the C<{LIST}> field will be what the
348 user thinks of as the real hash.
354 whose dot files this object represents
358 where those dot files live
362 whether we should try to change or remove those dot files
366 the hash of dot file names and content mappings
370 Here's the start of F<Dotfiles.pm>:
374 sub whowasi { (caller(1))[3] . '()' }
376 sub debug { $DEBUG = @_ ? shift : 1 }
378 For our example, we want to be able to emit debugging info to help in tracing
379 during development. We keep also one convenience function around
380 internally to help print out warnings; whowasi() returns the function name
383 Here are the methods for the DotFiles tied hash.
387 =item TIEHASH classname, LIST
389 This is the constructor for the class. That means it is expected to
390 return a blessed reference through which the new object (probably but not
391 necessarily an anonymous hash) will be accessed.
393 Here's the constructor:
397 my $user = shift || $>;
398 my $dotdir = shift || '';
399 croak "usage: @{[&whowasi]} [USER [DOTDIR]]" if @_;
400 $user = getpwuid($user) if $user =~ /^\d+$/;
401 my $dir = (getpwnam($user))[7]
402 || croak "@{[&whowasi]}: no user $user";
403 $dir .= "/$dotdir" if $dotdir;
413 || croak "@{[&whowasi]}: can't opendir $dir: $!";
414 foreach $dot ( grep /^\./ && -f "$dir/$_", readdir(DIR)) {
416 $node->{LIST}{$dot} = undef;
419 return bless $node, $self;
422 It's probably worth mentioning that if you're going to filetest the
423 return values out of a readdir, you'd better prepend the directory
424 in question. Otherwise, because we didn't chdir() there, it would
425 have been testing the wrong file.
427 =item FETCH this, key
429 This method will be triggered every time an element in the tied hash is
430 accessed (read). It takes one argument beyond its self reference: the key
431 whose value we're trying to fetch.
433 Here's the fetch for our DotFiles example.
436 carp &whowasi if $DEBUG;
439 my $dir = $self->{HOME};
440 my $file = "$dir/.$dot";
442 unless (exists $self->{LIST}->{$dot} || -f $file) {
443 carp "@{[&whowasi]}: no $dot file" if $DEBUG;
447 if (defined $self->{LIST}->{$dot}) {
448 return $self->{LIST}->{$dot};
450 return $self->{LIST}->{$dot} = `cat $dir/.$dot`;
454 It was easy to write by having it call the Unix cat(1) command, but it
455 would probably be more portable to open the file manually (and somewhat
456 more efficient). Of course, because dot files are a Unixy concept, we're
459 =item STORE this, key, value
461 This method will be triggered every time an element in the tied hash is set
462 (written). It takes two arguments beyond its self reference: the index at
463 which we're trying to store something, and the value we're trying to put
466 Here in our DotFiles example, we'll be careful not to let
467 them try to overwrite the file unless they've called the clobber()
468 method on the original object reference returned by tie().
471 carp &whowasi if $DEBUG;
475 my $file = $self->{HOME} . "/.$dot";
476 my $user = $self->{USER};
478 croak "@{[&whowasi]}: $file not clobberable"
479 unless $self->{CLOBBER};
481 open(F, "> $file") || croak "can't open $file: $!";
486 If they wanted to clobber something, they might say:
488 $ob = tie %daemon_dots, 'daemon';
490 $daemon_dots{signature} = "A true daemon\n";
492 Another way to lay hands on a reference to the underlying object is to
493 use the tied() function, so they might alternately have set clobber
496 tie %daemon_dots, 'daemon';
497 tied(%daemon_dots)->clobber(1);
499 The clobber method is simply:
503 $self->{CLOBBER} = @_ ? shift : 1;
506 =item DELETE this, key
508 This method is triggered when we remove an element from the hash,
509 typically by using the delete() function. Again, we'll
510 be careful to check whether they really want to clobber files.
513 carp &whowasi if $DEBUG;
517 my $file = $self->{HOME} . "/.$dot";
518 croak "@{[&whowasi]}: won't remove file $file"
519 unless $self->{CLOBBER};
520 delete $self->{LIST}->{$dot};
521 my $success = unlink($file);
522 carp "@{[&whowasi]}: can't unlink $file: $!" unless $success;
526 The value returned by DELETE becomes the return value of the call
527 to delete(). If you want to emulate the normal behavior of delete(),
528 you should return whatever FETCH would have returned for this key.
529 In this example, we have chosen instead to return a value which tells
530 the caller whether the file was successfully deleted.
534 This method is triggered when the whole hash is to be cleared, usually by
535 assigning the empty list to it.
537 In our example, that would remove all the user's dot files! It's such a
538 dangerous thing that they'll have to set CLOBBER to something higher than
542 carp &whowasi if $DEBUG;
544 croak "@{[&whowasi]}: won't remove all dot files for $self->{USER}"
545 unless $self->{CLOBBER} > 1;
547 foreach $dot ( keys %{$self->{LIST}}) {
552 =item EXISTS this, key
554 This method is triggered when the user uses the exists() function
555 on a particular hash. In our example, we'll look at the C<{LIST}>
556 hash element for this:
559 carp &whowasi if $DEBUG;
562 return exists $self->{LIST}->{$dot};
567 This method will be triggered when the user is going
568 to iterate through the hash, such as via a keys() or each()
572 carp &whowasi if $DEBUG;
574 my $a = keys %{$self->{LIST}}; # reset each() iterator
575 each %{$self->{LIST}}
578 =item NEXTKEY this, lastkey
580 This method gets triggered during a keys() or each() iteration. It has a
581 second argument which is the last key that had been accessed. This is
582 useful if you're carrying about ordering or calling the iterator from more
583 than one sequence, or not really storing things in a hash anywhere.
585 For our example, we're using a real hash so we'll do just the simple
586 thing, but we'll have to go through the LIST field indirectly.
589 carp &whowasi if $DEBUG;
591 return each %{ $self->{LIST} }
596 This method is triggered when a tied hash is about to go out of
597 scope. You don't really need it unless you're trying to add debugging
598 or have auxiliary state to clean up. Here's a very simple function:
601 carp &whowasi if $DEBUG;
606 Note that functions such as keys() and values() may return huge lists
607 when used on large objects, like DBM files. You may prefer to use the
608 each() function to iterate over such. Example:
610 # print out history file offsets
612 tie(%HIST, 'NDBM_File', '/usr/lib/news/history', 1, 0);
613 while (($key,$val) = each %HIST) {
614 print $key, ' = ', unpack('L',$val), "\n";
618 =head2 Tying FileHandles
620 This is partially implemented now.
622 A class implementing a tied filehandle should define the following
623 methods: TIEHANDLE, at least one of PRINT, PRINTF, WRITE, READLINE, GETC,
624 READ, and possibly CLOSE and DESTROY.
626 It is especially useful when perl is embedded in some other program,
627 where output to STDOUT and STDERR may have to be redirected in some
628 special way. See nvi and the Apache module for examples.
630 In our example we're going to create a shouting handle.
636 =item TIEHANDLE classname, LIST
638 This is the constructor for the class. That means it is expected to
639 return a blessed reference of some sort. The reference can be used to
640 hold some internal information.
642 sub TIEHANDLE { print "<shout>\n"; my $i; bless \$i, shift }
644 =item WRITE this, LIST
646 This method will be called when the handle is written to via the
647 C<syswrite> function.
651 my($buf,$len,$offset) = @_;
652 print "WRITE called, \$buf=$buf, \$len=$len, \$offset=$offset";
655 =item PRINT this, LIST
657 This method will be triggered every time the tied handle is printed to
658 with the C<print()> function.
659 Beyond its self reference it also expects the list that was passed to
662 sub PRINT { $r = shift; $$r++; print join($,,map(uc($_),@_)),$\ }
664 =item PRINTF this, LIST
666 This method will be triggered every time the tied handle is printed to
667 with the C<printf()> function.
668 Beyond its self reference it also expects the format and list that was
669 passed to the printf function.
674 print sprintf($fmt, @_)."\n";
677 =item READ this, LIST
679 This method will be called when the handle is read from via the C<read>
680 or C<sysread> functions.
684 my $$bufref = \$_[0];
685 my(undef,$len,$offset) = @_;
686 print "READ called, \$buf=$bufref, \$len=$len, \$offset=$offset";
687 # add to $$bufref, set $len to number of characters read
693 This method will be called when the handle is read from via <HANDLE>.
694 The method should return undef when there is no more data.
696 sub READLINE { $r = shift; "READLINE called $$r times\n"; }
700 This method will be called when the C<getc> function is called.
702 sub GETC { print "Don't GETC, Get Perl"; return "a"; }
706 This method will be called when the handle is closed via the C<close>
709 sub CLOSE { print "CLOSE called.\n" }
713 As with the other types of ties, this method will be called when the
714 tied handle is about to be destroyed. This is useful for debugging and
715 possibly cleaning up.
717 sub DESTROY { print "</shout>\n" }
721 Here's how to use our little example:
726 print FOO $a, " plus ", $b, " equals ", $a + $b, "\n";
729 =head2 The C<untie> Gotcha
731 If you intend making use of the object returned from either tie() or
732 tied(), and if the tie's target class defines a destructor, there is a
733 subtle gotcha you I<must> guard against.
735 As setup, consider this (admittedly rather contrived) example of a
736 tie; all it does is use a file to keep a log of the values assigned to
746 my $filename = shift;
747 my $handle = new IO::File "> $filename"
748 or die "Cannot open $filename: $!\n";
750 print $handle "The Start\n";
751 bless {FH => $handle, Value => 0}, $class;
756 return $self->{Value};
762 my $handle = $self->{FH};
763 print $handle "$value\n";
764 $self->{Value} = $value;
769 my $handle = $self->{FH};
770 print $handle "The End\n";
776 Here is an example that makes use of this tie:
782 tie $fred, 'Remember', 'myfile.txt';
787 system "cat myfile.txt";
789 This is the output when it is executed:
797 So far so good. Those of you who have been paying attention will have
798 spotted that the tied object hasn't been used so far. So lets add an
799 extra method to the Remember class to allow comments to be included in
800 the file -- say, something like this:
805 my $handle = $self->{FH};
806 print $handle $text, "\n";
809 And here is the previous example modified to use the C<comment> method
810 (which requires the tied object):
816 $x = tie $fred, 'Remember', 'myfile.txt';
819 comment $x "changing...";
822 system "cat myfile.txt";
824 When this code is executed there is no output. Here's why:
826 When a variable is tied, it is associated with the object which is the
827 return value of the TIESCALAR, TIEARRAY, or TIEHASH function. This
828 object normally has only one reference, namely, the implicit reference
829 from the tied variable. When untie() is called, that reference is
830 destroyed. Then, as in the first example above, the object's
831 destructor (DESTROY) is called, which is normal for objects that have
832 no more valid references; and thus the file is closed.
834 In the second example, however, we have stored another reference to
835 the tied object in C<$x>. That means that when untie() gets called
836 there will still be a valid reference to the object in existence, so
837 the destructor is not called at that time, and thus the file is not
838 closed. The reason there is no output is because the file buffers
839 have not been flushed to disk.
841 Now that you know what the problem is, what can you do to avoid it?
842 Well, the good old C<-w> flag will spot any instances where you call
843 untie() and there are still valid references to the tied object. If
844 the second script above is run with the C<-w> flag, Perl prints this
847 untie attempted while 1 inner references still exist
849 To get the script to work properly and silence the warning make sure
850 there are no valid references to the tied object I<before> untie() is
858 See L<DB_File> or L<Config> for some interesting tie() implementations.
862 Tied arrays are I<incomplete>. They are also distinctly lacking something
863 for the C<$#ARRAY> access (which is hard, as it's an lvalue), as well as
864 the other obvious array functions, like push(), pop(), shift(), unshift(),
867 You cannot easily tie a multilevel data structure (such as a hash of
868 hashes) to a dbm file. The first problem is that all but GDBM and
869 Berkeley DB have size limitations, but beyond that, you also have problems
870 with how references are to be represented on disk. One experimental
871 module that does attempt to address this need partially is the MLDBM
872 module. Check your nearest CPAN site as described in L<perlmodlib> for
873 source code to MLDBM.
879 TIEHANDLE by Sven Verdoolaege <F<skimo@dns.ufsia.ac.be>> and Doug MacEachern <F<dougm@osf.org>>