Remove the MANIFEST check from the release guide

[perl5.git] / pod / perlopentut.pod

diff --git a/pod/perlopentut.pod b/pod/perlopentut.pod
index f023434..4bb43bf 100644 (file)
--- a/pod/perlopentut.pod
+++ b/pod/perlopentut.pod
@@ -55,7 +55,7 @@ If you prefer the low-punctuation version, you could write that this way:
     open RESULTS,">  runstats"  or die "can't open runstats: $!";
     open LOG,    ">> logfile "  or die "can't open logfile:  $!";
 
-A few things to notice.  First, the leading less-than is optional.
+A few things to notice.  First, the leading C<< < >> is optional.
 If omitted, Perl assumes that you want to open the file for reading.
 
 Note also that the first example uses the C<||> logical operator, and the
@@ -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,
@@ -165,6 +182,33 @@ If you would like to open a bidirectional pipe, the IPC::Open2
 library will handle this for you.  Check out 
 L<perlipc/"Bidirectional Communication with Another Process">
 
+perl-5.6.x introduced a version of piped open that executes a process
+based on its command line arguments without relying on the shell. (Similar
+to the C<system(@LIST)> notation.) This is safer and faster than executing
+a single argument pipe-command, but does not allow special shell
+constructs. (It is also not supported on Microsoft Windows, Mac OS Classic
+or RISC OS.)
+
+Here's an example of C<open '-|'>, which prints a random Unix
+fortune cookie as uppercase:
+
+    my $collection = shift(@ARGV);
+    open my $fortune, '-|', 'fortune', $collection
+        or die "Could not find fortune - $!";
+    while (<$fortune>)
+    {
+        print uc($_);
+    }
+    close($fortune);
+
+And this C<open '|-'> pipes into lpr:
+
+    open my $printer, '|-', 'lpr', '-Plp1'
+        or die "can't run lpr: $!";
+    print {$printer} "stuff\n";
+    close($printer)
+        or die "can't close lpr: $!";
+
 =head2 The Minus File
 
 Again following the lead of the standard shell utilities, Perl's
@@ -195,7 +239,7 @@ whether it only works on existing files or always clobbers existing ones.
     open(SCREEN, "+> lkscreen")
         || die "can't open lkscreen: $!";
 
-    open(LOGFILE, "+>> /var/log/applog"
+    open(LOGFILE, "+>> /var/log/applog")
         || die "can't open /var/log/applog: $!";
 
 The first one won't create a new file, and the second one will always
@@ -230,7 +274,7 @@ on each file in @ARGV.  Thus a program called like this:
 
     $ myprogram file1 file2 file3
 
-Can have all its files opened and processed one at a time
+can have all its files opened and processed one at a time
 using a construct no more complex than:
 
     while (<>) {
@@ -307,7 +351,7 @@ One of the more interesting applications is to change files of a certain
 name into pipes.  For example, to autoprocess gzipped or compressed
 files by decompressing them with I<gzip>:
 
-    @ARGV = map { /^\.(gz|Z)$/ ? "gzip -dc $_ |" : $_  } @ARGV;
+    @ARGV = map { /\.(gz|Z)$/ ? "gzip -dc $_ |" : $_  } @ARGV;
 
 Or, if you have the I<GET> program installed from LWP,
 you can fetch URLs before processing them:
@@ -422,7 +466,7 @@ be 0777, and for anything else, 0666.
 Why so permissive?  Well, it isn't really.  The MASK will be modified
 by your process's current C<umask>.  A umask is a number representing
 I<disabled> permissions bits; that is, bits that will not be turned on
-in the created files' permissions field.
+in the created file's permissions field.
 
 For example, if your C<umask> were 027, then the 020 part would
 disable the group from writing, and the 007 part would disable others
@@ -487,7 +531,7 @@ If the filehandle or descriptor number is preceded not just with a simple
 "&" but rather with a "&=" combination, then Perl will not create a
 completely new descriptor opened to the same place using the dup(2)
 system call.  Instead, it will just make something of an alias to the
-existing one using the fdopen(3S) library call  This is slightly more
+existing one using the fdopen(3S) library call.  This is slightly more
 parsimonious of systems resources, although this is less a concern
 these days.  Here's an example of that:
 
@@ -752,7 +796,7 @@ the doctor ordered.  There's no filehandle interface, but
 it's still easy to get the contents of a document:
 
     use LWP::Simple;
-    $doc = get('http://www.linpro.no/lwp/');
+    $doc = get('http://www.cpan.org/');
 
 =head2 Binary Files
 
@@ -917,7 +961,7 @@ second argument contains something else in addition to the usual
 C<< '<' >>, C<< '>' >>, C<< '>>' >>, C<< '|' >> and their variants,
 for example:
 
-    open(my $fh, "<:utf8", $fn);
+    open(my $fh, "<:crlf", $fn);
 
 =item *