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 $self = 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, $self;
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 SCALAR this
742 This is called when the hash is evaluated in scalar context, and in
743 5.28 onwards, by "keys" in boolean context. In order to mimic the
744 behaviour of untied hashes, this method must return a value which
745 when used as boolean, indicates whether the tied hash is considered
746 empty. If this method does not exist, perl will make some educated
747 guesses and return true when the hash is inside an iteration. If
748 this isn't the case, FIRSTKEY is called, and the result will be a
749 false value if FIRSTKEY returns the empty list, true otherwise.
750 However, you should not blindly rely on perl always doing the right
752 thing. Particularly, perl will mistakenly return true when you
753 clear the hash by repeatedly calling DELETE until it is empty. You
754 are therefore advised to supply your own SCALAR method when you
755 want to be absolutely sure that your hash behaves nicely in scalar
756 context.
757 In our example we can just call "scalar" on the underlying hash
759 referenced by "$self->{LIST}":
760 sub SCALAR {
762 carp &whowasi if $DEBUG;
763 my $self = shift;
764 return scalar %{ $self->{LIST} }
765 }
766 NOTE: In perl 5.25 the behavior of scalar %hash on an untied hash
768 changed to return the count of keys. Prior to this it returned a
769 string containing information about the bucket setup of the hash.
770 See "bucket_ratio" in Hash::Util for a backwards compatibility
771 path.
772 UNTIE this
774 This is called when "untie" occurs. See "The "untie" Gotcha"
775 below.
776 DESTROY this
778 This method is triggered when a tied hash is about to go out of
779 scope. You don't really need it unless you're trying to add
780 debugging or have auxiliary state to clean up. Here's a very
781 simple function:
782 sub DESTROY {
784 carp &whowasi if $DEBUG;
785 }
786 Note that functions such as keys() and values() may return huge lists
788 when used on large objects, like DBM files. You may prefer to use the
789 each() function to iterate over such. Example:
790 # print out history file offsets
792 use NDBM_File;
793 tie(%HIST, 'NDBM_File', '/usr/lib/news/history', 1, 0);
794 while (($key,$val) = each %HIST) {
795 print $key, ' = ', unpack('L',$val), "\n";
796 }
797 untie(%HIST);
798 Tying FileHandles
800 This is partially implemented now.
801 A class implementing a tied filehandle should define the following
803 methods: TIEHANDLE, at least one of PRINT, PRINTF, WRITE, READLINE,
804 GETC, READ, and possibly CLOSE, UNTIE and DESTROY. The class can also
805 provide: BINMODE, OPEN, EOF, FILENO, SEEK, TELL - if the corresponding
806 perl operators are used on the handle.
807 When STDERR is tied, its PRINT method will be called to issue warnings
809 and error messages. This feature is temporarily disabled during the
810 call, which means you can use "warn()" inside PRINT without starting a
811 recursive loop. And just like "__WARN__" and "__DIE__" handlers,
812 STDERR's PRINT method may be called to report parser errors, so the
813 caveats mentioned under "%SIG" in perlvar apply.
814 All of this is especially useful when perl is embedded in some other
816 program, where output to STDOUT and STDERR may have to be redirected in
817 some special way. See nvi and the Apache module for examples.
818 When tying a handle, the first argument to "tie" should begin with an
820 asterisk. So, if you are tying STDOUT, use *STDOUT. If you have
821 assigned it to a scalar variable, say $handle, use *$handle. "tie
822 $handle" ties the scalar variable $handle, not the handle inside it.
823 In our example we're going to create a shouting handle.
825 package Shout;
827 TIEHANDLE classname, LIST
829 This is the constructor for the class. That means it is expected
830 to return a blessed reference of some sort. The reference can be
831 used to hold some internal information.
832 sub TIEHANDLE { print "<shout>\n"; my $i; bless \$i, shift }
834 WRITE this, LIST
836 This method will be called when the handle is written to via the
837 "syswrite" function.
838 sub WRITE {
840 $r = shift;
841 my($buf,$len,$offset) = @_;
842 print "WRITE called, \$buf=$buf, \$len=$len, \$offset=$offset";
843 }
844 PRINT this, LIST
846 This method will be triggered every time the tied handle is printed
847 to with the "print()" or "say()" functions. Beyond its self
848 reference it also expects the list that was passed to the print
849 function.
850 sub PRINT { $r = shift; $$r++; print join($,,map(uc($_),@_)),$\ }
852 "say()" acts just like "print()" except $\ will be localized to
854 "\n" so you need do nothing special to handle "say()" in "PRINT()".
855 PRINTF this, LIST
857 This method will be triggered every time the tied handle is printed
858 to with the "printf()" function. Beyond its self reference it also
859 expects the format and list that was passed to the printf function.
860 sub PRINTF {
862 shift;
863 my $fmt = shift;
864 print sprintf($fmt, @_);
865 }
866 READ this, LIST
868 This method will be called when the handle is read from via the
869 "read" or "sysread" functions.
870 sub READ {
872 my $self = shift;
873 my $bufref = \$_[0];
874 my(undef,$len,$offset) = @_;
875 print "READ called, \$buf=$bufref, \$len=$len, \$offset=$offset";
876 # add to $$bufref, set $len to number of characters read
877 $len;
878 }
879 READLINE this
881 This method is called when the handle is read via "<HANDLE>" or
882 "readline HANDLE".
883 As per "readline", in scalar context it should return the next
885 line, or "undef" for no more data. In list context it should
886 return all remaining lines, or an empty list for no more data. The
887 strings returned should include the input record separator $/ (see
888 perlvar), unless it is "undef" (which means "slurp" mode).
889 sub READLINE {
891 my $r = shift;
892 if (wantarray) {
893 return ("all remaining\n",
894 "lines up\n",
895 "to eof\n");
896 } else {
897 return "READLINE called " . ++$$r . " times\n";
898 }
899 }
900 GETC this
902 This method will be called when the "getc" function is called.
903 sub GETC { print "Don't GETC, Get Perl"; return "a"; }
905 EOF this
907 This method will be called when the "eof" function is called.
908 Starting with Perl 5.12, an additional integer parameter will be
910 passed. It will be zero if "eof" is called without parameter; 1 if
911 "eof" is given a filehandle as a parameter, e.g. "eof(FH)"; and 2
912 in the very special case that the tied filehandle is "ARGV" and
913 "eof" is called with an empty parameter list, e.g. "eof()".
914 sub EOF { not length $stringbuf }
916 CLOSE this
918 This method will be called when the handle is closed via the
919 "close" function.
920 sub CLOSE { print "CLOSE called.\n" }
922 UNTIE this
924 As with the other types of ties, this method will be called when
925 "untie" happens. It may be appropriate to "auto CLOSE" when this
926 occurs. See "The "untie" Gotcha" below.
927 DESTROY this
929 As with the other types of ties, this method will be called when
930 the tied handle is about to be destroyed. This is useful for
931 debugging and possibly cleaning up.
932 sub DESTROY { print "</shout>\n" }
934 Here's how to use our little example:
936 tie(*FOO,'Shout');
938 print FOO "hello\n";
939 $a = 4; $b = 6;
940 print FOO $a, " plus ", $b, " equals ", $a + $b, "\n";
941 print <FOO>;
942 UNTIE this
944 You can define for all tie types an UNTIE method that will be called at
945 untie(). See "The "untie" Gotcha" below.
946 The "untie" Gotcha
948 If you intend making use of the object returned from either tie() or
949 tied(), and if the tie's target class defines a destructor, there is a
950 subtle gotcha you must guard against.
951 As setup, consider this (admittedly rather contrived) example of a tie;
953 all it does is use a file to keep a log of the values assigned to a
954 scalar.
955 package Remember;
957 use strict;
959 use warnings;
960 use IO::File;
961 sub TIESCALAR {
963 my $class = shift;
964 my $filename = shift;
965 my $handle = IO::File->new( "> $filename" )
966 or die "Cannot open $filename: $!\n";
967 print $handle "The Start\n";
969 bless {FH => $handle, Value => 0}, $class;
970 }
971 sub FETCH {
973 my $self = shift;
974 return $self->{Value};
975 }
976 sub STORE {
978 my $self = shift;
979 my $value = shift;
980 my $handle = $self->{FH};
981 print $handle "$value\n";
982 $self->{Value} = $value;
983 }
984 sub DESTROY {
986 my $self = shift;
987 my $handle = $self->{FH};
988 print $handle "The End\n";
989 close $handle;
990 }
991 1;
993 Here is an example that makes use of this tie:
995 use strict;
997 use Remember;
998 my $fred;
1000 tie $fred, 'Remember', 'myfile.txt';
1001 $fred = 1;
1002 $fred = 4;
1003 $fred = 5;
1004 untie $fred;
1005 system "cat myfile.txt";
1006 This is the output when it is executed:
1008 The Start
1010 1
1011 4
1012 5
1013 The End
1014 So far so good. Those of you who have been paying attention will have
1016 spotted that the tied object hasn't been used so far. So lets add an
1017 extra method to the Remember class to allow comments to be included in
1018 the file; say, something like this:
1019 sub comment {
1021 my $self = shift;
1022 my $text = shift;
1023 my $handle = $self->{FH};
1024 print $handle $text, "\n";
1025 }
1026 And here is the previous example modified to use the "comment" method
1028 (which requires the tied object):
1029 use strict;
1031 use Remember;
1032 my ($fred, $x);
1034 $x = tie $fred, 'Remember', 'myfile.txt';
1035 $fred = 1;
1036 $fred = 4;
1037 comment $x "changing...";
1038 $fred = 5;
1039 untie $fred;
1040 system "cat myfile.txt";
1041 When this code is executed there is no output. Here's why:
1043 When a variable is tied, it is associated with the object which is the
1045 return value of the TIESCALAR, TIEARRAY, or TIEHASH function. This
1046 object normally has only one reference, namely, the implicit reference
1047 from the tied variable. When untie() is called, that reference is
1048 destroyed. Then, as in the first example above, the object's
1049 destructor (DESTROY) is called, which is normal for objects that have
1050 no more valid references; and thus the file is closed.
1051 In the second example, however, we have stored another reference to the
1053 tied object in $x. That means that when untie() gets called there will
1054 still be a valid reference to the object in existence, so the
1055 destructor is not called at that time, and thus the file is not closed.
1056 The reason there is no output is because the file buffers have not been
1057 flushed to disk.
1058 Now that you know what the problem is, what can you do to avoid it?
1060 Prior to the introduction of the optional UNTIE method the only way was
1061 the good old "-w" flag. Which will spot any instances where you call
1062 untie() and there are still valid references to the tied object. If
1063 the second script above this near the top "use warnings 'untie'" or was
1064 run with the "-w" flag, Perl prints this warning message:
1065 untie attempted while 1 inner references still exist
1067 To get the script to work properly and silence the warning make sure
1069 there are no valid references to the tied object before untie() is
1070 called:
1071 undef $x;
1073 untie $fred;
1074 Now that UNTIE exists the class designer can decide which parts of the
1076 class functionality are really associated with "untie" and which with
1077 the object being destroyed. What makes sense for a given class depends
1078 on whether the inner references are being kept so that non-tie-related
1079 methods can be called on the object. But in most cases it probably
1080 makes sense to move the functionality that would have been in DESTROY
1081 to the UNTIE method.
1082 If the UNTIE method exists then the warning above does not occur.
1084 Instead the UNTIE method is passed the count of "extra" references and
1085 can issue its own warning if appropriate. e.g. to replicate the no
1086 UNTIE case this method can be used:
1087 sub UNTIE
1089 {
1090 my ($obj,$count) = @_;
1091 carp "untie attempted while $count inner references still exist"
1092 if $count;
1093 }
1094
1096 See DB_File or Config for some interesting tie() implementations. A
1097 good starting point for many tie() implementations is with one of the
1098 modules Tie::Scalar, Tie::Array, Tie::Hash, or Tie::Handle.
1099
1101 The normal return provided by "scalar(%hash)" is not available. What
1102 this means is that using %tied_hash in boolean context doesn't work
1103 right (currently this always tests false, regardless of whether the
1104 hash is empty or hash elements). [ This paragraph needs review in
1105 light of changes in 5.25 ]
1106 Localizing tied arrays or hashes does not work. After exiting the
1108 scope the arrays or the hashes are not restored.
1109 Counting the number of entries in a hash via "scalar(keys(%hash))" or
1111 "scalar(values(%hash)") is inefficient since it needs to iterate
1112 through all the entries with FIRSTKEY/NEXTKEY.
1113 Tied hash/array slices cause multiple FETCH/STORE pairs, there are no
1115 tie methods for slice operations.
1116 You cannot easily tie a multilevel data structure (such as a hash of
1118 hashes) to a dbm file. The first problem is that all but GDBM and
1119 Berkeley DB have size limitations, but beyond that, you also have
1120 problems with how references are to be represented on disk. One module
1121 that does attempt to address this need is DBM::Deep. Check your
1122 nearest CPAN site as described in perlmodlib for source code. Note
1123 that despite its name, DBM::Deep does not use dbm. Another earlier
1124 attempt at solving the problem is MLDBM, which is also available on the
1125 CPAN, but which has some fairly serious limitations.
1126 Tied filehandles are still incomplete. sysopen(), truncate(), flock(),
1128 fcntl(), stat() and -X can't currently be trapped.
1129
1131 Tom Christiansen
1132 TIEHANDLE by Sven Verdoolaege <skimo@dns.ufsia.ac.be> and Doug
1134 MacEachern <dougm@osf.org>
1135 UNTIE by Nick Ing-Simmons <nick@ing-simmons.net>
1137 SCALAR by Tassilo von Parseval <tassilo.von.parseval@rwth-aachen.de>
1139 Tying Arrays by Casey West <casey@geeknest.com>
1141perl v5.32.1 2021-05-31 PERLTIE(1)