develooper Front page | perl.perl5.porters | Postings from March 2013

RE: [perl #117223] Remove IO::File example from perlfunc

Thread Next
Ed Avis
March 22, 2013 10:45
RE: [perl #117223] Remove IO::File example from perlfunc
Message ID:
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 7088a9e..a249af2 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -3865,12 +3865,6 @@ FILEHANDLE is an expression, its value is the real filehandle.  (This is
 considered a symbolic reference, so C<use strict "refs"> should I<not> be
 in effect.)

-If EXPR is omitted, the global (package) scalar variable of the same
-name as the FILEHANDLE contains the filename.  (Note that lexical
-variables--those declared with C<my> or C<state>--will not work for this
-purpose; so if you're using C<my> or C<state>, specify EXPR in your
-call to open.)
 If three (or more) arguments are specified, the open mode (including
 optional encoding) in the second argument are distinct from the filename in
 the third.  If MODE is C<< < >> or nothing, the file is opened for input.
@@ -3953,6 +3947,31 @@ where you want to format a suitable error message (but there are
 modules that can help with that problem)) always check
 the return value from opening a file.

+The filehandle will be closed when its reference count reaches
+zero.  If it is a lexically scoped variable declared with C<my>,
+that usually means the end of the enclosing scope.  However,
+this automatic close does not check for errors, so it is better
+to explicitly close filehandles, especially those used for writing:
+    close($handle)
+       || warn "close failed: $!";
+An older style is to use a bareword as the filehandle, as
+    open(FH, "<", "input.txt")
+       or die "cannot open < input.txt: $!";
+Then you can use FH as the filenandle, in C<< close FH >> and C<< <FH> >> and so on.
+Note that it's a global variable, so this form is not recommeded in new code.
+As a shortcut a one-argument call takes the filename from the global scalar variable
+of the same name as the filehandle:
+    $ARTICLE = 100;
+    open(ARTICLE) or die "Can't find article $ARTICLE: $!\n";
+Here $ARTICLE must be a global (package) scalar variable - not one
+declared with C<my> or C<state>.
 As a special case the three-argument form with a read/write mode and the third
 argument being C<undef>:

@@ -3977,10 +3996,6 @@ To (re)open C<STDOUT> or C<STDERR> as an in-memory file, close it first:

 General examples:

-    $ARTICLE = 100;
-    open(ARTICLE) or die "Can't find article $ARTICLE: $!\n";
-    while (<ARTICLE>) {...
     open(LOG, ">>/usr/spool/news/twitlog");  # (log is reserved)
     # if the open fails, output is discarded

@@ -4225,34 +4240,6 @@ interpretation.  For example:
     seek(HANDLE, 0, 0);
     print "File contains: ", <HANDLE>;

-Using the constructor from the C<IO::Handle> package (or one of its
-subclasses, such as C<IO::File> or C<IO::Socket>), you can generate anonymous
-filehandles that have the scope of the variables used to hold them, then
-automatically (but silently) close once their reference counts become
-zero, typically at scope exit:
-    use IO::File;
-    #...
-    sub read_myfile_munged {
-        my $ALL = shift;
-       # or just leave it undef to autoviv
-        my $handle = IO::File->new;
-        open($handle, "<", "myfile") or die "myfile: $!";
-        $first = <$handle>
-            or return ();     # Automatically closed here.
-        mung($first) or die "mung failed";  # Or here.
-        return (first, <$handle>) if $ALL;  # Or here.
-        return $first;                      # Or here.
-    }
-B<WARNING:> The previous example has a bug because the automatic
-close that happens when the refcount on C<handle> reaches zero does not
-properly detect and report failures.  I<Always> close the handle
-yourself and inspect the return value.
-    close($handle)
-       || warn "close failed: $!";
 See L</seek> for some details about mixing reading and writing.

 Portability issues: L<perlport/open>.

This email has been scanned by the Symantec Email service.
For more information please visit

Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About