1PERLTIE(1)             Perl Programmers Reference Guide             PERLTIE(1)
2
3
4

NAME

6       perltie - how to hide an object class in a simple variable
7

SYNOPSIS

9        tie VARIABLE, CLASSNAME, LIST
10
11        $object = tied VARIABLE
12
13        untie VARIABLE
14

DESCRIPTION

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
22       Now you can.
23
24       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
33       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
46       Unlike dbmopen(), the tie() function will not "use" or "require" a
47       module for you--you need to do that explicitly yourself.
48
49   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
53       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
56           tie $his_speed, 'Nice', getppid();
57           tie $my_speed,  'Nice', $$;
58
59       And now whenever either of those variables is accessed, its current
60       system priority is retrieved and returned.  If those variables are set,
61       then the process's priority is changed!
62
63       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
68           package Nice;
69           use Carp;
70           use BSD::Resource;
71           use strict;
72           $Nice::DEBUG = 0 unless defined $Nice::DEBUG;
73
74       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
79            sub TIESCALAR {
80                my $class = shift;
81                my $pid = shift || $$; # 0 means me
82
83                if ($pid !~ /^\d+$/) {
84                    carp "Nice::Tie::Scalar got non-numeric pid $pid" if $^W;
85                    return undef;
86                }
87
88                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
93                return bless \$pid, $class;
94            }
95
96           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
102       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
111               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
122           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
126       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
133            sub STORE {
134                my $self = shift;
135                confess "wrong type" unless ref $self;
136                my $new_nicety = shift;
137                croak "usage error" if @_;
138
139                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
146                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
153                unless (defined setpriority(PRIO_PROCESS,
154                                            $$self,
155                                            $new_nicety))
156                {
157                    confess "setpriority failed: $!";
158                }
159            }
160
161       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
167       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
174               sub DESTROY {
175                   my $self = shift;
176                   confess "wrong type" unless ref $self;
177                   carp "[ Nice::DESTROY pid $$self ]" if $Nice::DEBUG;
178               }
179
180       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
185   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
190       FETCHSIZE and STORESIZE are used to provide $#array and equivalent
191       "scalar(@array)" access.
192
193       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
200       In addition EXTEND will be called when perl would have pre-extended
201       allocation in a real array.
202
203       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
207           use FixedElem_Array;
208           tie @array, 'FixedElem_Array', 3;
209           $array[0] = 'cat';  # ok.
210           $array[1] = 'dogs'; # exception, length('dogs') > 3.
211
212       The preamble code for the class is as follows:
213
214           package FixedElem_Array;
215           use Carp;
216           use strict;
217
218       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
223           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
232               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
244       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
249               sub FETCH {
250                 my $self  = shift;
251                 my $index = shift;
252                 return $self->{ARRAY}->[$index];
253               }
254
255           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
261           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
268       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
274           In our example, "undef" is really "$self->{ELEMSIZE}" number of
275           spaces so we have a little more work to do here:
276
277            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
289           Negative indexes are treated the same as with FETCH.
290
291       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
295               sub FETCHSIZE {
296                 my $self = shift;
297                 return scalar $self->{ARRAY}->@*;
298               }
299
300       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
307           In our example, 'undef' is really an element containing
308           "$self->{ELEMSIZE}" number of spaces.  Observe:
309
310               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
324       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
329           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
336               sub EXTEND {
337                 my $self  = shift;
338                 my $count = shift;
339                 # nothing to see here, move along.
340               }
341
342           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
349       EXISTS this, key
350           Verify that the element at index key exists in the tied array this.
351
352           In our example, we will determine that if an element consists of
353           "$self->{ELEMSIZE}" spaces only, it does not exist:
354
355            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
363       DELETE this, key
364           Delete the element at index key from the tied array this.
365
366           In our example, a deleted item is "$self->{ELEMSIZE}" spaces:
367
368               sub DELETE {
369                 my $self  = shift;
370                 my $index = shift;
371                 return $self->STORE( $index, '' );
372               }
373
374       CLEAR this
375           Clear (remove, delete, ...) all values from the tied array
376           associated with object this.  For example:
377
378               sub CLEAR {
379                 my $self = shift;
380                 return $self->{ARRAY} = [];
381               }
382
383       PUSH this, LIST
384           Append elements of LIST to the array.  For example:
385
386               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
394       POP this
395           Remove last element of the array and return it.  For example:
396
397               sub POP {
398                 my $self = shift;
399                 return pop $self->{ARRAY}->@*;
400               }
401
402       SHIFT this
403           Remove the first element of the array (shifting other elements
404           down) and return it.  For example:
405
406               sub SHIFT {
407                 my $self = shift;
408                 return shift $self->{ARRAY}->@*;
409               }
410
411       UNSHIFT this, LIST
412           Insert LIST elements at the beginning of the array, moving existing
413           elements up to make room.  For example:
414
415               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
425       SPLICE this, offset, length, LIST
426           Perform the equivalent of "splice" on the array.
427
428           offset is optional and defaults to zero, negative values count back
429           from the end of the array.
430
431           length is optional and defaults to rest of the array.
432
433           LIST may be empty.
434
435           Returns a list of the original length elements at offset.
436
437           In our example, we'll use a little shortcut if there is a LIST:
438
439               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
451       UNTIE this
452           Will be called when "untie" happens. (See "The "untie" Gotcha"
453           below.)
454
455       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
461   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
473       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
477       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
482       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
487           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
496       Or here's another sample of using our tied class:
497
498           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
504       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
508       USER whose dot files this object represents
509
510       HOME where those dot files live
511
512       CLOBBER
513            whether we should try to change or remove those dot files
514
515       LIST the hash of dot file names and content mappings
516
517       Here's the start of Dotfiles.pm:
518
519           package DotFiles;
520           use Carp;
521           sub whowasi { (caller(1))[3] . '()' }
522           my $DEBUG = 0;
523           sub debug { $DEBUG = @_ ? shift : 1 }
524
525       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
530       Here are the methods for the DotFiles tied hash.
531
532       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
537           Here's the constructor:
538
539               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
549                   my $node = {
550                       USER    => $user,
551                       HOME    => $dir,
552                       LIST    => {},
553                       CLOBBER => 0,
554                   };
555
556                   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
566           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
571       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
576           Here's the fetch for our DotFiles example.
577
578               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
585                   unless (exists $self->{LIST}->{$dot} || -f $file) {
586                       carp "@{[&whowasi]}: no $dot file" if $DEBUG;
587                       return undef;
588                   }
589
590                   if (defined $self->{LIST}->{$dot}) {
591                       return $self->{LIST}->{$dot};
592                   } else {
593                       return $self->{LIST}->{$dot} = `cat $dir/.$dot`;
594                   }
595               }
596
597           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
602       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
608           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
612               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
620                   croak "@{[&whowasi]}: $file not clobberable"
621                       unless $self->{CLOBBER};
622
623                   open(my $f, '>', $file) || croak "can't open $file: $!";
624                   print $f $value;
625                   close($f);
626               }
627
628           If they wanted to clobber something, they might say:
629
630               $ob = tie %daemon_dots, 'daemon';
631               $ob->clobber(1);
632               $daemon_dots{signature} = "A true daemon\n";
633
634           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
638               tie %daemon_dots, 'daemon';
639               tied(%daemon_dots)->clobber(1);
640
641           The clobber method is simply:
642
643               sub clobber {
644                   my $self = shift;
645                   $self->{CLOBBER} = @_ ? shift : 1;
646               }
647
648       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
653            sub DELETE   {
654                carp &whowasi if $DEBUG;
655
656                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
667           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
674       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
678           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
682            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
693       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
698               sub EXISTS   {
699                   carp &whowasi if $DEBUG;
700                   my $self = shift;
701                   my $dot = shift;
702                   return exists $self->{LIST}->{$dot};
703               }
704
705       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
709               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
716           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
720       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
727           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
731           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
735               sub NEXTKEY  {
736                   carp &whowasi if $DEBUG;
737                   my $self = shift;
738                   return each $self->{LIST}->%*
739               }
740
741           If the object underlying your tied hash isn't a real hash and you
742           don't have "each" available, then you should return "undef" or the
743           empty list once you've reached the end of your list of keys. See
744           "each's own documentation" for more details.
745
746       SCALAR this
747           This is called when the hash is evaluated in scalar context, and in
748           5.28 onwards, by "keys" in boolean context. In order to mimic the
749           behaviour of untied hashes, this method must return a value which
750           when used as boolean, indicates whether the tied hash is considered
751           empty. If this method does not exist, perl will make some educated
752           guesses and return true when the hash is inside an iteration. If
753           this isn't the case, FIRSTKEY is called, and the result will be a
754           false value if FIRSTKEY returns the empty list, true otherwise.
755
756           However, you should not blindly rely on perl always doing the right
757           thing. Particularly, perl will mistakenly return true when you
758           clear the hash by repeatedly calling DELETE until it is empty. You
759           are therefore advised to supply your own SCALAR method when you
760           want to be absolutely sure that your hash behaves nicely in scalar
761           context.
762
763           In our example we can just call "scalar" on the underlying hash
764           referenced by "$self->{LIST}":
765
766               sub SCALAR {
767                   carp &whowasi if $DEBUG;
768                   my $self = shift;
769                   return scalar $self->{LIST}->%*
770               }
771
772           NOTE: In perl 5.25 the behavior of scalar %hash on an untied hash
773           changed to return the count of keys. Prior to this it returned a
774           string containing information about the bucket setup of the hash.
775           See "bucket_ratio" in Hash::Util for a backwards compatibility
776           path.
777
778       UNTIE this
779           This is called when "untie" occurs.  See "The "untie" Gotcha"
780           below.
781
782       DESTROY this
783           This method is triggered when a tied hash is about to go out of
784           scope.  You don't really need it unless you're trying to add
785           debugging or have auxiliary state to clean up.  Here's a very
786           simple function:
787
788               sub DESTROY  {
789                   carp &whowasi if $DEBUG;
790               }
791
792       Note that functions such as keys() and values() may return huge lists
793       when used on large objects, like DBM files.  You may prefer to use the
794       each() function to iterate over such.  Example:
795
796           # print out history file offsets
797           use NDBM_File;
798           tie(%HIST, 'NDBM_File', '/usr/lib/news/history', 1, 0);
799           while (($key,$val) = each %HIST) {
800               print $key, ' = ', unpack('L',$val), "\n";
801           }
802           untie(%HIST);
803
804   Tying FileHandles
805       This is partially implemented now.
806
807       A class implementing a tied filehandle should define the following
808       methods: TIEHANDLE, at least one of PRINT, PRINTF, WRITE, READLINE,
809       GETC, READ, and possibly CLOSE, UNTIE and DESTROY.  The class can also
810       provide: BINMODE, OPEN, EOF, FILENO, SEEK, TELL - if the corresponding
811       perl operators are used on the handle.
812
813       When STDERR is tied, its PRINT method will be called to issue warnings
814       and error messages.  This feature is temporarily disabled during the
815       call, which means you can use "warn()" inside PRINT without starting a
816       recursive loop.  And just like "__WARN__" and "__DIE__" handlers,
817       STDERR's PRINT method may be called to report parser errors, so the
818       caveats mentioned under "%SIG" in perlvar apply.
819
820       All of this is especially useful when perl is embedded in some other
821       program, where output to STDOUT and STDERR may have to be redirected in
822       some special way.  See nvi and the Apache module for examples.
823
824       When tying a handle, the first argument to "tie" should begin with an
825       asterisk.  So, if you are tying STDOUT, use *STDOUT.  If you have
826       assigned it to a scalar variable, say $handle, use *$handle.  "tie
827       $handle" ties the scalar variable $handle, not the handle inside it.
828
829       In our example we're going to create a shouting handle.
830
831           package Shout;
832
833       TIEHANDLE classname, LIST
834           This is the constructor for the class.  That means it is expected
835           to return a blessed reference of some sort. The reference can be
836           used to hold some internal information.
837
838               sub TIEHANDLE { print "<shout>\n"; my $i; bless \$i, shift }
839
840       WRITE this, LIST
841           This method will be called when the handle is written to via the
842           "syswrite" function.
843
844            sub WRITE {
845                $r = shift;
846                my($buf,$len,$offset) = @_;
847                print "WRITE called, \$buf=$buf, \$len=$len, \$offset=$offset";
848            }
849
850       PRINT this, LIST
851           This method will be triggered every time the tied handle is printed
852           to with the "print()" or "say()" functions.  Beyond its self
853           reference it also expects the list that was passed to the print
854           function.
855
856             sub PRINT { $r = shift; $$r++; print join($,,map(uc($_),@_)),$\ }
857
858           "say()" acts just like "print()" except $\ will be localized to
859           "\n" so you need do nothing special to handle "say()" in "PRINT()".
860
861       PRINTF this, LIST
862           This method will be triggered every time the tied handle is printed
863           to with the "printf()" function.  Beyond its self reference it also
864           expects the format and list that was passed to the printf function.
865
866               sub PRINTF {
867                   shift;
868                   my $fmt = shift;
869                   print sprintf($fmt, @_);
870               }
871
872       READ this, LIST
873           This method will be called when the handle is read from via the
874           "read" or "sysread" functions.
875
876            sub READ {
877              my $self = shift;
878              my $bufref = \$_[0];
879              my(undef,$len,$offset) = @_;
880              print "READ called, \$buf=$bufref, \$len=$len, \$offset=$offset";
881              # add to $$bufref, set $len to number of characters read
882              $len;
883            }
884
885       READLINE this
886           This method is called when the handle is read via "<HANDLE>" or
887           "readline HANDLE".
888
889           As per "readline", in scalar context it should return the next
890           line, or "undef" for no more data.  In list context it should
891           return all remaining lines, or an empty list for no more data.  The
892           strings returned should include the input record separator $/ (see
893           perlvar), unless it is "undef" (which means "slurp" mode).
894
895               sub READLINE {
896                 my $r = shift;
897                 if (wantarray) {
898                   return ("all remaining\n",
899                           "lines up\n",
900                           "to eof\n");
901                 } else {
902                   return "READLINE called " . ++$$r . " times\n";
903                 }
904               }
905
906       GETC this
907           This method will be called when the "getc" function is called.
908
909               sub GETC { print "Don't GETC, Get Perl"; return "a"; }
910
911       EOF this
912           This method will be called when the "eof" function is called.
913
914           Starting with Perl 5.12, an additional integer parameter will be
915           passed.  It will be zero if "eof" is called without parameter; 1 if
916           "eof" is given a filehandle as a parameter, e.g. "eof(FH)"; and 2
917           in the very special case that the tied filehandle is "ARGV" and
918           "eof" is called with an empty parameter list, e.g. "eof()".
919
920               sub EOF { not length $stringbuf }
921
922       CLOSE this
923           This method will be called when the handle is closed via the
924           "close" function.
925
926               sub CLOSE { print "CLOSE called.\n" }
927
928       UNTIE this
929           As with the other types of ties, this method will be called when
930           "untie" happens.  It may be appropriate to "auto CLOSE" when this
931           occurs.  See "The "untie" Gotcha" below.
932
933       DESTROY this
934           As with the other types of ties, this method will be called when
935           the tied handle is about to be destroyed. This is useful for
936           debugging and possibly cleaning up.
937
938               sub DESTROY { print "</shout>\n" }
939
940       Here's how to use our little example:
941
942           tie(*FOO,'Shout');
943           print FOO "hello\n";
944           $a = 4; $b = 6;
945           print FOO $a, " plus ", $b, " equals ", $a + $b, "\n";
946           print <FOO>;
947
948   UNTIE this
949       You can define for all tie types an UNTIE method that will be called at
950       untie().  See "The "untie" Gotcha" below.
951
952   The "untie" Gotcha
953       If you intend making use of the object returned from either tie() or
954       tied(), and if the tie's target class defines a destructor, there is a
955       subtle gotcha you must guard against.
956
957       As setup, consider this (admittedly rather contrived) example of a tie;
958       all it does is use a file to keep a log of the values assigned to a
959       scalar.
960
961           package Remember;
962
963           use strict;
964           use warnings;
965           use IO::File;
966
967           sub TIESCALAR {
968               my $class = shift;
969               my $filename = shift;
970               my $handle = IO::File->new( "> $filename" )
971                                or die "Cannot open $filename: $!\n";
972
973               print $handle "The Start\n";
974               bless {FH => $handle, Value => 0}, $class;
975           }
976
977           sub FETCH {
978               my $self = shift;
979               return $self->{Value};
980           }
981
982           sub STORE {
983               my $self = shift;
984               my $value = shift;
985               my $handle = $self->{FH};
986               print $handle "$value\n";
987               $self->{Value} = $value;
988           }
989
990           sub DESTROY {
991               my $self = shift;
992               my $handle = $self->{FH};
993               print $handle "The End\n";
994               close $handle;
995           }
996
997           1;
998
999       Here is an example that makes use of this tie:
1000
1001           use strict;
1002           use Remember;
1003
1004           my $fred;
1005           tie $fred, 'Remember', 'myfile.txt';
1006           $fred = 1;
1007           $fred = 4;
1008           $fred = 5;
1009           untie $fred;
1010           system "cat myfile.txt";
1011
1012       This is the output when it is executed:
1013
1014           The Start
1015           1
1016           4
1017           5
1018           The End
1019
1020       So far so good.  Those of you who have been paying attention will have
1021       spotted that the tied object hasn't been used so far.  So lets add an
1022       extra method to the Remember class to allow comments to be included in
1023       the file; say, something like this:
1024
1025           sub comment {
1026               my $self = shift;
1027               my $text = shift;
1028               my $handle = $self->{FH};
1029               print $handle $text, "\n";
1030           }
1031
1032       And here is the previous example modified to use the "comment" method
1033       (which requires the tied object):
1034
1035           use strict;
1036           use Remember;
1037
1038           my ($fred, $x);
1039           $x = tie $fred, 'Remember', 'myfile.txt';
1040           $fred = 1;
1041           $fred = 4;
1042           comment $x "changing...";
1043           $fred = 5;
1044           untie $fred;
1045           system "cat myfile.txt";
1046
1047       When this code is executed there is no output.  Here's why:
1048
1049       When a variable is tied, it is associated with the object which is the
1050       return value of the TIESCALAR, TIEARRAY, or TIEHASH function.  This
1051       object normally has only one reference, namely, the implicit reference
1052       from the tied variable.  When untie() is called, that reference is
1053       destroyed.  Then, as in the first example above, the object's
1054       destructor (DESTROY) is called, which is normal for objects that have
1055       no more valid references; and thus the file is closed.
1056
1057       In the second example, however, we have stored another reference to the
1058       tied object in $x.  That means that when untie() gets called there will
1059       still be a valid reference to the object in existence, so the
1060       destructor is not called at that time, and thus the file is not closed.
1061       The reason there is no output is because the file buffers have not been
1062       flushed to disk.
1063
1064       Now that you know what the problem is, what can you do to avoid it?
1065       Prior to the introduction of the optional UNTIE method the only way was
1066       the good old "-w" flag. Which will spot any instances where you call
1067       untie() and there are still valid references to the tied object.  If
1068       the second script above this near the top "use warnings 'untie'" or was
1069       run with the "-w" flag, Perl prints this warning message:
1070
1071           untie attempted while 1 inner references still exist
1072
1073       To get the script to work properly and silence the warning make sure
1074       there are no valid references to the tied object before untie() is
1075       called:
1076
1077           undef $x;
1078           untie $fred;
1079
1080       Now that UNTIE exists the class designer can decide which parts of the
1081       class functionality are really associated with "untie" and which with
1082       the object being destroyed. What makes sense for a given class depends
1083       on whether the inner references are being kept so that non-tie-related
1084       methods can be called on the object. But in most cases it probably
1085       makes sense to move the functionality that would have been in DESTROY
1086       to the UNTIE method.
1087
1088       If the UNTIE method exists then the warning above does not occur.
1089       Instead the UNTIE method is passed the count of "extra" references and
1090       can issue its own warning if appropriate. e.g. to replicate the no
1091       UNTIE case this method can be used:
1092
1093        sub UNTIE
1094        {
1095         my ($obj,$count) = @_;
1096         carp "untie attempted while $count inner references still exist"
1097                                                                     if $count;
1098        }
1099

SEE ALSO

1101       See DB_File or Config for some interesting tie() implementations.  A
1102       good starting point for many tie() implementations is with one of the
1103       modules Tie::Scalar, Tie::Array, Tie::Hash, or Tie::Handle.
1104

BUGS

1106       The normal return provided by "scalar(%hash)" is not available.  What
1107       this means is that using %tied_hash in boolean context doesn't work
1108       right (currently this always tests false, regardless of whether the
1109       hash is empty or hash elements).  [ This paragraph needs review in
1110       light of changes in 5.25 ]
1111
1112       Localizing tied arrays or hashes does not work.  After exiting the
1113       scope the arrays or the hashes are not restored.
1114
1115       Counting the number of entries in a hash via "scalar(keys(%hash))" or
1116       "scalar(values(%hash)") is inefficient since it needs to iterate
1117       through all the entries with FIRSTKEY/NEXTKEY.
1118
1119       Tied hash/array slices cause multiple FETCH/STORE pairs, there are no
1120       tie methods for slice operations.
1121
1122       You cannot easily tie a multilevel data structure (such as a hash of
1123       hashes) to a dbm file.  The first problem is that all but GDBM and
1124       Berkeley DB have size limitations, but beyond that, you also have
1125       problems with how references are to be represented on disk.  One module
1126       that does attempt to address this need is DBM::Deep.  Check your
1127       nearest CPAN site as described in perlmodlib for source code.  Note
1128       that despite its name, DBM::Deep does not use dbm.  Another earlier
1129       attempt at solving the problem is MLDBM, which is also available on the
1130       CPAN, but which has some fairly serious limitations.
1131
1132       Tied filehandles are still incomplete.  sysopen(), truncate(), flock(),
1133       fcntl(), stat() and -X can't currently be trapped.
1134

AUTHOR

1136       Tom Christiansen
1137
1138       TIEHANDLE by Sven Verdoolaege <skimo@dns.ufsia.ac.be> and Doug
1139       MacEachern <dougm@osf.org>
1140
1141       UNTIE by Nick Ing-Simmons <nick@ing-simmons.net>
1142
1143       SCALAR by Tassilo von Parseval <tassilo.von.parseval@rwth-aachen.de>
1144
1145       Tying Arrays by Casey West <casey@geeknest.com>
1146
1147
1148
1149perl v5.34.1                      2022-03-15                        PERLTIE(1)
Impressum