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->EXTEND( $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, we want to make sure there are no blank ("undef")
330 entries, so "EXTEND" will make use of "STORESIZE" to fill elements
331 as needed:
332 sub EXTEND {
334 my $self = shift;
335 my $count = shift;
336 $self->STORESIZE( $count );
337 }
338 EXISTS this, key
340 Verify that the element at index key exists in the tied array this.
341 In our example, we will determine that if an element consists of
343 "$self->{ELEMSIZE}" spaces only, it does not exist:
344 sub EXISTS {
346 my $self = shift;
347 my $index = shift;
348 return 0 if ! defined $self->{ARRAY}->[$index] ||
349 $self->{ARRAY}->[$index] eq ' ' x $self->{ELEMSIZE};
350 return 1;
351 }
352 DELETE this, key
354 Delete the element at index key from the tied array this.
355 In our example, a deleted item is "$self->{ELEMSIZE}" spaces:
357 sub DELETE {
359 my $self = shift;
360 my $index = shift;
361 return $self->STORE( $index, '' );
362 }
363 CLEAR this
365 Clear (remove, delete, ...) all values from the tied array
366 associated with object this. For example:
367 sub CLEAR {
369 my $self = shift;
370 return $self->{ARRAY} = [];
371 }
372 PUSH this, LIST
374 Append elements of LIST to the array. For example:
375 sub PUSH {
377 my $self = shift;
378 my @list = @_;
379 my $last = $self->FETCHSIZE();
380 $self->STORE( $last + $_, $list[$_] ) foreach 0 .. $#list;
381 return $self->FETCHSIZE();
382 }
383 POP this
385 Remove last element of the array and return it. For example:
386 sub POP {
388 my $self = shift;
389 return pop @{$self->{ARRAY}};
390 }
391 SHIFT this
393 Remove the first element of the array (shifting other elements
394 down) and return it. For example:
395 sub SHIFT {
397 my $self = shift;
398 return shift @{$self->{ARRAY}};
399 }
400 UNSHIFT this, LIST
402 Insert LIST elements at the beginning of the array, moving existing
403 elements up to make room. For example:
404 sub UNSHIFT {
406 my $self = shift;
407 my @list = @_;
408 my $size = scalar( @list );
409 # make room for our list
410 @{$self->{ARRAY}}[ $size .. $#{$self->{ARRAY}} + $size ]
411 = @{$self->{ARRAY}};
412 $self->STORE( $_, $list[$_] ) foreach 0 .. $#list;
413 }
414 SPLICE this, offset, length, LIST
416 Perform the equivalent of "splice" on the array.
417 offset is optional and defaults to zero, negative values count back
419 from the end of the array.
420 length is optional and defaults to rest of the array.
422 LIST may be empty.
424 Returns a list of the original length elements at offset.
426 In our example, we'll use a little shortcut if there is a LIST:
428 sub SPLICE {
430 my $self = shift;
431 my $offset = shift || 0;
432 my $length = shift || $self->FETCHSIZE() - $offset;
433 my @list = ();
434 if ( @_ ) {
435 tie @list, __PACKAGE__, $self->{ELEMSIZE};
436 @list = @_;
437 }
438 return splice @{$self->{ARRAY}}, $offset, $length, @list;
439 }
440 UNTIE this
442 Will be called when "untie" happens. (See "The "untie" Gotcha"
443 below.)
444 DESTROY this
446 This method will be triggered when the tied variable needs to be
447 destructed. As with the scalar tie class, this is almost never
448 needed in a language that does its own garbage collection, so this
449 time we'll just leave it out.
450 Tying Hashes
452 Hashes were the first Perl data type to be tied (see dbmopen()). A
453 class implementing a tied hash should define the following methods:
454 TIEHASH is the constructor. FETCH and STORE access the key and value
455 pairs. EXISTS reports whether a key is present in the hash, and DELETE
456 deletes one. CLEAR empties the hash by deleting all the key and value
457 pairs. FIRSTKEY and NEXTKEY implement the keys() and each() functions
458 to iterate over all the keys. SCALAR is triggered when the tied hash is
459 evaluated in scalar context, and in 5.28 onwards, by "keys" in boolean
460 context. UNTIE is called when "untie" happens, and DESTROY is called
461 when the tied variable is garbage collected.
462 If this seems like a lot, then feel free to inherit from merely the
464 standard Tie::StdHash module for most of your methods, redefining only
465 the interesting ones. See Tie::Hash for details.
466 Remember that Perl distinguishes between a key not existing in the
468 hash, and the key existing in the hash but having a corresponding value
469 of "undef". The two possibilities can be tested with the "exists()"
470 and "defined()" functions.
471 Here's an example of a somewhat interesting tied hash class: it gives
473 you a hash representing a particular user's dot files. You index into
474 the hash with the name of the file (minus the dot) and you get back
475 that dot file's contents. For example:
476 use DotFiles;
478 tie %dot, 'DotFiles';
479 if ( $dot{profile} =~ /MANPATH/ ||
480 $dot{login} =~ /MANPATH/ ||
481 $dot{cshrc} =~ /MANPATH/ )
482 {
483 print "you seem to set your MANPATH\n";
484 }
485 Or here's another sample of using our tied class:
487 tie %him, 'DotFiles', 'daemon';
489 foreach $f ( keys %him ) {
490 printf "daemon dot file %s is size %d\n",
491 $f, length $him{$f};
492 }
493 In our tied hash DotFiles example, we use a regular hash for the object
495 containing several important fields, of which only the "{LIST}" field
496 will be what the user thinks of as the real hash.
497 USER whose dot files this object represents
499 HOME where those dot files live
501 CLOBBER
503 whether we should try to change or remove those dot files
504 LIST the hash of dot file names and content mappings
506 Here's the start of Dotfiles.pm:
508 package DotFiles;
510 use Carp;
511 sub whowasi { (caller(1))[3] . '()' }
512 my $DEBUG = 0;
513 sub debug { $DEBUG = @_ ? shift : 1 }
514 For our example, we want to be able to emit debugging info to help in
516 tracing during development. We keep also one convenience function
517 around internally to help print out warnings; whowasi() returns the
518 function name that calls it.
519 Here are the methods for the DotFiles tied hash.
521 TIEHASH classname, LIST
523 This is the constructor for the class. That means it is expected
524 to return a blessed reference through which the new object
525 (probably but not necessarily an anonymous hash) will be accessed.
526 Here's the constructor:
528 sub TIEHASH {
530 my $self = shift;
531 my $user = shift || $>;
532 my $dotdir = shift || '';
533 croak "usage: @{[&whowasi]} [USER [DOTDIR]]" if @_;
534 $user = getpwuid($user) if $user =~ /^\d+$/;
535 my $dir = (getpwnam($user))[7]
536 || croak "@{[&whowasi]}: no user $user";
537 $dir .= "/$dotdir" if $dotdir;
538 my $node = {
540 USER => $user,
541 HOME => $dir,
542 LIST => {},
543 CLOBBER => 0,
544 };
545 opendir(DIR, $dir)
547 || croak "@{[&whowasi]}: can't opendir $dir: $!";
548 foreach $dot ( grep /^\./ && -f "$dir/$_", readdir(DIR)) {
549 $dot =~ s/^\.//;
550 $node->{LIST}{$dot} = undef;
551 }
552 closedir DIR;
553 return bless $node, $self;
554 }
555 It's probably worth mentioning that if you're going to filetest the
557 return values out of a readdir, you'd better prepend the directory
558 in question. Otherwise, because we didn't chdir() there, it would
559 have been testing the wrong file.
560 FETCH this, key
562 This method will be triggered every time an element in the tied
563 hash is accessed (read). It takes one argument beyond its self
564 reference: the key whose value we're trying to fetch.
565 Here's the fetch for our DotFiles example.
567 sub FETCH {
569 carp &whowasi if $DEBUG;
570 my $self = shift;
571 my $dot = shift;
572 my $dir = $self->{HOME};
573 my $file = "$dir/.$dot";
574 unless (exists $self->{LIST}->{$dot} || -f $file) {
576 carp "@{[&whowasi]}: no $dot file" if $DEBUG;
577 return undef;
578 }
579 if (defined $self->{LIST}->{$dot}) {
581 return $self->{LIST}->{$dot};
582 } else {
583 return $self->{LIST}->{$dot} = `cat $dir/.$dot`;
584 }
585 }
586 It was easy to write by having it call the Unix cat(1) command, but
588 it would probably be more portable to open the file manually (and
589 somewhat more efficient). Of course, because dot files are a Unixy
590 concept, we're not that concerned.
591 STORE this, key, value
593 This method will be triggered every time an element in the tied
594 hash is set (written). It takes two arguments beyond its self
595 reference: the index at which we're trying to store something, and
596 the value we're trying to put there.
597 Here in our DotFiles example, we'll be careful not to let them try
599 to overwrite the file unless they've called the clobber() method on
600 the original object reference returned by tie().
601 sub STORE {
603 carp &whowasi if $DEBUG;
604 my $self = shift;
605 my $dot = shift;
606 my $value = shift;
607 my $file = $self->{HOME} . "/.$dot";
608 my $user = $self->{USER};
609 croak "@{[&whowasi]}: $file not clobberable"
611 unless $self->{CLOBBER};
612 open(my $f, '>', $file) || croak "can't open $file: $!";
614 print $f $value;
615 close($f);
616 }
617 If they wanted to clobber something, they might say:
619 $ob = tie %daemon_dots, 'daemon';
621 $ob->clobber(1);
622 $daemon_dots{signature} = "A true daemon\n";
623 Another way to lay hands on a reference to the underlying object is
625 to use the tied() function, so they might alternately have set
626 clobber using:
627 tie %daemon_dots, 'daemon';
629 tied(%daemon_dots)->clobber(1);
630 The clobber method is simply:
632 sub clobber {
634 my $self = shift;
635 $self->{CLOBBER} = @_ ? shift : 1;
636 }
637 DELETE this, key
639 This method is triggered when we remove an element from the hash,
640 typically by using the delete() function. Again, we'll be careful
641 to check whether they really want to clobber files.
642 sub DELETE {
644 carp &whowasi if $DEBUG;
645 my $self = shift;
647 my $dot = shift;
648 my $file = $self->{HOME} . "/.$dot";
649 croak "@{[&whowasi]}: won't remove file $file"
650 unless $self->{CLOBBER};
651 delete $self->{LIST}->{$dot};
652 my $success = unlink($file);
653 carp "@{[&whowasi]}: can't unlink $file: $!" unless $success;
654 $success;
655 }
656 The value returned by DELETE becomes the return value of the call
658 to delete(). If you want to emulate the normal behavior of
659 delete(), you should return whatever FETCH would have returned for
660 this key. In this example, we have chosen instead to return a
661 value which tells the caller whether the file was successfully
662 deleted.
663 CLEAR this
665 This method is triggered when the whole hash is to be cleared,
666 usually by assigning the empty list to it.
667 In our example, that would remove all the user's dot files! It's
669 such a dangerous thing that they'll have to set CLOBBER to
670 something higher than 1 to make it happen.
671 sub CLEAR {
673 carp &whowasi if $DEBUG;
674 my $self = shift;
675 croak "@{[&whowasi]}: won't remove all dot files for $self->{USER}"
676 unless $self->{CLOBBER} > 1;
677 my $dot;
678 foreach $dot ( keys %{$self->{LIST}}) {
679 $self->DELETE($dot);
680 }
681 }
682 EXISTS this, key
684 This method is triggered when the user uses the exists() function
685 on a particular hash. In our example, we'll look at the "{LIST}"
686 hash element for this:
687 sub EXISTS {
689 carp &whowasi if $DEBUG;
690 my $self = shift;
691 my $dot = shift;
692 return exists $self->{LIST}->{$dot};
693 }
694 FIRSTKEY this
696 This method will be triggered when the user is going to iterate
697 through the hash, such as via a keys(), values(), or each() call.
698 sub FIRSTKEY {
700 carp &whowasi if $DEBUG;
701 my $self = shift;
702 my $a = keys %{$self->{LIST}}; # reset each() iterator
703 each %{$self->{LIST}}
704 }
705 FIRSTKEY is always called in scalar context and it should just
707 return the first key. values(), and each() in list context, will
708 call FETCH for the returned keys.
709 NEXTKEY this, lastkey
711 This method gets triggered during a keys(), values(), or each()
712 iteration. It has a second argument which is the last key that had
713 been accessed. This is useful if you're caring about ordering or
714 calling the iterator from more than one sequence, or not really
715 storing things in a hash anywhere.
716 NEXTKEY is always called in scalar context and it should just
718 return the next key. values(), and each() in list context, will
719 call FETCH for the returned keys.
720 For our example, we're using a real hash so we'll do just the
722 simple thing, but we'll have to go through the LIST field
723 indirectly.
724 sub NEXTKEY {
726 carp &whowasi if $DEBUG;
727 my $self = shift;
728 return each %{ $self->{LIST} }
729 }
730 SCALAR this
732 This is called when the hash is evaluated in scalar context, and in
733 5.28 onwards, by "keys" in boolean context. In order to mimic the
734 behaviour of untied hashes, this method must return a value which
735 when used as boolean, indicates whether the tied hash is considered
736 empty. If this method does not exist, perl will make some educated
737 guesses and return true when the hash is inside an iteration. If
738 this isn't the case, FIRSTKEY is called, and the result will be a
739 false value if FIRSTKEY returns the empty list, true otherwise.
740 However, you should not blindly rely on perl always doing the right
742 thing. Particularly, perl will mistakenly return true when you
743 clear the hash by repeatedly calling DELETE until it is empty. You
744 are therefore advised to supply your own SCALAR method when you
745 want to be absolutely sure that your hash behaves nicely in scalar
746 context.
747 In our example we can just call "scalar" on the underlying hash
749 referenced by "$self->{LIST}":
750 sub SCALAR {
752 carp &whowasi if $DEBUG;
753 my $self = shift;
754 return scalar %{ $self->{LIST} }
755 }
756 NOTE: In perl 5.25 the behavior of scalar %hash on an untied hash
758 changed to return the count of keys. Prior to this it returned a
759 string containing information about the bucket setup of the hash.
760 See "bucket_ratio" in Hash::Util for a backwards compatibility
761 path.
762 UNTIE this
764 This is called when "untie" occurs. See "The "untie" Gotcha"
765 below.
766 DESTROY this
768 This method is triggered when a tied hash is about to go out of
769 scope. You don't really need it unless you're trying to add
770 debugging or have auxiliary state to clean up. Here's a very
771 simple function:
772 sub DESTROY {
774 carp &whowasi if $DEBUG;
775 }
776 Note that functions such as keys() and values() may return huge lists
778 when used on large objects, like DBM files. You may prefer to use the
779 each() function to iterate over such. Example:
780 # print out history file offsets
782 use NDBM_File;
783 tie(%HIST, 'NDBM_File', '/usr/lib/news/history', 1, 0);
784 while (($key,$val) = each %HIST) {
785 print $key, ' = ', unpack('L',$val), "\n";
786 }
787 untie(%HIST);
788 Tying FileHandles
790 This is partially implemented now.
791 A class implementing a tied filehandle should define the following
793 methods: TIEHANDLE, at least one of PRINT, PRINTF, WRITE, READLINE,
794 GETC, READ, and possibly CLOSE, UNTIE and DESTROY. The class can also
795 provide: BINMODE, OPEN, EOF, FILENO, SEEK, TELL - if the corresponding
796 perl operators are used on the handle.
797 When STDERR is tied, its PRINT method will be called to issue warnings
799 and error messages. This feature is temporarily disabled during the
800 call, which means you can use "warn()" inside PRINT without starting a
801 recursive loop. And just like "__WARN__" and "__DIE__" handlers,
802 STDERR's PRINT method may be called to report parser errors, so the
803 caveats mentioned under "%SIG" in perlvar apply.
804 All of this is especially useful when perl is embedded in some other
806 program, where output to STDOUT and STDERR may have to be redirected in
807 some special way. See nvi and the Apache module for examples.
808 When tying a handle, the first argument to "tie" should begin with an
810 asterisk. So, if you are tying STDOUT, use *STDOUT. If you have
811 assigned it to a scalar variable, say $handle, use *$handle. "tie
812 $handle" ties the scalar variable $handle, not the handle inside it.
813 In our example we're going to create a shouting handle.
815 package Shout;
817 TIEHANDLE classname, LIST
819 This is the constructor for the class. That means it is expected
820 to return a blessed reference of some sort. The reference can be
821 used to hold some internal information.
822 sub TIEHANDLE { print "<shout>\n"; my $i; bless \$i, shift }
824 WRITE this, LIST
826 This method will be called when the handle is written to via the
827 "syswrite" function.
828 sub WRITE {
830 $r = shift;
831 my($buf,$len,$offset) = @_;
832 print "WRITE called, \$buf=$buf, \$len=$len, \$offset=$offset";
833 }
834 PRINT this, LIST
836 This method will be triggered every time the tied handle is printed
837 to with the "print()" or "say()" functions. Beyond its self
838 reference it also expects the list that was passed to the print
839 function.
840 sub PRINT { $r = shift; $$r++; print join($,,map(uc($_),@_)),$\ }
842 "say()" acts just like "print()" except $\ will be localized to
844 "\n" so you need do nothing special to handle "say()" in "PRINT()".
845 PRINTF this, LIST
847 This method will be triggered every time the tied handle is printed
848 to with the "printf()" function. Beyond its self reference it also
849 expects the format and list that was passed to the printf function.
850 sub PRINTF {
852 shift;
853 my $fmt = shift;
854 print sprintf($fmt, @_);
855 }
856 READ this, LIST
858 This method will be called when the handle is read from via the
859 "read" or "sysread" functions.
860 sub READ {
862 my $self = shift;
863 my $bufref = \$_[0];
864 my(undef,$len,$offset) = @_;
865 print "READ called, \$buf=$bufref, \$len=$len, \$offset=$offset";
866 # add to $$bufref, set $len to number of characters read
867 $len;
868 }
869 READLINE this
871 This method is called when the handle is read via "<HANDLE>" or
872 "readline HANDLE".
873 As per "readline", in scalar context it should return the next
875 line, or "undef" for no more data. In list context it should
876 return all remaining lines, or an empty list for no more data. The
877 strings returned should include the input record separator $/ (see
878 perlvar), unless it is "undef" (which means "slurp" mode).
879 sub READLINE {
881 my $r = shift;
882 if (wantarray) {
883 return ("all remaining\n",
884 "lines up\n",
885 "to eof\n");
886 } else {
887 return "READLINE called " . ++$$r . " times\n";
888 }
889 }
890 GETC this
892 This method will be called when the "getc" function is called.
893 sub GETC { print "Don't GETC, Get Perl"; return "a"; }
895 EOF this
897 This method will be called when the "eof" function is called.
898 Starting with Perl 5.12, an additional integer parameter will be
900 passed. It will be zero if "eof" is called without parameter; 1 if
901 "eof" is given a filehandle as a parameter, e.g. "eof(FH)"; and 2
902 in the very special case that the tied filehandle is "ARGV" and
903 "eof" is called with an empty parameter list, e.g. "eof()".
904 sub EOF { not length $stringbuf }
906 CLOSE this
908 This method will be called when the handle is closed via the
909 "close" function.
910 sub CLOSE { print "CLOSE called.\n" }
912 UNTIE this
914 As with the other types of ties, this method will be called when
915 "untie" happens. It may be appropriate to "auto CLOSE" when this
916 occurs. See "The "untie" Gotcha" below.
917 DESTROY this
919 As with the other types of ties, this method will be called when
920 the tied handle is about to be destroyed. This is useful for
921 debugging and possibly cleaning up.
922 sub DESTROY { print "</shout>\n" }
924 Here's how to use our little example:
926 tie(*FOO,'Shout');
928 print FOO "hello\n";
929 $a = 4; $b = 6;
930 print FOO $a, " plus ", $b, " equals ", $a + $b, "\n";
931 print <FOO>;
932 UNTIE this
934 You can define for all tie types an UNTIE method that will be called at
935 untie(). See "The "untie" Gotcha" below.
936 The "untie" Gotcha
938 If you intend making use of the object returned from either tie() or
939 tied(), and if the tie's target class defines a destructor, there is a
940 subtle gotcha you must guard against.
941 As setup, consider this (admittedly rather contrived) example of a tie;
943 all it does is use a file to keep a log of the values assigned to a
944 scalar.
945 package Remember;
947 use strict;
949 use warnings;
950 use IO::File;
951 sub TIESCALAR {
953 my $class = shift;
954 my $filename = shift;
955 my $handle = IO::File->new( "> $filename" )
956 or die "Cannot open $filename: $!\n";
957 print $handle "The Start\n";
959 bless {FH => $handle, Value => 0}, $class;
960 }
961 sub FETCH {
963 my $self = shift;
964 return $self->{Value};
965 }
966 sub STORE {
968 my $self = shift;
969 my $value = shift;
970 my $handle = $self->{FH};
971 print $handle "$value\n";
972 $self->{Value} = $value;
973 }
974 sub DESTROY {
976 my $self = shift;
977 my $handle = $self->{FH};
978 print $handle "The End\n";
979 close $handle;
980 }
981 1;
983 Here is an example that makes use of this tie:
985 use strict;
987 use Remember;
988 my $fred;
990 tie $fred, 'Remember', 'myfile.txt';
991 $fred = 1;
992 $fred = 4;
993 $fred = 5;
994 untie $fred;
995 system "cat myfile.txt";
996 This is the output when it is executed:
998 The Start
1000 1
1001 4
1002 5
1003 The End
1004 So far so good. Those of you who have been paying attention will have
1006 spotted that the tied object hasn't been used so far. So lets add an
1007 extra method to the Remember class to allow comments to be included in
1008 the file; say, something like this:
1009 sub comment {
1011 my $self = shift;
1012 my $text = shift;
1013 my $handle = $self->{FH};
1014 print $handle $text, "\n";
1015 }
1016 And here is the previous example modified to use the "comment" method
1018 (which requires the tied object):
1019 use strict;
1021 use Remember;
1022 my ($fred, $x);
1024 $x = tie $fred, 'Remember', 'myfile.txt';
1025 $fred = 1;
1026 $fred = 4;
1027 comment $x "changing...";
1028 $fred = 5;
1029 untie $fred;
1030 system "cat myfile.txt";
1031 When this code is executed there is no output. Here's why:
1033 When a variable is tied, it is associated with the object which is the
1035 return value of the TIESCALAR, TIEARRAY, or TIEHASH function. This
1036 object normally has only one reference, namely, the implicit reference
1037 from the tied variable. When untie() is called, that reference is
1038 destroyed. Then, as in the first example above, the object's
1039 destructor (DESTROY) is called, which is normal for objects that have
1040 no more valid references; and thus the file is closed.
1041 In the second example, however, we have stored another reference to the
1043 tied object in $x. That means that when untie() gets called there will
1044 still be a valid reference to the object in existence, so the
1045 destructor is not called at that time, and thus the file is not closed.
1046 The reason there is no output is because the file buffers have not been
1047 flushed to disk.
1048 Now that you know what the problem is, what can you do to avoid it?
1050 Prior to the introduction of the optional UNTIE method the only way was
1051 the good old "-w" flag. Which will spot any instances where you call
1052 untie() and there are still valid references to the tied object. If
1053 the second script above this near the top "use warnings 'untie'" or was
1054 run with the "-w" flag, Perl prints this warning message:
1055 untie attempted while 1 inner references still exist
1057 To get the script to work properly and silence the warning make sure
1059 there are no valid references to the tied object before untie() is
1060 called:
1061 undef $x;
1063 untie $fred;
1064 Now that UNTIE exists the class designer can decide which parts of the
1066 class functionality are really associated with "untie" and which with
1067 the object being destroyed. What makes sense for a given class depends
1068 on whether the inner references are being kept so that non-tie-related
1069 methods can be called on the object. But in most cases it probably
1070 makes sense to move the functionality that would have been in DESTROY
1071 to the UNTIE method.
1072 If the UNTIE method exists then the warning above does not occur.
1074 Instead the UNTIE method is passed the count of "extra" references and
1075 can issue its own warning if appropriate. e.g. to replicate the no
1076 UNTIE case this method can be used:
1077 sub UNTIE
1079 {
1080 my ($obj,$count) = @_;
1081 carp "untie attempted while $count inner references still exist"
1082 if $count;
1083 }
1084
1086 See DB_File or Config for some interesting tie() implementations. A
1087 good starting point for many tie() implementations is with one of the
1088 modules Tie::Scalar, Tie::Array, Tie::Hash, or Tie::Handle.
1089
1091 The normal return provided by "scalar(%hash)" is not available. What
1092 this means is that using %tied_hash in boolean context doesn't work
1093 right (currently this always tests false, regardless of whether the
1094 hash is empty or hash elements). [ This paragraph needs review in
1095 light of changes in 5.25 ]
1096 Localizing tied arrays or hashes does not work. After exiting the
1098 scope the arrays or the hashes are not restored.
1099 Counting the number of entries in a hash via "scalar(keys(%hash))" or
1101 "scalar(values(%hash)") is inefficient since it needs to iterate
1102 through all the entries with FIRSTKEY/NEXTKEY.
1103 Tied hash/array slices cause multiple FETCH/STORE pairs, there are no
1105 tie methods for slice operations.
1106 You cannot easily tie a multilevel data structure (such as a hash of
1108 hashes) to a dbm file. The first problem is that all but GDBM and
1109 Berkeley DB have size limitations, but beyond that, you also have
1110 problems with how references are to be represented on disk. One module
1111 that does attempt to address this need is DBM::Deep. Check your
1112 nearest CPAN site as described in perlmodlib for source code. Note
1113 that despite its name, DBM::Deep does not use dbm. Another earlier
1114 attempt at solving the problem is MLDBM, which is also available on the
1115 CPAN, but which has some fairly serious limitations.
1116 Tied filehandles are still incomplete. sysopen(), truncate(), flock(),
1118 fcntl(), stat() and -X can't currently be trapped.
1119
1121 Tom Christiansen
1122 TIEHANDLE by Sven Verdoolaege <skimo@dns.ufsia.ac.be> and Doug
1124 MacEachern <dougm@osf.org>
1125 UNTIE by Nick Ing-Simmons <nick@ing-simmons.net>
1127 SCALAR by Tassilo von Parseval <tassilo.von.parseval@rwth-aachen.de>
1129 Tying Arrays by Casey West <casey@geeknest.com>
1131perl v5.30.1 2019-11-29 PERLTIE(1)