Recipe 7.6 Writing a Subroutine That Takes Filehandles as Built-ins Do

7.6.1 Problem

You can pass a bareword filehandle to Perl functions like eof, and you'd like to write similar subroutines of your own.

7.6.2 Solution

Use the Symbol module's qualify_to_ref in conjunction with a * prototype on the subroutine:

use Symbol qw(qualify_to_ref);

sub my_eof (*) {
  my $handle = shift;
  $handle = qualify_to_ref($handle, caller( ));
  # use $handle
}

7.6.3 Discussion

The * prototype tells Perl that the function expects a bareword filehandle as its argument. This lets you call the function like so:

my_eof(HANDLE);

This works even when use strict 'subs' is in effect. The function receives a string as its argument, though. To safely use the argument as a filehandle, you need the Symbol module to turn it into a reference to a typeglob. And since typeglob refs can be used wherever you'd use named filehandles, store that reference in a scalar variable and use the variable as an indirect filehandle within your subroutine.

If you pass in a filehandle that is already a reference to a typeglob, like those autovivified by open, Perl and qualify_to_ref still do the right thing:

open(my $fh, "<", $filename) or die;
my_eof($fh);

This technique is used in Recipe 7.23.

7.6.4 See Also

The documentation for the standard module Symbol (also in Chapter 32 of Programming Perl); the "Prototypes" section in the perlsub(1) manpage (also in Chapter 6 of Programming Perl); Recipe 7.23