From: Gabor Szabo <szabgab@gmail.com>
Date: Tue, 8 Jan 2008 22:07:54 +0000 (+0200)
Subject: Re: [PATCH] docs more open() and $_ related entries
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=b0169937a1833d262bdcef83fc6595ccc076cb56;p=p5sagit%2Fp5-mst-13.2.git

Re: [PATCH] docs more open() and $_ related entries
From: "Gabor Szabo" <szabgab@gmail.com>
Message-ID: <d8a74af10801081207q2637419dy59f1a3600bcc4a76@mail.gmail.com>

p4raw-id: //depot/perl@32904
---

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index dc340f1..49eb729 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -1928,11 +1928,11 @@ Here's a mailbox appender for BSD systems.
 	flock(MBOX,LOCK_UN);
     }
 
-    open(MBOX, ">>/usr/spool/mail/$ENV{'USER'}")
+    open(my $mbox, ">>", "/usr/spool/mail/$ENV{'USER'}")
 	    or die "Can't open mailbox: $!";
 
     lock();
-    print MBOX $msg,"\n\n";
+    print $mbox $msg,"\n\n";
     unlock();
 
 On systems that support a real flock(), locks are inherited across fork()
@@ -3410,7 +3410,7 @@ them, and automatically close whenever and however you leave that scope:
     #...
     sub read_myfile_munged {
 	my $ALL = shift;
-	my $handle = new IO::File;
+	my $handle = IO::File->new;
 	open($handle, "myfile") or die "myfile: $!";
 	$first = <$handle>
 	    or return ();     # Automatically closed here.
@@ -3432,6 +3432,8 @@ scalar variable (or array or hash element), the variable is assigned a
 reference to a new anonymous dirhandle.
 DIRHANDLEs have their own namespace separate from FILEHANDLEs.
 
+See example at C<readdir>.
+
 =item ord EXPR
 X<ord> X<encoding>
 
@@ -4283,9 +4285,9 @@ If you're planning to filetest the return values out of a C<readdir>, you'd
 better prepend the directory in question.  Otherwise, because we didn't
 C<chdir> there, it would have been testing the wrong file.
 
-    opendir(DIR, $some_dir) || die "can't opendir $some_dir: $!";
-    @dots = grep { /^\./ && -f "$some_dir/$_" } readdir(DIR);
-    closedir DIR;
+    opendir(my $dh, $some_dir) || die "can't opendir $some_dir: $!";
+    @dots = grep { /^\./ && -f "$some_dir/$_" } readdir($dh);
+    closedir $dh;
 
 =item readline EXPR
 
diff --git a/pod/perlvar.pod b/pod/perlvar.pod
index 7f65590..6e62a10 100644
--- a/pod/perlvar.pod
+++ b/pod/perlvar.pod
@@ -58,14 +58,14 @@ the change may affect other modules which rely on the default values
 of the special variables that you have changed. This is one of the
 correct ways to read the whole file at once:
 
-    open my $fh, "foo" or die $!;
+    open my $fh, "<", "foo" or die $!;
     local $/; # enable localized slurp mode
     my $content = <$fh>;
     close $fh;
 
 But the following code is quite bad:
 
-    open my $fh, "foo" or die $!;
+    open my $fh, "<", "foo" or die $!;
     undef $/; # enable slurp mode
     my $content = <$fh>;
     close $fh;
@@ -81,7 +81,7 @@ inside some short C<{}> block, you should create one yourself. For
 example:
 
     my $content = '';
-    open my $fh, "foo" or die $!;
+    open my $fh, "<", "foo" or die $!;
     {
         local $/;
         $content = <$fh>;
@@ -150,10 +150,11 @@ don't use it:
 
 The following functions:
 
-abs, alarm, chomp chop, chr, chroot, cos, defined, eval, exp, glob,
-hex, int, lc, lcfirst, length, log, lstat, mkdir, ord, pos, print,
-quotemeta, readlink, readpipe, ref, require, reverse, rmdir, sin, split, 
-sqrt, stat, study, uc, ucfirst, unlink, unpack.
+abs, alarm, chomp, chop, chr, chroot, cos, defined, eval, exp, glob,
+hex, int, lc, lcfirst, length, log, lstat, mkdir, oct, ord, pos, print,
+quotemeta, readlink, readpipe, ref, require, reverse (in scalar context only),
+rmdir, sin, split (on its second argument), sqrt, stat, study, uc, ucfirst, 
+unlink, unpack.
 
 =item *
 
@@ -163,8 +164,8 @@ See L<perlfunc/-X>
 
 =item *
 
-The pattern matching operations C<m//>, C<s///>, and C<tr///> when used
-without an C<=~> operator.
+The pattern matching operations C<m//>, C<s///> and C<tr///> (aka C<y///>)
+when used without an C<=~> operator.
 
 =item *
 
@@ -442,7 +443,7 @@ instead of lines, with the maximum record size being the referenced
 integer.  So this:
 
     local $/ = \32768; # or \"32768", or \$var_containing_32768
-    open my $fh, $myfile or die $!;
+    open my $fh, "<", $myfile or die $!;
     local $_ = <$fh>;
 
 will read a record of no more than 32768 bytes from FILE.  If you're
@@ -478,7 +479,8 @@ buffered otherwise.  Setting this variable is useful primarily when
 you are outputting to a pipe or socket, such as when you are running
 a Perl program under B<rsh> and want to see the output as it's
 happening.  This has no effect on input buffering.  See L<perlfunc/getc>
-for that.  (Mnemonic: when you want your pipes to be piping hot.)
+for that.  See L<perldoc/select> on how to select the output channel. 
+See also L<IO::Handle>. (Mnemonic: when you want your pipes to be piping hot.)
 
 =item IO::Handle->output_field_separator EXPR
 
@@ -789,7 +791,7 @@ variable, or in other words, if a system or library call fails, it
 sets this variable.  This means that the value of C<$!> is meaningful
 only I<immediately> after a B<failure>:
 
-    if (open(FH, $filename)) {
+    if (open my $fh, "<", $filename) {
 	# Here $! is meaningless.
 	...
     } else {