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. UNTIE is called when "untie" happens, and
460 DESTROY is called when the tied variable is garbage collected.
461 If this seems like a lot, then feel free to inherit from merely the
463 standard Tie::StdHash module for most of your methods, redefining only
464 the interesting ones. See Tie::Hash for details.
465 Remember that Perl distinguishes between a key not existing in the
467 hash, and the key existing in the hash but having a corresponding value
468 of "undef". The two possibilities can be tested with the "exists()"
469 and "defined()" functions.
470 Here's an example of a somewhat interesting tied hash class: it gives
472 you a hash representing a particular user's dot files. You index into
473 the hash with the name of the file (minus the dot) and you get back
474 that dot file's contents. For example:
475 use DotFiles;
477 tie %dot, 'DotFiles';
478 if ( $dot{profile} =~ /MANPATH/ ||
479 $dot{login} =~ /MANPATH/ ||
480 $dot{cshrc} =~ /MANPATH/ )
481 {
482 print "you seem to set your MANPATH\n";
483 }
484 Or here's another sample of using our tied class:
486 tie %him, 'DotFiles', 'daemon';
488 foreach $f ( keys %him ) {
489 printf "daemon dot file %s is size %d\n",
490 $f, length $him{$f};
491 }
492 In our tied hash DotFiles example, we use a regular hash for the object
494 containing several important fields, of which only the "{LIST}" field
495 will be what the user thinks of as the real hash.
496 USER whose dot files this object represents
498 HOME where those dot files live
500 CLOBBER
502 whether we should try to change or remove those dot files
503 LIST the hash of dot file names and content mappings
505 Here's the start of Dotfiles.pm:
507 package DotFiles;
509 use Carp;
510 sub whowasi { (caller(1))[3] . '()' }
511 my $DEBUG = 0;
512 sub debug { $DEBUG = @_ ? shift : 1 }
513 For our example, we want to be able to emit debugging info to help in
515 tracing during development. We keep also one convenience function
516 around internally to help print out warnings; whowasi() returns the
517 function name that calls it.
518 Here are the methods for the DotFiles tied hash.
520 TIEHASH classname, LIST
522 This is the constructor for the class. That means it is expected
523 to return a blessed reference through which the new object
524 (probably but not necessarily an anonymous hash) will be accessed.
525 Here's the constructor:
527 sub TIEHASH {
529 my $self = shift;
530 my $user = shift || $>;
531 my $dotdir = shift || '';
532 croak "usage: @{[&whowasi]} [USER [DOTDIR]]" if @_;
533 $user = getpwuid($user) if $user =~ /^\d+$/;
534 my $dir = (getpwnam($user))[7]
535 || croak "@{[&whowasi]}: no user $user";
536 $dir .= "/$dotdir" if $dotdir;
537 my $node = {
539 USER => $user,
540 HOME => $dir,
541 LIST => {},
542 CLOBBER => 0,
543 };
544 opendir(DIR, $dir)
546 || croak "@{[&whowasi]}: can't opendir $dir: $!";
547 foreach $dot ( grep /^\./ && -f "$dir/$_", readdir(DIR)) {
548 $dot =~ s/^\.//;
549 $node->{LIST}{$dot} = undef;
550 }
551 closedir DIR;
552 return bless $node, $self;
553 }
554 It's probably worth mentioning that if you're going to filetest the
556 return values out of a readdir, you'd better prepend the directory
557 in question. Otherwise, because we didn't chdir() there, it would
558 have been testing the wrong file.
559 FETCH this, key
561 This method will be triggered every time an element in the tied
562 hash is accessed (read). It takes one argument beyond its self
563 reference: the key whose value we're trying to fetch.
564 Here's the fetch for our DotFiles example.
566 sub FETCH {
568 carp &whowasi if $DEBUG;
569 my $self = shift;
570 my $dot = shift;
571 my $dir = $self->{HOME};
572 my $file = "$dir/.$dot";
573 unless (exists $self->{LIST}->{$dot} || -f $file) {
575 carp "@{[&whowasi]}: no $dot file" if $DEBUG;
576 return undef;
577 }
578 if (defined $self->{LIST}->{$dot}) {
580 return $self->{LIST}->{$dot};
581 } else {
582 return $self->{LIST}->{$dot} = `cat $dir/.$dot`;
583 }
584 }
585 It was easy to write by having it call the Unix cat(1) command, but
587 it would probably be more portable to open the file manually (and
588 somewhat more efficient). Of course, because dot files are a Unixy
589 concept, we're not that concerned.
590 STORE this, key, value
592 This method will be triggered every time an element in the tied
593 hash is set (written). It takes two arguments beyond its self
594 reference: the index at which we're trying to store something, and
595 the value we're trying to put there.
596 Here in our DotFiles example, we'll be careful not to let them try
598 to overwrite the file unless they've called the clobber() method on
599 the original object reference returned by tie().
600 sub STORE {
602 carp &whowasi if $DEBUG;
603 my $self = shift;
604 my $dot = shift;
605 my $value = shift;
606 my $file = $self->{HOME} . "/.$dot";
607 my $user = $self->{USER};
608 croak "@{[&whowasi]}: $file not clobberable"
610 unless $self->{CLOBBER};
611 open(my $f, '>', $file) || croak "can't open $file: $!";
613 print $f $value;
614 close($f);
615 }
616 If they wanted to clobber something, they might say:
618 $ob = tie %daemon_dots, 'daemon';
620 $ob->clobber(1);
621 $daemon_dots{signature} = "A true daemon\n";
622 Another way to lay hands on a reference to the underlying object is
624 to use the tied() function, so they might alternately have set
625 clobber using:
626 tie %daemon_dots, 'daemon';
628 tied(%daemon_dots)->clobber(1);
629 The clobber method is simply:
631 sub clobber {
633 my $self = shift;
634 $self->{CLOBBER} = @_ ? shift : 1;
635 }
636 DELETE this, key
638 This method is triggered when we remove an element from the hash,
639 typically by using the delete() function. Again, we'll be careful
640 to check whether they really want to clobber files.
641 sub DELETE {
643 carp &whowasi if $DEBUG;
644 my $self = shift;
646 my $dot = shift;
647 my $file = $self->{HOME} . "/.$dot";
648 croak "@{[&whowasi]}: won't remove file $file"
649 unless $self->{CLOBBER};
650 delete $self->{LIST}->{$dot};
651 my $success = unlink($file);
652 carp "@{[&whowasi]}: can't unlink $file: $!" unless $success;
653 $success;
654 }
655 The value returned by DELETE becomes the return value of the call
657 to delete(). If you want to emulate the normal behavior of
658 delete(), you should return whatever FETCH would have returned for
659 this key. In this example, we have chosen instead to return a
660 value which tells the caller whether the file was successfully
661 deleted.
662 CLEAR this
664 This method is triggered when the whole hash is to be cleared,
665 usually by assigning the empty list to it.
666 In our example, that would remove all the user's dot files! It's
668 such a dangerous thing that they'll have to set CLOBBER to
669 something higher than 1 to make it happen.
670 sub CLEAR {
672 carp &whowasi if $DEBUG;
673 my $self = shift;
674 croak "@{[&whowasi]}: won't remove all dot files for $self->{USER}"
675 unless $self->{CLOBBER} > 1;
676 my $dot;
677 foreach $dot ( keys %{$self->{LIST}}) {
678 $self->DELETE($dot);
679 }
680 }
681 EXISTS this, key
683 This method is triggered when the user uses the exists() function
684 on a particular hash. In our example, we'll look at the "{LIST}"
685 hash element for this:
686 sub EXISTS {
688 carp &whowasi if $DEBUG;
689 my $self = shift;
690 my $dot = shift;
691 return exists $self->{LIST}->{$dot};
692 }
693 FIRSTKEY this
695 This method will be triggered when the user is going to iterate
696 through the hash, such as via a keys(), values(), or each() call.
697 sub FIRSTKEY {
699 carp &whowasi if $DEBUG;
700 my $self = shift;
701 my $a = keys %{$self->{LIST}}; # reset each() iterator
702 each %{$self->{LIST}}
703 }
704 FIRSTKEY is always called in scalar context and it should just
706 return the first key. values(), and each() in list context, will
707 call FETCH for the returned keys.
708 NEXTKEY this, lastkey
710 This method gets triggered during a keys(), values(), or each()
711 iteration. It has a second argument which is the last key that had
712 been accessed. This is useful if you're caring about ordering or
713 calling the iterator from more than one sequence, or not really
714 storing things in a hash anywhere.
715 NEXTKEY is always called in scalar context and it should just
717 return the next key. values(), and each() in list context, will
718 call FETCH for the returned keys.
719 For our example, we're using a real hash so we'll do just the
721 simple thing, but we'll have to go through the LIST field
722 indirectly.
723 sub NEXTKEY {
725 carp &whowasi if $DEBUG;
726 my $self = shift;
727 return each %{ $self->{LIST} }
728 }
729 SCALAR this
731 This is called when the hash is evaluated in scalar context. In
732 order to mimic the behaviour of untied hashes, this method should
733 return a false value when the tied hash is considered empty. If
734 this method does not exist, perl will make some educated guesses
735 and return true when the hash is inside an iteration. If this isn't
736 the case, FIRSTKEY is called, and the result will be a false value
737 if FIRSTKEY returns the empty list, true otherwise.
738 However, you should not blindly rely on perl always doing the right
740 thing. Particularly, perl will mistakenly return true when you
741 clear the hash by repeatedly calling DELETE until it is empty. You
742 are therefore advised to supply your own SCALAR method when you
743 want to be absolutely sure that your hash behaves nicely in scalar
744 context.
745 In our example we can just call "scalar" on the underlying hash
747 referenced by "$self->{LIST}":
748 sub SCALAR {
750 carp &whowasi if $DEBUG;
751 my $self = shift;
752 return scalar %{ $self->{LIST} }
753 }
754 NOTE: In perl 5.25 the behavior of scalar %hash on an untied hash
756 changed to return the count of keys. Prior to this it returned a
757 string containing information about the bucket setup of the hash.
758 See "bucket_ratio" in Hash::Util for a backwards compatibility
759 path.
760 UNTIE this
762 This is called when "untie" occurs. See "The "untie" Gotcha"
763 below.
764 DESTROY this
766 This method is triggered when a tied hash is about to go out of
767 scope. You don't really need it unless you're trying to add
768 debugging or have auxiliary state to clean up. Here's a very
769 simple function:
770 sub DESTROY {
772 carp &whowasi if $DEBUG;
773 }
774 Note that functions such as keys() and values() may return huge lists
776 when used on large objects, like DBM files. You may prefer to use the
777 each() function to iterate over such. Example:
778 # print out history file offsets
780 use NDBM_File;
781 tie(%HIST, 'NDBM_File', '/usr/lib/news/history', 1, 0);
782 while (($key,$val) = each %HIST) {
783 print $key, ' = ', unpack('L',$val), "\n";
784 }
785 untie(%HIST);
786 Tying FileHandles
788 This is partially implemented now.
789 A class implementing a tied filehandle should define the following
791 methods: TIEHANDLE, at least one of PRINT, PRINTF, WRITE, READLINE,
792 GETC, READ, and possibly CLOSE, UNTIE and DESTROY. The class can also
793 provide: BINMODE, OPEN, EOF, FILENO, SEEK, TELL - if the corresponding
794 perl operators are used on the handle.
795 When STDERR is tied, its PRINT method will be called to issue warnings
797 and error messages. This feature is temporarily disabled during the
798 call, which means you can use "warn()" inside PRINT without starting a
799 recursive loop. And just like "__WARN__" and "__DIE__" handlers,
800 STDERR's PRINT method may be called to report parser errors, so the
801 caveats mentioned under "%SIG" in perlvar apply.
802 All of this is especially useful when perl is embedded in some other
804 program, where output to STDOUT and STDERR may have to be redirected in
805 some special way. See nvi and the Apache module for examples.
806 When tying a handle, the first argument to "tie" should begin with an
808 asterisk. So, if you are tying STDOUT, use *STDOUT. If you have
809 assigned it to a scalar variable, say $handle, use *$handle. "tie
810 $handle" ties the scalar variable $handle, not the handle inside it.
811 In our example we're going to create a shouting handle.
813 package Shout;
815 TIEHANDLE classname, LIST
817 This is the constructor for the class. That means it is expected
818 to return a blessed reference of some sort. The reference can be
819 used to hold some internal information.
820 sub TIEHANDLE { print "<shout>\n"; my $i; bless \$i, shift }
822 WRITE this, LIST
824 This method will be called when the handle is written to via the
825 "syswrite" function.
826 sub WRITE {
828 $r = shift;
829 my($buf,$len,$offset) = @_;
830 print "WRITE called, \$buf=$buf, \$len=$len, \$offset=$offset";
831 }
832 PRINT this, LIST
834 This method will be triggered every time the tied handle is printed
835 to with the "print()" or "say()" functions. Beyond its self
836 reference it also expects the list that was passed to the print
837 function.
838 sub PRINT { $r = shift; $$r++; print join($,,map(uc($_),@_)),$\ }
840 "say()" acts just like "print()" except $\ will be localized to
842 "\n" so you need do nothing special to handle "say()" in "PRINT()".
843 PRINTF this, LIST
845 This method will be triggered every time the tied handle is printed
846 to with the "printf()" function. Beyond its self reference it also
847 expects the format and list that was passed to the printf function.
848 sub PRINTF {
850 shift;
851 my $fmt = shift;
852 print sprintf($fmt, @_);
853 }
854 READ this, LIST
856 This method will be called when the handle is read from via the
857 "read" or "sysread" functions.
858 sub READ {
860 my $self = shift;
861 my $bufref = \$_[0];
862 my(undef,$len,$offset) = @_;
863 print "READ called, \$buf=$bufref, \$len=$len, \$offset=$offset";
864 # add to $$bufref, set $len to number of characters read
865 $len;
866 }
867 READLINE this
869 This method is called when the handle is read via "<HANDLE>" or
870 "readline HANDLE".
871 As per "readline", in scalar context it should return the next
873 line, or "undef" for no more data. In list context it should
874 return all remaining lines, or an empty list for no more data. The
875 strings returned should include the input record separator $/ (see
876 perlvar), unless it is "undef" (which means "slurp" mode).
877 sub READLINE {
879 my $r = shift;
880 if (wantarray) {
881 return ("all remaining\n",
882 "lines up\n",
883 "to eof\n");
884 } else {
885 return "READLINE called " . ++$$r . " times\n";
886 }
887 }
888 GETC this
890 This method will be called when the "getc" function is called.
891 sub GETC { print "Don't GETC, Get Perl"; return "a"; }
893 EOF this
895 This method will be called when the "eof" function is called.
896 Starting with Perl 5.12, an additional integer parameter will be
898 passed. It will be zero if "eof" is called without parameter; 1 if
899 "eof" is given a filehandle as a parameter, e.g. "eof(FH)"; and 2
900 in the very special case that the tied filehandle is "ARGV" and
901 "eof" is called with an empty parameter list, e.g. "eof()".
902 sub EOF { not length $stringbuf }
904 CLOSE this
906 This method will be called when the handle is closed via the
907 "close" function.
908 sub CLOSE { print "CLOSE called.\n" }
910 UNTIE this
912 As with the other types of ties, this method will be called when
913 "untie" happens. It may be appropriate to "auto CLOSE" when this
914 occurs. See "The "untie" Gotcha" below.
915 DESTROY this
917 As with the other types of ties, this method will be called when
918 the tied handle is about to be destroyed. This is useful for
919 debugging and possibly cleaning up.
920 sub DESTROY { print "</shout>\n" }
922 Here's how to use our little example:
924 tie(*FOO,'Shout');
926 print FOO "hello\n";
927 $a = 4; $b = 6;
928 print FOO $a, " plus ", $b, " equals ", $a + $b, "\n";
929 print <FOO>;
930 UNTIE this
932 You can define for all tie types an UNTIE method that will be called at
933 untie(). See "The "untie" Gotcha" below.
934 The "untie" Gotcha
936 If you intend making use of the object returned from either tie() or
937 tied(), and if the tie's target class defines a destructor, there is a
938 subtle gotcha you must guard against.
939 As setup, consider this (admittedly rather contrived) example of a tie;
941 all it does is use a file to keep a log of the values assigned to a
942 scalar.
943 package Remember;
945 use strict;
947 use warnings;
948 use IO::File;
949 sub TIESCALAR {
951 my $class = shift;
952 my $filename = shift;
953 my $handle = IO::File->new( "> $filename" )
954 or die "Cannot open $filename: $!\n";
955 print $handle "The Start\n";
957 bless {FH => $handle, Value => 0}, $class;
958 }
959 sub FETCH {
961 my $self = shift;
962 return $self->{Value};
963 }
964 sub STORE {
966 my $self = shift;
967 my $value = shift;
968 my $handle = $self->{FH};
969 print $handle "$value\n";
970 $self->{Value} = $value;
971 }
972 sub DESTROY {
974 my $self = shift;
975 my $handle = $self->{FH};
976 print $handle "The End\n";
977 close $handle;
978 }
979 1;
981 Here is an example that makes use of this tie:
983 use strict;
985 use Remember;
986 my $fred;
988 tie $fred, 'Remember', 'myfile.txt';
989 $fred = 1;
990 $fred = 4;
991 $fred = 5;
992 untie $fred;
993 system "cat myfile.txt";
994 This is the output when it is executed:
996 The Start
998 1
999 4
1000 5
1001 The End
1002 So far so good. Those of you who have been paying attention will have
1004 spotted that the tied object hasn't been used so far. So lets add an
1005 extra method to the Remember class to allow comments to be included in
1006 the file; say, something like this:
1007 sub comment {
1009 my $self = shift;
1010 my $text = shift;
1011 my $handle = $self->{FH};
1012 print $handle $text, "\n";
1013 }
1014 And here is the previous example modified to use the "comment" method
1016 (which requires the tied object):
1017 use strict;
1019 use Remember;
1020 my ($fred, $x);
1022 $x = tie $fred, 'Remember', 'myfile.txt';
1023 $fred = 1;
1024 $fred = 4;
1025 comment $x "changing...";
1026 $fred = 5;
1027 untie $fred;
1028 system "cat myfile.txt";
1029 When this code is executed there is no output. Here's why:
1031 When a variable is tied, it is associated with the object which is the
1033 return value of the TIESCALAR, TIEARRAY, or TIEHASH function. This
1034 object normally has only one reference, namely, the implicit reference
1035 from the tied variable. When untie() is called, that reference is
1036 destroyed. Then, as in the first example above, the object's
1037 destructor (DESTROY) is called, which is normal for objects that have
1038 no more valid references; and thus the file is closed.
1039 In the second example, however, we have stored another reference to the
1041 tied object in $x. That means that when untie() gets called there will
1042 still be a valid reference to the object in existence, so the
1043 destructor is not called at that time, and thus the file is not closed.
1044 The reason there is no output is because the file buffers have not been
1045 flushed to disk.
1046 Now that you know what the problem is, what can you do to avoid it?
1048 Prior to the introduction of the optional UNTIE method the only way was
1049 the good old "-w" flag. Which will spot any instances where you call
1050 untie() and there are still valid references to the tied object. If
1051 the second script above this near the top "use warnings 'untie'" or was
1052 run with the "-w" flag, Perl prints this warning message:
1053 untie attempted while 1 inner references still exist
1055 To get the script to work properly and silence the warning make sure
1057 there are no valid references to the tied object before untie() is
1058 called:
1059 undef $x;
1061 untie $fred;
1062 Now that UNTIE exists the class designer can decide which parts of the
1064 class functionality are really associated with "untie" and which with
1065 the object being destroyed. What makes sense for a given class depends
1066 on whether the inner references are being kept so that non-tie-related
1067 methods can be called on the object. But in most cases it probably
1068 makes sense to move the functionality that would have been in DESTROY
1069 to the UNTIE method.
1070 If the UNTIE method exists then the warning above does not occur.
1072 Instead the UNTIE method is passed the count of "extra" references and
1073 can issue its own warning if appropriate. e.g. to replicate the no
1074 UNTIE case this method can be used:
1075 sub UNTIE
1077 {
1078 my ($obj,$count) = @_;
1079 carp "untie attempted while $count inner references still exist"
1080 if $count;
1081 }
1082
1084 See DB_File or Config for some interesting tie() implementations. A
1085 good starting point for many tie() implementations is with one of the
1086 modules Tie::Scalar, Tie::Array, Tie::Hash, or Tie::Handle.
1087
1089 The normal return provided by "scalar(%hash)" is not available. What
1090 this means is that using %tied_hash in boolean context doesn't work
1091 right (currently this always tests false, regardless of whether the
1092 hash is empty or hash elements). [ This paragraph needs review in
1093 light of changes in 5.25 ]
1094 Localizing tied arrays or hashes does not work. After exiting the
1096 scope the arrays or the hashes are not restored.
1097 Counting the number of entries in a hash via "scalar(keys(%hash))" or
1099 "scalar(values(%hash)") is inefficient since it needs to iterate
1100 through all the entries with FIRSTKEY/NEXTKEY.
1101 Tied hash/array slices cause multiple FETCH/STORE pairs, there are no
1103 tie methods for slice operations.
1104 You cannot easily tie a multilevel data structure (such as a hash of
1106 hashes) to a dbm file. The first problem is that all but GDBM and
1107 Berkeley DB have size limitations, but beyond that, you also have
1108 problems with how references are to be represented on disk. One module
1109 that does attempt to address this need is DBM::Deep. Check your
1110 nearest CPAN site as described in perlmodlib for source code. Note
1111 that despite its name, DBM::Deep does not use dbm. Another earlier
1112 attempt at solving the problem is MLDBM, which is also available on the
1113 CPAN, but which has some fairly serious limitations.
1114 Tied filehandles are still incomplete. sysopen(), truncate(), flock(),
1116 fcntl(), stat() and -X can't currently be trapped.
1117
1119 Tom Christiansen
1120 TIEHANDLE by Sven Verdoolaege <skimo@dns.ufsia.ac.be> and Doug
1122 MacEachern <dougm@osf.org>
1123 UNTIE by Nick Ing-Simmons <nick@ing-simmons.net>
1125 SCALAR by Tassilo von Parseval <tassilo.von.parseval@rwth-aachen.de>
1127 Tying Arrays by Casey West <casey@geeknest.com>
1129perl v5.26.3 2018-03-23 PERLTIE(1)