X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=c440faa4100163019f5b91e9c5cbea6d0077be1e;hb=4ff31b786b9f6148fc8ea695db081861576d06a2;hp=776aaf25ef1aa8c8485451049ec4b5eae09f938a;hpb=a6d8037e26aaceac1a62ab1a36249ff12386c7ff;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 776aaf2..c440faa 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -1275,14 +1275,14 @@ produce, respectively
 
 See also exit(), warn(), and the Carp module.
 
-If LIST is empty and C<$@> already contains a value (typically from a
+If the output is empty and C<$@> already contains a value (typically from a
 previous eval) that value is reused after appending C<"\t...propagated">.
 This is useful for propagating exceptions:
 
     eval { ... };
     die unless $@ =~ /Expected exception/;
 
-If LIST is empty and C<$@> contains an object reference that has a
+If the output is empty and C<$@> contains an object reference that has a
 C<PROPAGATE> method, that method will be called with additional file
 and line number parameters.  The return value replaces the value in
 C<$@>.  i.e. as if C<< $@ = eval { $@->PROPAGATE(__FILE__, __LINE__) }; >>
@@ -4080,8 +4080,10 @@ Examples:
 
 The same template may generally also be used in unpack().
 
+=item package NAMESPACE VERSION
+X<package> X<module> X<namespace> X<version>
+
 =item package NAMESPACE
-X<package> X<module> X<namespace>
 
 Declares the compilation unit as being in the given namespace.  The scope
 of the package declaration is from the declaration itself through the end
@@ -4099,6 +4101,11 @@ If the package name is null, the C<main> package as assumed.  That is,
 C<$::sail> is equivalent to C<$main::sail> (as well as to C<$main'sail>,
 still seen in older code).
 
+If VERSION is provided, C<package> also sets the C<$VERSION> variable in the
+given namespace.  VERSION must be be a numeric literal or v-string; it is
+parsed exactly the same way as a VERSION argument to C<use MODULE VERSION>.
+C<$VERSION> should only be set once per package.
+
 See L<perlmod/"Packages"> for more information about packages, modules,
 and classes.  See L<perlsub> for other scoping issues.
 
@@ -4324,6 +4331,15 @@ C<chdir> there, it would have been testing the wrong file.
     @dots = grep { /^\./ && -f "$some_dir/$_" } readdir($dh);
     closedir $dh;
 
+As of Perl 5.11.2 you can use a bare C<readdir> in a C<while> loop,
+which will set C<$_> on every iteration.
+
+    opendir(my $dh, $some_dir) || die;
+    while(readdir $dh) {
+        print "$some_dir/$_\n";
+    }
+    closedir $dh;
+
 =item readline EXPR
 
 =item readline
@@ -4332,12 +4348,12 @@ X<readline> X<gets> X<fgets>
 Reads from the filehandle whose typeglob is contained in EXPR (or from
 *ARGV if EXPR is not provided).  In scalar context, each call reads and
 returns the next line, until end-of-file is reached, whereupon the
-subsequent call returns undef.  In list context, reads until end-of-file
+subsequent call returns C<undef>.  In list context, reads until end-of-file
 is reached and returns a list of lines.  Note that the notion of "line"
 used here is however you may have defined it with C<$/> or
 C<$INPUT_RECORD_SEPARATOR>).  See L<perlvar/"$/">.
 
-When C<$/> is set to C<undef>, when readline() is in scalar
+When C<$/> is set to C<undef>, when C<readline> is in scalar
 context (i.e. file slurp mode), and when an empty file is read, it
 returns C<''> the first time, followed by C<undef> subsequently.
 
@@ -4348,19 +4364,29 @@ operator is discussed in more detail in L<perlop/"I/O Operators">.
     $line = <STDIN>;
     $line = readline(*STDIN);		# same thing
 
-If readline encounters an operating system error, C<$!> will be set with the
-corresponding error message.  It can be helpful to check C<$!> when you are
-reading from filehandles you don't trust, such as a tty or a socket.  The
-following example uses the operator form of C<readline>, and takes the necessary
-steps to ensure that C<readline> was successful.
+If C<readline> encounters an operating system error, C<$!> will be set
+with the corresponding error message.  It can be helpful to check
+C<$!> when you are reading from filehandles you don't trust, such as a
+tty or a socket.  The following example uses the operator form of
+C<readline> and dies if the result is not defined.
 
-    for (;;) {
-        undef $!;
-        unless (defined( $line = <> )) {
-            last if eof;
-            die $! if $!;
+	while ( ! eof($fh) ) {
+		defined( $_ = <$fh> ) or die "readline failed: $!";
+	    ...
+	}
+
+Note that you have can't handle C<readline> errors that way with the
+C<ARGV> filehandle. In that case, you have to open each element of
+C<@ARGV> yourself since C<eof> handles C<ARGV> differently.
+
+    foreach my $arg (@ARGV) {
+        open(my $fh, $arg) or warn "Can't open $arg: $!";
+
+        while ( ! eof($fh) ) {
+            defined( $_ = <$fh> )
+                or die "readline failed for $arg: $!";
+            ...
         }
-        # ...
     }
 
 =item readlink EXPR
@@ -7392,7 +7418,7 @@ Prints the value of LIST to STDERR.  If the last element of LIST does
 not end in a newline, it appends the same file/line number text as C<die>
 does.
 
-If LIST is empty and C<$@> already contains a value (typically from a
+If the output is empty and C<$@> already contains a value (typically from a
 previous eval) that value is used after appending C<"\t...caught">
 to C<$@>.  This is useful for staying almost, but not entirely similar to
 C<die>.