Further clarification on indirect filehandles

A recent discussion on Stackoverflow.com indicated to me that there is
some potential for confusion in the "Indirect Filehandles" section in
perlopentut.pod. See comments to
http://stackoverflow.com/questions/3661161/writing-a-macro-in-perl/3661239#36612
39

The attached patch is my attempt at clarifying that indirect
filehandles are closed when there are no more references to them
rather than simply when the end of the current lexical scope is
reached. I also added an example of returning such a filehandle from a
subroutine.

I am not sure if this is the best way to word it, so I would
appreciate feedback.

The patch is attached.

-- Sinan

diff --git a/pod/perlopentut.pod b/pod/perlopentut.pod
index ea4b307..2322907 100644 (file)
--- a/pod/perlopentut.pod
+++ b/pod/perlopentut.pod
@@ -117,13 +117,30 @@ like C<my $infile>, there's no clash and no need to worry about future
 conflicts.
 
 Another convenient behavior is that an indirect filehandle automatically
-closes when it goes out of scope or when you undefine it:
+closes when there are no more references to it:
 
     sub firstline {
        open( my $in, shift ) && return scalar <$in>;
        # no close() required
     }
 
+Indirect filehandles also make it easy to pass filehandles to and return
+filehandles from subroutines:
+
+    for my $file ( qw(this.conf that.conf) ) {
+        my $fin = open_or_throw('<', $file);
+        process_conf( $fin );
+        # no close() needed
+    }
+
+    use Carp;
+    sub open_or_throw {
+        my ($mode, $filename) = @_;
+        open my $h, $mode, $filename
+            or croak "Could not open '$filename': $!";
+        return $h;
+    }
+
 =head2 Pipe Opens
 
 In C, when you want to open a file using the standard I/O library,