my $handle = undef; # this will be filled in on success
open($handle, "< $encoding", $filename)
- || die "$0: can't open $filename for reading: $!\n";
+ || die "$0: can't open $filename for reading: $!";
As with the shell, in Perl the C<< "<" >> is used to open the file in
read-only mode. If it succeeds, Perl allocates a brand new filehandle for
open mode:
open($handle, "<", $filename)
- || die "$0: can't open $filename for reading: $!\n";
+ || die "$0: can't open $filename for reading: $!";
But never use the bare C<< "<" >> without having set up a default encoding
first. Otherwise, Perl cannot know which of the many, many, many possible
my $encoding = ":encoding(UTF-8)";
open($handle, ">> $encoding", $filename)
- || die "$0: can't open $filename for appending: $!\n";
+ || die "$0: can't open $filename for appending: $!";
Now you can write to that filehandle using any of C<print>, C<printf>,
C<say>, C<write>, or C<syswrite>.
my $encoding = ":encoding(UTF-8)";
open($handle, "> $encoding", $filename)
- || die "$0: can't open $filename in write-open mode: $!\n";
+ || die "$0: can't open $filename in write-open mode: $!";
Here again Perl works just like the shell in that the C<< ">" >> clobbers
an existing file.
C<<< ">" >>> as needed:
open($handle, "< $encoding", $filename)
- || die "$0: can't open $filename for reading: $!\n";
+ || die "$0: can't open $filename for reading: $!";
open($handle, ">> $encoding", $filename)
- || die "$0: can't open $filename for appending: $!\n";
+ || die "$0: can't open $filename for appending: $!";
open($handle, "> $encoding", $filename)
- || die "$0: can't open $filename in write-open mode: $!\n";
+ || die "$0: can't open $filename in write-open mode: $!";
Alternately, you can change to binary mode on an existing handle this way:
You can also pass C<binmode> an explicit encoding to change it on the fly.
This isn't exactly "binary" mode, but we still use C<binmode> to do it:
- binmode(STDIN, ":encoding(MacRoman)") || die "cannot binmode STDIN";
- binmode(STDOUT, ":encoding(UTF-8)") || die "cannot binmode STDOUT";
+ binmode(STDIN, ":encoding(MacRoman)") || die "cannot binmode STDIN";
+ binmode(STDOUT, ":encoding(UTF-8)") || die "cannot binmode STDOUT";
Once you have your binary file properly opened in the right mode, you can
use all the same Perl I/O functions as you used on text files. However,
my($in_fh, $out_fh, $buffer);
- open($in_fh, "<", $name_in) || die "$0: cannot open $name_in for reading: $!";
- open($out_fh, ">", $name_out) || die "$0: cannot open $name_out for writing: $!";
+ open($in_fh, "<", $name_in)
+ || die "$0: cannot open $name_in for reading: $!";
+ open($out_fh, ">", $name_out)
+ || die "$0: cannot open $name_out for writing: $!";
for my $fh ($in_fh, $out_fh) {
binmode($fh) || die "binmode failed";
=head1 Opening Pipes
-To be announced.
+Perl also lets you open a filehandle into an external program or shell
+command rather than into a file. You can do this in order to pass data
+from your Perl program to an external command for further processing, or
+to receive data from another program for your own Perl program to
+process.
+
+Filehandles into commands are also known as I<pipes>, since they work on
+similar inter-process communication principles as Unix pipelines. Such a
+filehandle has an active program instead of a static file on its
+external end, but in every other sense it works just like a more typical
+file-based filehandle, with all the techniques discussed earlier in this
+article just as applicable.
+
+As such, you open a pipe using the same C<open> call that you use for
+opening files, setting the second (C<MODE>) argument to special
+characters that indicate either an input or an output pipe. Use C<"-|"> for a
+filehandle that will let your Perl program read data from an external
+program, and C<"|-"> for a filehandle that will send data to that
+program instead.
+
+=head2 Opening a pipe for reading
+
+Let's say you'd like your Perl program to process data stored in a nearby
+directory called C<unsorted>, which contains a number of textfiles.
+You'd also like your program to sort all the contents from these files
+into a single, alphabetically sorted list of unique lines before it
+starts processing them.
+
+You could do this through opening an ordinary filehandle into each of
+those files, gradually building up an in-memory array of all the file
+contents you load this way, and finally sorting and filtering that array
+when you've run out of files to load. I<Or>, you could offload all that
+merging and sorting into your operating system's own C<sort> command by
+opening a pipe directly into its output, and get to work that much
+faster.
+
+Here's how that might look:
+
+ open(my $sort_fh, '-|', 'sort -u unsorted/*.txt')
+ or die "Couldn't open a pipe into sort: $!";
+
+ # And right away, we can start reading sorted lines:
+ while (my $line = <$sort_fh>) {
+ #
+ # ... Do something interesting with each $line here ...
+ #
+ }
+
+The second argument to C<open>, C<"-|">, makes it a read-pipe into a
+separate program, rather than an ordinary filehandle into a file.
+
+Note that the third argument to C<open> is a string containing the
+program name (C<sort>) plus all its arguments: in this case, C<-u> to
+specify unqiue sort, and then a fileglob specifying the files to sort.
+The resulting filehandle C<$sort_fh> works just like a read-only (C<<
+"<" >>) filehandle, and your program can subsequently read data
+from it as if it were opened onto an ordinary, single file.
+
+=head2 Opening a pipe for writing
-=head1 Low-level File Opens via sysopen
+Continuing the previous example, let's say that your program has
+completed its processing, and the results sit in an array called
+C<@processed>. You want to print these lines to a file called
+C<numbered.txt> with a neatly formatted column of line-numbers.
+
+Certainly you could write your own code to do this — or, once again,
+you could kick that work over to another program. In this case, C<cat>,
+running with its own C<-n> option to activate line numbering, should do
+the trick:
+
+ open(my $cat_fh, '|-', 'cat -n > numbered.txt')
+ or die "Couldn't open a pipe into cat: $!";
+
+ for my $line (@processed) {
+ print $cat_fh $line;
+ }
-To be announced. Or deleted.
+Here, we use a second C<open> argument of C<"|-">, signifying that the
+filehandle assigned to C<$cat_fh> should be a write-pipe. We can then
+use it just as we would a write-only ordinary filehandle, including the
+basic function of C<print>-ing data to it.
+
+Note that the third argument, specifying the command that we wish to
+pipe to, sets up C<cat> to redirect its output via that C<< ">" >>
+symbol into the file C<numbered.txt>. This can start to look a little
+tricky, because that same symbol would have meant something
+entirely different had it showed it in the second argument to C<open>!
+But here in the third argument, it's simply part of the shell command that
+Perl will open the pipe into, and Perl itself doesn't invest any special
+meaning to it.
+
+=head2 Expressing the command as a list
+
+For opening pipes, Perl offers the option to call C<open> with a list
+comprising the desired command and all its own arguments as separate
+elements, rather than combining them into a single string as in the
+examples above. For instance, we could have phrased the C<open> call in
+the first example like this:
+
+ open(my $sort_fh, '-|', 'sort', '-u', glob('unsorted/*.txt'))
+ or die "Couldn't open a pipe into sort: $!";
+
+When you call C<open> this way, Perl invokes the given command directly,
+bypassing the shell. As such, the shell won't try to interpret any
+special characters within the command's argument list, which might
+overwise have unwanted effects. This can make for safer, less
+error-prone C<open> calls, useful in cases such as passing in variables
+as arguments, or even just referring to filenames with spaces in them.
+
+However, when you I<do> want to pass a meaningful metacharacter to the
+shell, such with the C<"*"> inside that final C<unsorted/*.txt> argument
+here, you can't use this alternate syntax. In this case, we have worked
+around it via Perl's handy C<glob> built-in function, which evaluates
+its argument into a list of filenames — and we can safely pass that
+resulting list right into C<open>, as shown above.
+
+Note also that representing piped-command arguments in list form like
+this doesn't work on every platform. It will work on any Unix-based OS
+that provides a real C<fork> function (e.g. macOS or Linux), as well as
+on Windows when running Perl 5.22 or later.
=head1 SEE ALSO
-To be announced.
+The full documentation for L<C<open>|perlfunc/open FILEHANDLE,MODE,EXPR>
+provides a thorough reference to this function, beyond the best-practice
+basics covered here.
=head1 AUTHOR and COPYRIGHT
-Copyright 2013 Tom Christiansen.
+Copyright 2013 Tom Christiansen; now maintained by Perl5 Porters
This documentation is free; you can redistribute it and/or modify it under
the same terms as Perl itself.