1PERLTIE(1) Perl Programmers Reference Guide PERLTIE(1)
2
6 perltie - how to hide an object class in a simple variable
7
9 tie VARIABLE, CLASSNAME, LIST
10 $object = tied VARIABLE
12 untie VARIABLE
14
16 Prior to release 5.0 of Perl, a programmer could use dbmopen() to
17 connect an on-disk database in the standard Unix dbm(3x) format
18 magically to a %HASH in their program. However, their Perl was either
19 built with one particular dbm library or another, but not both, and you
20 couldn't extend this mechanism to other packages or types of variables.
21 Now you can.
23 The tie() function binds a variable to a class (package) that will
25 provide the implementation for access methods for that variable. Once
26 this magic has been performed, accessing a tied variable automatically
27 triggers method calls in the proper class. The complexity of the class
28 is hidden behind magic methods calls. The method names are in ALL
29 CAPS, which is a convention that Perl uses to indicate that they're
30 called implicitly rather than explicitly--just like the BEGIN() and
31 END() functions.
32 In the tie() call, "VARIABLE" is the name of the variable to be
34 enchanted. "CLASSNAME" is the name of a class implementing objects of
35 the correct type. Any additional arguments in the "LIST" are passed to
36 the appropriate constructor method for that class--meaning TIESCALAR(),
37 TIEARRAY(), TIEHASH(), or TIEHANDLE(). (Typically these are arguments
38 such as might be passed to the dbminit() function of C.) The object
39 returned by the "new" method is also returned by the tie() function,
40 which would be useful if you wanted to access other methods in
41 "CLASSNAME". (You don't actually have to return a reference to a right
42 "type" (e.g., HASH or "CLASSNAME") so long as it's a properly blessed
43 object.) You can also retrieve a reference to the underlying object
44 using the tied() function.
45 Unlike dbmopen(), the tie() function will not "use" or "require" a
47 module for you--you need to do that explicitly yourself.
48 Tying Scalars
50 A class implementing a tied scalar should define the following methods:
51 TIESCALAR, FETCH, STORE, and possibly UNTIE and/or DESTROY.
52 Let's look at each in turn, using as an example a tie class for scalars
54 that allows the user to do something like:
55 tie $his_speed, 'Nice', getppid();
57 tie $my_speed, 'Nice', $$;
58 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 We'll use Jarkko Hietaniemi <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.
67 package Nice;
69 use Carp;
70 use BSD::Resource;
71 use strict;
72 $Nice::DEBUG = 0 unless defined $Nice::DEBUG;
73 TIESCALAR classname, LIST
75 This is the constructor for the class. That means it is expected
76 to return a blessed reference to a new scalar (probably anonymous)
77 that it's creating. For example:
78 sub TIESCALAR {
80 my $class = shift;
81 my $pid = shift || $$; # 0 means me
82 if ($pid !~ /^\d+$/) {
84 carp "Nice::Tie::Scalar got non-numeric pid $pid" if $^W;
85 return undef;
86 }
87 unless (kill 0, $pid) { # EPERM or ERSCH, no doubt
89 carp "Nice::Tie::Scalar got bad pid $pid: $!" if $^W;
90 return undef;
91 }
92 return bless \$pid, $class;
94 }
95 This tie class has chosen to return an error rather than raising an
97 exception if its constructor should fail. While this is how
98 dbmopen() works, other classes may well not wish to be so
99 forgiving. It checks the global variable $^W to see whether to
100 emit a bit of noise anyway.
101 FETCH this
103 This method will be triggered every time the tied variable is
104 accessed (read). It takes no arguments beyond its self reference,
105 which is the object representing the scalar we're dealing with.
106 Because in this case we're using just a SCALAR ref for the tied
107 scalar object, a simple $$self allows the method to get at the real
108 value stored there. In our example below, that real value is the
109 process ID to which we've tied our variable.
110 sub FETCH {
112 my $self = shift;
113 confess "wrong type" unless ref $self;
114 croak "usage error" if @_;
115 my $nicety;
116 local($!) = 0;
117 $nicety = getpriority(PRIO_PROCESS, $$self);
118 if ($!) { croak "getpriority failed: $!" }
119 return $nicety;
120 }
121 This time we've decided to blow up (raise an exception) if the
123 renice fails--there's no place for us to return an error otherwise,
124 and it's probably the right thing to do.
125 STORE this, value
127 This method will be triggered every time the tied variable is set
128 (assigned). Beyond its self reference, it also expects one (and
129 only one) argument: the new value the user is trying to assign.
130 Don't worry about returning a value from STORE; the semantic of
131 assignment returning the assigned value is implemented with FETCH.
132 sub STORE {
134 my $self = shift;
135 confess "wrong type" unless ref $self;
136 my $new_nicety = shift;
137 croak "usage error" if @_;
138 if ($new_nicety < PRIO_MIN) {
140 carp sprintf
141 "WARNING: priority %d less than minimum system priority %d",
142 $new_nicety, PRIO_MIN if $^W;
143 $new_nicety = PRIO_MIN;
144 }
145 if ($new_nicety > PRIO_MAX) {
147 carp sprintf
148 "WARNING: priority %d greater than maximum system priority %d",
149 $new_nicety, PRIO_MAX if $^W;
150 $new_nicety = PRIO_MAX;
151 }
152 unless (defined setpriority(PRIO_PROCESS,
154 $$self,
155 $new_nicety))
156 {
157 confess "setpriority failed: $!";
158 }
159 }
160 UNTIE this
162 This method will be triggered when the "untie" occurs. This can be
163 useful if the class needs to know when no further calls will be
164 made. (Except DESTROY of course.) See "The "untie" Gotcha" below
165 for more details.
166 DESTROY this
168 This method will be triggered when the tied variable needs to be
169 destructed. As with other object classes, such a method is seldom
170 necessary, because Perl deallocates its moribund object's memory
171 for you automatically--this isn't C++, you know. We'll use a
172 DESTROY method here for debugging purposes only.
173 sub DESTROY {
175 my $self = shift;
176 confess "wrong type" unless ref $self;
177 carp "[ Nice::DESTROY pid $$self ]" if $Nice::DEBUG;
178 }
179 That's about all there is to it. Actually, it's more than all there is
181 to it, because we've done a few nice things here for the sake of
182 completeness, robustness, and general aesthetics. Simpler TIESCALAR
183 classes are certainly possible.
184 Tying Arrays
186 A class implementing a tied ordinary array should define the following
187 methods: TIEARRAY, FETCH, STORE, FETCHSIZE, STORESIZE, CLEAR and
188 perhaps UNTIE and/or DESTROY.
189 FETCHSIZE and STORESIZE are used to provide $#array and equivalent
191 "scalar(@array)" access.
192 The methods POP, PUSH, SHIFT, UNSHIFT, SPLICE, DELETE, and EXISTS are
194 required if the perl operator with the corresponding (but lowercase)
195 name is to operate on the tied array. The Tie::Array class can be used
196 as a base class to implement the first five of these in terms of the
197 basic methods above. The default implementations of DELETE and EXISTS
198 in Tie::Array simply "croak".
199 In addition EXTEND will be called when perl would have pre-extended
201 allocation in a real array.
202 For this discussion, we'll implement an array whose elements are a
204 fixed size at creation. If you try to create an element larger than
205 the fixed size, you'll take an exception. For example:
206 use FixedElem_Array;
208 tie @array, 'FixedElem_Array', 3;
209 $array[0] = 'cat'; # ok.
210 $array[1] = 'dogs'; # exception, length('dogs') > 3.
211 The preamble code for the class is as follows:
213 package FixedElem_Array;
215 use Carp;
216 use strict;
217 TIEARRAY classname, LIST
219 This is the constructor for the class. That means it is expected
220 to return a blessed reference through which the new array (probably
221 an anonymous ARRAY ref) will be accessed.
222 In our example, just to show you that you don't really have to
224 return an ARRAY reference, we'll choose a HASH reference to
225 represent our object. A HASH works out well as a generic record
226 type: the "{ELEMSIZE}" field will store the maximum element size
227 allowed, and the "{ARRAY}" field will hold the true ARRAY ref. If
228 someone outside the class tries to dereference the object returned
229 (doubtless thinking it an ARRAY ref), they'll blow up. This just
230 goes to show you that you should respect an object's privacy.
231 sub TIEARRAY {
233 my $class = shift;
234 my $elemsize = shift;
235 if ( @_ || $elemsize =~ /\D/ ) {
236 croak "usage: tie ARRAY, '" . __PACKAGE__ . "', elem_size";
237 }
238 return bless {
239 ELEMSIZE => $elemsize,
240 ARRAY => [],
241 }, $class;
242 }
243 FETCH this, index
245 This method will be triggered every time an individual element the
246 tied array is accessed (read). It takes one argument beyond its
247 self reference: the index whose value we're trying to fetch.
248 sub FETCH {
250 my $self = shift;
251 my $index = shift;
252 return $self->{ARRAY}->[$index];
253 }
254 If a negative array index is used to read from an array, the index
256 will be translated to a positive one internally by calling
257 FETCHSIZE before being passed to FETCH. You may disable this
258 feature by assigning a true value to the variable $NEGATIVE_INDICES
259 in the tied array class.
260 As you may have noticed, the name of the FETCH method (et al.) is
262 the same for all accesses, even though the constructors differ in
263 names (TIESCALAR vs TIEARRAY). While in theory you could have the
264 same class servicing several tied types, in practice this becomes
265 cumbersome, and it's easiest to keep them at simply one tie type
266 per class.
267 STORE this, index, value
269 This method will be triggered every time an element in the tied
270 array is set (written). It takes two arguments beyond its self
271 reference: the index at which we're trying to store something and
272 the value we're trying to put there.
273 In our example, "undef" is really "$self->{ELEMSIZE}" number of
275 spaces so we have a little more work to do here:
276 sub STORE {
278 my $self = shift;
279 my( $index, $value ) = @_;
280 if ( length $value > $self->{ELEMSIZE} ) {
281 croak "length of $value is greater than $self->{ELEMSIZE}";
282 }
283 # fill in the blanks
284 $self->STORESIZE( $index ) if $index > $self->FETCHSIZE();
285 # right justify to keep element size for smaller elements
286 $self->{ARRAY}->[$index] = sprintf "%$self->{ELEMSIZE}s", $value;
287 }
288 Negative indexes are treated the same as with FETCH.
290 FETCHSIZE this
292 Returns the total number of items in the tied array associated with
293 object this. (Equivalent to "scalar(@array)"). For example:
294 sub FETCHSIZE {
296 my $self = shift;
297 return scalar $self->{ARRAY}->@*;
298 }
299 STORESIZE this, count
301 Sets the total number of items in the tied array associated with
302 object this to be count. If this makes the array larger then
303 class's mapping of "undef" should be returned for new positions.
304 If the array becomes smaller then entries beyond count should be
305 deleted.
306 In our example, 'undef' is really an element containing
308 "$self->{ELEMSIZE}" number of spaces. Observe:
309 sub STORESIZE {
311 my $self = shift;
312 my $count = shift;
313 if ( $count > $self->FETCHSIZE() ) {
314 foreach ( $count - $self->FETCHSIZE() .. $count ) {
315 $self->STORE( $_, '' );
316 }
317 } elsif ( $count < $self->FETCHSIZE() ) {
318 foreach ( 0 .. $self->FETCHSIZE() - $count - 2 ) {
319 $self->POP();
320 }
321 }
322 }
323 EXTEND this, count
325 Informative call that array is likely to grow to have count
326 entries. Can be used to optimize allocation. This method need do
327 nothing.
328 In our example there is no reason to implement this method, so we
330 leave it as a no-op. This method is only relevant to tied array
331 implementations where there is the possibility of having the
332 allocated size of the array be larger than is visible to a perl
333 programmer inspecting the size of the array. Many tied array
334 implementations will have no reason to implement it.
335 sub EXTEND {
337 my $self = shift;
338 my $count = shift;
339 # nothing to see here, move along.
340 }
341 NOTE: It is generally an error to make this equivalent to
343 STORESIZE. Perl may from time to time call EXTEND without wanting
344 to actually change the array size directly. Any tied array should
345 function correctly if this method is a no-op, even if perhaps they
346 might not be as efficient as they would if this method was
347 implemented.
348 EXISTS this, key
350 Verify that the element at index key exists in the tied array this.
351 In our example, we will determine that if an element consists of
353 "$self->{ELEMSIZE}" spaces only, it does not exist:
354 sub EXISTS {
356 my $self = shift;
357 my $index = shift;
358 return 0 if ! defined $self->{ARRAY}->[$index] ||
359 $self->{ARRAY}->[$index] eq ' ' x $self->{ELEMSIZE};
360 return 1;
361 }
362 DELETE this, key
364 Delete the element at index key from the tied array this.
365 In our example, a deleted item is "$self->{ELEMSIZE}" spaces:
367 sub DELETE {
369 my $self = shift;
370 my $index = shift;
371 return $self->STORE( $index, '' );
372 }
373 CLEAR this
375 Clear (remove, delete, ...) all values from the tied array
376 associated with object this. For example:
377 sub CLEAR {
379 my $self = shift;
380 return $self->{ARRAY} = [];
381 }
382 PUSH this, LIST
384 Append elements of LIST to the array. For example:
385 sub PUSH {
387 my $self = shift;
388 my @list = @_;
389 my $last = $self->FETCHSIZE();
390 $self->STORE( $last + $_, $list[$_] ) foreach 0 .. $#list;
391 return $self->FETCHSIZE();
392 }
393 POP this
395 Remove last element of the array and return it. For example:
396 sub POP {
398 my $self = shift;
399 return pop $self->{ARRAY}->@*;
400 }
401 SHIFT this
403 Remove the first element of the array (shifting other elements
404 down) and return it. For example:
405 sub SHIFT {
407 my $self = shift;
408 return shift $self->{ARRAY}->@*;
409 }
410 UNSHIFT this, LIST
412 Insert LIST elements at the beginning of the array, moving existing
413 elements up to make room. For example:
414 sub UNSHIFT {
416 my $self = shift;
417 my @list = @_;
418 my $size = scalar( @list );
419 # make room for our list
420 $self->{ARRAY}[ $size .. $self->{ARRAY}->$#* + $size ]->@*
421 = $self->{ARRAY}->@*
422 $self->STORE( $_, $list[$_] ) foreach 0 .. $#list;
423 }
424 SPLICE this, offset, length, LIST
426 Perform the equivalent of "splice" on the array.
427 offset is optional and defaults to zero, negative values count back
429 from the end of the array.
430 length is optional and defaults to rest of the array.
432 LIST may be empty.
434 Returns a list of the original length elements at offset.
436 In our example, we'll use a little shortcut if there is a LIST:
438 sub SPLICE {
440 my $self = shift;
441 my $offset = shift || 0;
442 my $length = shift || $self->FETCHSIZE() - $offset;
443 my @list = ();
444 if ( @_ ) {
445 tie @list, __PACKAGE__, $self->{ELEMSIZE};
446 @list = @_;
447 }
448 return splice $self->{ARRAY}->@*, $offset, $length, @list;
449 }
450 UNTIE this
452 Will be called when "untie" happens. (See "The "untie" Gotcha"
453 below.)
454 DESTROY this
456 This method will be triggered when the tied variable needs to be
457 destructed. As with the scalar tie class, this is almost never
458 needed in a language that does its own garbage collection, so this
459 time we'll just leave it out.
460 Tying Hashes
462 Hashes were the first Perl data type to be tied (see dbmopen()). A
463 class implementing a tied hash should define the following methods:
464 TIEHASH is the constructor. FETCH and STORE access the key and value
465 pairs. EXISTS reports whether a key is present in the hash, and DELETE
466 deletes one. CLEAR empties the hash by deleting all the key and value
467 pairs. FIRSTKEY and NEXTKEY implement the keys() and each() functions
468 to iterate over all the keys. SCALAR is triggered when the tied hash is
469 evaluated in scalar context, and in 5.28 onwards, by "keys" in boolean
470 context. UNTIE is called when "untie" happens, and DESTROY is called
471 when the tied variable is garbage collected.
472 If this seems like a lot, then feel free to inherit from merely the
474 standard Tie::StdHash module for most of your methods, redefining only
475 the interesting ones. See Tie::Hash for details.
476 Remember that Perl distinguishes between a key not existing in the
478 hash, and the key existing in the hash but having a corresponding value
479 of "undef". The two possibilities can be tested with the "exists()"
480 and "defined()" functions.
481 Here's an example of a somewhat interesting tied hash class: it gives
483 you a hash representing a particular user's dot files. You index into
484 the hash with the name of the file (minus the dot) and you get back
485 that dot file's contents. For example:
486 use DotFiles;
488 tie %dot, 'DotFiles';
489 if ( $dot{profile} =~ /MANPATH/ ||
490 $dot{login} =~ /MANPATH/ ||
491 $dot{cshrc} =~ /MANPATH/ )
492 {
493 print "you seem to set your MANPATH\n";
494 }
495 Or here's another sample of using our tied class:
497 tie %him, 'DotFiles', 'daemon';
499 foreach $f ( keys %him ) {
500 printf "daemon dot file %s is size %d\n",
501 $f, length $him{$f};
502 }
503 In our tied hash DotFiles example, we use a regular hash for the object
505 containing several important fields, of which only the "{LIST}" field
506 will be what the user thinks of as the real hash.
507 USER whose dot files this object represents
509 HOME where those dot files live
511 CLOBBER
513 whether we should try to change or remove those dot files
514 LIST the hash of dot file names and content mappings
516 Here's the start of Dotfiles.pm:
518 package DotFiles;
520 use Carp;
521 sub whowasi { (caller(1))[3] . '()' }
522 my $DEBUG = 0;
523 sub debug { $DEBUG = @_ ? shift : 1 }
524 For our example, we want to be able to emit debugging info to help in
526 tracing during development. We keep also one convenience function
527 around internally to help print out warnings; whowasi() returns the
528 function name that calls it.
529 Here are the methods for the DotFiles tied hash.
531 TIEHASH classname, LIST
533 This is the constructor for the class. That means it is expected
534 to return a blessed reference through which the new object
535 (probably but not necessarily an anonymous hash) will be accessed.
536 Here's the constructor:
538 sub TIEHASH {
540 my $class = shift;
541 my $user = shift || $>;
542 my $dotdir = shift || '';
543 croak "usage: @{[&whowasi]} [USER [DOTDIR]]" if @_;
544 $user = getpwuid($user) if $user =~ /^\d+$/;
545 my $dir = (getpwnam($user))[7]
546 || croak "@{[&whowasi]}: no user $user";
547 $dir .= "/$dotdir" if $dotdir;
548 my $node = {
550 USER => $user,
551 HOME => $dir,
552 LIST => {},
553 CLOBBER => 0,
554 };
555 opendir(DIR, $dir)
557 || croak "@{[&whowasi]}: can't opendir $dir: $!";
558 foreach $dot ( grep /^\./ && -f "$dir/$_", readdir(DIR)) {
559 $dot =~ s/^\.//;
560 $node->{LIST}{$dot} = undef;
561 }
562 closedir DIR;
563 return bless $node, $class;
564 }
565 It's probably worth mentioning that if you're going to filetest the
567 return values out of a readdir, you'd better prepend the directory
568 in question. Otherwise, because we didn't chdir() there, it would
569 have been testing the wrong file.
570 FETCH this, key
572 This method will be triggered every time an element in the tied
573 hash is accessed (read). It takes one argument beyond its self
574 reference: the key whose value we're trying to fetch.
575 Here's the fetch for our DotFiles example.
577 sub FETCH {
579 carp &whowasi if $DEBUG;
580 my $self = shift;
581 my $dot = shift;
582 my $dir = $self->{HOME};
583 my $file = "$dir/.$dot";
584 unless (exists $self->{LIST}->{$dot} || -f $file) {
586 carp "@{[&whowasi]}: no $dot file" if $DEBUG;
587 return undef;
588 }
589 if (defined $self->{LIST}->{$dot}) {
591 return $self->{LIST}->{$dot};
592 } else {
593 return $self->{LIST}->{$dot} = `cat $dir/.$dot`;
594 }
595 }
596 It was easy to write by having it call the Unix cat(1) command, but
598 it would probably be more portable to open the file manually (and
599 somewhat more efficient). Of course, because dot files are a Unixy
600 concept, we're not that concerned.
601 STORE this, key, value
603 This method will be triggered every time an element in the tied
604 hash is set (written). It takes two arguments beyond its self
605 reference: the index at which we're trying to store something, and
606 the value we're trying to put there.
607 Here in our DotFiles example, we'll be careful not to let them try
609 to overwrite the file unless they've called the clobber() method on
610 the original object reference returned by tie().
611 sub STORE {
613 carp &whowasi if $DEBUG;
614 my $self = shift;
615 my $dot = shift;
616 my $value = shift;
617 my $file = $self->{HOME} . "/.$dot";
618 my $user = $self->{USER};
619 croak "@{[&whowasi]}: $file not clobberable"
621 unless $self->{CLOBBER};
622 open(my $f, '>', $file) || croak "can't open $file: $!";
624 print $f $value;
625 close($f);
626 }
627 If they wanted to clobber something, they might say:
629 $ob = tie %daemon_dots, 'daemon';
631 $ob->clobber(1);
632 $daemon_dots{signature} = "A true daemon\n";
633 Another way to lay hands on a reference to the underlying object is
635 to use the tied() function, so they might alternately have set
636 clobber using:
637 tie %daemon_dots, 'daemon';
639 tied(%daemon_dots)->clobber(1);
640 The clobber method is simply:
642 sub clobber {
644 my $self = shift;
645 $self->{CLOBBER} = @_ ? shift : 1;
646 }
647 DELETE this, key
649 This method is triggered when we remove an element from the hash,
650 typically by using the delete() function. Again, we'll be careful
651 to check whether they really want to clobber files.
652 sub DELETE {
654 carp &whowasi if $DEBUG;
655 my $self = shift;
657 my $dot = shift;
658 my $file = $self->{HOME} . "/.$dot";
659 croak "@{[&whowasi]}: won't remove file $file"
660 unless $self->{CLOBBER};
661 delete $self->{LIST}->{$dot};
662 my $success = unlink($file);
663 carp "@{[&whowasi]}: can't unlink $file: $!" unless $success;
664 $success;
665 }
666 The value returned by DELETE becomes the return value of the call
668 to delete(). If you want to emulate the normal behavior of
669 delete(), you should return whatever FETCH would have returned for
670 this key. In this example, we have chosen instead to return a
671 value which tells the caller whether the file was successfully
672 deleted.
673 CLEAR this
675 This method is triggered when the whole hash is to be cleared,
676 usually by assigning the empty list to it.
677 In our example, that would remove all the user's dot files! It's
679 such a dangerous thing that they'll have to set CLOBBER to
680 something higher than 1 to make it happen.
681 sub CLEAR {
683 carp &whowasi if $DEBUG;
684 my $self = shift;
685 croak "@{[&whowasi]}: won't remove all dot files for $self->{USER}"
686 unless $self->{CLOBBER} > 1;
687 my $dot;
688 foreach $dot ( keys $self->{LIST}->%* ) {
689 $self->DELETE($dot);
690 }
691 }
692 EXISTS this, key
694 This method is triggered when the user uses the exists() function
695 on a particular hash. In our example, we'll look at the "{LIST}"
696 hash element for this:
697 sub EXISTS {
699 carp &whowasi if $DEBUG;
700 my $self = shift;
701 my $dot = shift;
702 return exists $self->{LIST}->{$dot};
703 }
704 FIRSTKEY this
706 This method will be triggered when the user is going to iterate
707 through the hash, such as via a keys(), values(), or each() call.
708 sub FIRSTKEY {
710 carp &whowasi if $DEBUG;
711 my $self = shift;
712 my $a = keys $self->{LIST}->%*; # reset each() iterator
713 each $self->{LIST}->%*
714 }
715 FIRSTKEY is always called in scalar context and it should just
717 return the first key. values(), and each() in list context, will
718 call FETCH for the returned keys.
719 NEXTKEY this, lastkey
721 This method gets triggered during a keys(), values(), or each()
722 iteration. It has a second argument which is the last key that had
723 been accessed. This is useful if you're caring about ordering or
724 calling the iterator from more than one sequence, or not really
725 storing things in a hash anywhere.
726 NEXTKEY is always called in scalar context and it should just
728 return the next key. values(), and each() in list context, will
729 call FETCH for the returned keys.
730 For our example, we're using a real hash so we'll do just the
732 simple thing, but we'll have to go through the LIST field
733 indirectly.
734 sub NEXTKEY {
736 carp &whowasi if $DEBUG;
737 my $self = shift;
738 return each $self->{LIST}->%*
739 }
740 If the object underlying your tied hash isn't a real hash and you
742 don't have "each" available, then you should return "undef" or the
743 empty list once you've reached the end of your list of keys. See
744 "each's own documentation" for more details.
745 SCALAR this
747 This is called when the hash is evaluated in scalar context, and in
748 5.28 onwards, by "keys" in boolean context. In order to mimic the
749 behaviour of untied hashes, this method must return a value which
750 when used as boolean, indicates whether the tied hash is considered
751 empty. If this method does not exist, perl will make some educated
752 guesses and return true when the hash is inside an iteration. If
753 this isn't the case, FIRSTKEY is called, and the result will be a
754 false value if FIRSTKEY returns the empty list, true otherwise.
755 However, you should not blindly rely on perl always doing the right
757 thing. Particularly, perl will mistakenly return true when you
758 clear the hash by repeatedly calling DELETE until it is empty. You
759 are therefore advised to supply your own SCALAR method when you
760 want to be absolutely sure that your hash behaves nicely in scalar
761 context.
762 In our example we can just call "scalar" on the underlying hash
764 referenced by "$self->{LIST}":
765 sub SCALAR {
767 carp &whowasi if $DEBUG;
768 my $self = shift;
769 return scalar $self->{LIST}->%*
770 }
771 NOTE: In perl 5.25 the behavior of scalar %hash on an untied hash
773 changed to return the count of keys. Prior to this it returned a
774 string containing information about the bucket setup of the hash.
775 See "bucket_ratio" in Hash::Util for a backwards compatibility
776 path.
777 UNTIE this
779 This is called when "untie" occurs. See "The "untie" Gotcha"
780 below.
781 DESTROY this
783 This method is triggered when a tied hash is about to go out of
784 scope. You don't really need it unless you're trying to add
785 debugging or have auxiliary state to clean up. Here's a very
786 simple function:
787 sub DESTROY {
789 carp &whowasi if $DEBUG;
790 }
791 Note that functions such as keys() and values() may return huge lists
793 when used on large objects, like DBM files. You may prefer to use the
794 each() function to iterate over such. Example:
795 # print out history file offsets
797 use NDBM_File;
798 tie(%HIST, 'NDBM_File', '/usr/lib/news/history', 1, 0);
799 while (($key,$val) = each %HIST) {
800 print $key, ' = ', unpack('L',$val), "\n";
801 }
802 untie(%HIST);
803 Tying FileHandles
805 This is partially implemented now.
806 A class implementing a tied filehandle should define the following
808 methods: TIEHANDLE, at least one of PRINT, PRINTF, WRITE, READLINE,
809 GETC, READ, and possibly CLOSE, UNTIE and DESTROY. The class can also
810 provide: BINMODE, OPEN, EOF, FILENO, SEEK, TELL - if the corresponding
811 perl operators are used on the handle.
812 When STDERR is tied, its PRINT method will be called to issue warnings
814 and error messages. This feature is temporarily disabled during the
815 call, which means you can use "warn()" inside PRINT without starting a
816 recursive loop. And just like "__WARN__" and "__DIE__" handlers,
817 STDERR's PRINT method may be called to report parser errors, so the
818 caveats mentioned under "%SIG" in perlvar apply.
819 All of this is especially useful when perl is embedded in some other
821 program, where output to STDOUT and STDERR may have to be redirected in
822 some special way. See nvi and the Apache module for examples.
823 When tying a handle, the first argument to "tie" should begin with an
825 asterisk. So, if you are tying STDOUT, use *STDOUT. If you have
826 assigned it to a scalar variable, say $handle, use *$handle. "tie
827 $handle" ties the scalar variable $handle, not the handle inside it.
828 In our example we're going to create a shouting handle.
830 package Shout;
832 TIEHANDLE classname, LIST
834 This is the constructor for the class. That means it is expected
835 to return a blessed reference of some sort. The reference can be
836 used to hold some internal information.
837 sub TIEHANDLE { print "<shout>\n"; my $i; bless \$i, shift }
839 WRITE this, LIST
841 This method will be called when the handle is written to via the
842 "syswrite" function.
843 sub WRITE {
845 $r = shift;
846 my($buf,$len,$offset) = @_;
847 print "WRITE called, \$buf=$buf, \$len=$len, \$offset=$offset";
848 }
849 PRINT this, LIST
851 This method will be triggered every time the tied handle is printed
852 to with the "print()" or "say()" functions. Beyond its self
853 reference it also expects the list that was passed to the print
854 function.
855 sub PRINT { $r = shift; $$r++; print join($,,map(uc($_),@_)),$\ }
857 "say()" acts just like "print()" except $\ will be localized to
859 "\n" so you need do nothing special to handle "say()" in "PRINT()".
860 PRINTF this, LIST
862 This method will be triggered every time the tied handle is printed
863 to with the "printf()" function. Beyond its self reference it also
864 expects the format and list that was passed to the printf function.
865 sub PRINTF {
867 shift;
868 my $fmt = shift;
869 print sprintf($fmt, @_);
870 }
871 READ this, LIST
873 This method will be called when the handle is read from via the
874 "read" or "sysread" functions.
875 sub READ {
877 my $self = shift;
878 my $bufref = \$_[0];
879 my(undef,$len,$offset) = @_;
880 print "READ called, \$buf=$bufref, \$len=$len, \$offset=$offset";
881 # add to $$bufref, set $len to number of characters read
882 $len;
883 }
884 READLINE this
886 This method is called when the handle is read via "<HANDLE>" or
887 "readline HANDLE".
888 As per "readline", in scalar context it should return the next
890 line, or "undef" for no more data. In list context it should
891 return all remaining lines, or an empty list for no more data. The
892 strings returned should include the input record separator $/ (see
893 perlvar), unless it is "undef" (which means "slurp" mode).
894 sub READLINE {
896 my $r = shift;
897 if (wantarray) {
898 return ("all remaining\n",
899 "lines up\n",
900 "to eof\n");
901 } else {
902 return "READLINE called " . ++$$r . " times\n";
903 }
904 }
905 GETC this
907 This method will be called when the "getc" function is called.
908 sub GETC { print "Don't GETC, Get Perl"; return "a"; }
910 EOF this
912 This method will be called when the "eof" function is called.
913 Starting with Perl 5.12, an additional integer parameter will be
915 passed. It will be zero if "eof" is called without parameter; 1 if
916 "eof" is given a filehandle as a parameter, e.g. "eof(FH)"; and 2
917 in the very special case that the tied filehandle is "ARGV" and
918 "eof" is called with an empty parameter list, e.g. "eof()".
919 sub EOF { not length $stringbuf }
921 CLOSE this
923 This method will be called when the handle is closed via the
924 "close" function.
925 sub CLOSE { print "CLOSE called.\n" }
927 UNTIE this
929 As with the other types of ties, this method will be called when
930 "untie" happens. It may be appropriate to "auto CLOSE" when this
931 occurs. See "The "untie" Gotcha" below.
932 DESTROY this
934 As with the other types of ties, this method will be called when
935 the tied handle is about to be destroyed. This is useful for
936 debugging and possibly cleaning up.
937 sub DESTROY { print "</shout>\n" }
939 Here's how to use our little example:
941 tie(*FOO,'Shout');
943 print FOO "hello\n";
944 $a = 4; $b = 6;
945 print FOO $a, " plus ", $b, " equals ", $a + $b, "\n";
946 print <FOO>;
947 UNTIE this
949 You can define for all tie types an UNTIE method that will be called at
950 untie(). See "The "untie" Gotcha" below.
951 The "untie" Gotcha
953 If you intend making use of the object returned from either tie() or
954 tied(), and if the tie's target class defines a destructor, there is a
955 subtle gotcha you must guard against.
956 As setup, consider this (admittedly rather contrived) example of a tie;
958 all it does is use a file to keep a log of the values assigned to a
959 scalar.
960 package Remember;
962 use v5.36;
964 use IO::File;
965 sub TIESCALAR {
967 my $class = shift;
968 my $filename = shift;
969 my $handle = IO::File->new( "> $filename" )
970 or die "Cannot open $filename: $!\n";
971 print $handle "The Start\n";
973 bless {FH => $handle, Value => 0}, $class;
974 }
975 sub FETCH {
977 my $self = shift;
978 return $self->{Value};
979 }
980 sub STORE {
982 my $self = shift;
983 my $value = shift;
984 my $handle = $self->{FH};
985 print $handle "$value\n";
986 $self->{Value} = $value;
987 }
988 sub DESTROY {
990 my $self = shift;
991 my $handle = $self->{FH};
992 print $handle "The End\n";
993 close $handle;
994 }
995 1;
997 Here is an example that makes use of this tie:
999 use strict;
1001 use Remember;
1002 my $fred;
1004 tie $fred, 'Remember', 'myfile.txt';
1005 $fred = 1;
1006 $fred = 4;
1007 $fred = 5;
1008 untie $fred;
1009 system "cat myfile.txt";
1010 This is the output when it is executed:
1012 The Start
1014 1
1015 4
1016 5
1017 The End
1018 So far so good. Those of you who have been paying attention will have
1020 spotted that the tied object hasn't been used so far. So lets add an
1021 extra method to the Remember class to allow comments to be included in
1022 the file; say, something like this:
1023 sub comment {
1025 my $self = shift;
1026 my $text = shift;
1027 my $handle = $self->{FH};
1028 print $handle $text, "\n";
1029 }
1030 And here is the previous example modified to use the "comment" method
1032 (which requires the tied object):
1033 use strict;
1035 use Remember;
1036 my ($fred, $x);
1038 $x = tie $fred, 'Remember', 'myfile.txt';
1039 $fred = 1;
1040 $fred = 4;
1041 comment $x "changing...";
1042 $fred = 5;
1043 untie $fred;
1044 system "cat myfile.txt";
1045 When this code is executed there is no output. Here's why:
1047 When a variable is tied, it is associated with the object which is the
1049 return value of the TIESCALAR, TIEARRAY, or TIEHASH function. This
1050 object normally has only one reference, namely, the implicit reference
1051 from the tied variable. When untie() is called, that reference is
1052 destroyed. Then, as in the first example above, the object's
1053 destructor (DESTROY) is called, which is normal for objects that have
1054 no more valid references; and thus the file is closed.
1055 In the second example, however, we have stored another reference to the
1057 tied object in $x. That means that when untie() gets called there will
1058 still be a valid reference to the object in existence, so the
1059 destructor is not called at that time, and thus the file is not closed.
1060 The reason there is no output is because the file buffers have not been
1061 flushed to disk.
1062 Now that you know what the problem is, what can you do to avoid it?
1064 Prior to the introduction of the optional UNTIE method the only way was
1065 the good old "-w" flag. Which will spot any instances where you call
1066 untie() and there are still valid references to the tied object. If
1067 the second script above this near the top "use warnings 'untie'" or was
1068 run with the "-w" flag, Perl prints this warning message:
1069 untie attempted while 1 inner references still exist
1071 To get the script to work properly and silence the warning make sure
1073 there are no valid references to the tied object before untie() is
1074 called:
1075 undef $x;
1077 untie $fred;
1078 Now that UNTIE exists the class designer can decide which parts of the
1080 class functionality are really associated with "untie" and which with
1081 the object being destroyed. What makes sense for a given class depends
1082 on whether the inner references are being kept so that non-tie-related
1083 methods can be called on the object. But in most cases it probably
1084 makes sense to move the functionality that would have been in DESTROY
1085 to the UNTIE method.
1086 If the UNTIE method exists then the warning above does not occur.
1088 Instead the UNTIE method is passed the count of "extra" references and
1089 can issue its own warning if appropriate. e.g. to replicate the no
1090 UNTIE case this method can be used:
1091 sub UNTIE
1093 {
1094 my ($obj,$count) = @_;
1095 carp "untie attempted while $count inner references still exist"
1096 if $count;
1097 }
1098
1100 See DB_File or Config for some interesting tie() implementations. A
1101 good starting point for many tie() implementations is with one of the
1102 modules Tie::Scalar, Tie::Array, Tie::Hash, or Tie::Handle.
1103
1105 The normal return provided by "scalar(%hash)" is not available. What
1106 this means is that using %tied_hash in boolean context doesn't work
1107 right (currently this always tests false, regardless of whether the
1108 hash is empty or hash elements). [ This paragraph needs review in
1109 light of changes in 5.25 ]
1110 Localizing tied arrays or hashes does not work. After exiting the
1112 scope the arrays or the hashes are not restored.
1113 Counting the number of entries in a hash via "scalar(keys(%hash))" or
1115 "scalar(values(%hash)") is inefficient since it needs to iterate
1116 through all the entries with FIRSTKEY/NEXTKEY.
1117 Tied hash/array slices cause multiple FETCH/STORE pairs, there are no
1119 tie methods for slice operations.
1120 You cannot easily tie a multilevel data structure (such as a hash of
1122 hashes) to a dbm file. The first problem is that all but GDBM and
1123 Berkeley DB have size limitations, but beyond that, you also have
1124 problems with how references are to be represented on disk. One module
1125 that does attempt to address this need is DBM::Deep. Check your
1126 nearest CPAN site as described in perlmodlib for source code. Note
1127 that despite its name, DBM::Deep does not use dbm. Another earlier
1128 attempt at solving the problem is MLDBM, which is also available on the
1129 CPAN, but which has some fairly serious limitations.
1130 Tied filehandles are still incomplete. sysopen(), truncate(), flock(),
1132 fcntl(), stat() and -X can't currently be trapped.
1133
1135 Tom Christiansen
1136 TIEHANDLE by Sven Verdoolaege <skimo@dns.ufsia.ac.be> and Doug
1138 MacEachern <dougm@osf.org>
1139 UNTIE by Nick Ing-Simmons <nick@ing-simmons.net>
1141 SCALAR by Tassilo von Parseval <tassilo.von.parseval@rwth-aachen.de>
1143 Tying Arrays by Casey West <casey@geeknest.com>
1145perl v5.36.3 2023-11-30 PERLTIE(1)