Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 43 ยท Files and I/O

Reading and Writing Files

Read and write files in Perl the safe way: three-argument open, lexical filehandles, die on failure, the diamond operator, chomp, append mode and UTF-8 layers.

Almost every useful Perl script reads or writes files: a log to scan, a CSV to convert, a report to save. Perl makes this easy, but it also keeps a lot of old habits around. This lesson teaches the modern, safe way to do file input and output, and points out the old forms you will meet in legacy code so you can recognize and replace them.

The core idea is simple: you open a file to get a filehandle, you read from or write to that handle, and you close it. Along the way you should always check whether open worked.

Perl is not installed on this site, so the Perl code is read-only; its output is shown below each snippet. The interactive examples are Bash stand-ins that perform the same steps (create, append, read line by line, handle a missing file) with shell tools in a temporary folder.

Opening a file

The recommended form is the three-argument open: a lexical filehandle, a mode, and the file name as separate arguments.

PERL
use v5.36;

my $file = "notes.txt";
open(my $in, '<', $file) or die "Cannot open '$file': $!";
  • my $in creates a lexical filehandle, a normal variable that holds the handle. It is closed automatically when the variable goes out of scope, and it cannot clash with other code. Old programs use global barewords such as open(FH, "<$file"). Avoid them.
  • The mode is its own argument, so a strange file name can never be mistaken for a mode. The old two-argument open(FH, $file) treats characters like > or | in the name as instructions, which is a security problem (see Security and Safe Perl).
  • $! holds the system's error message for the last failure, such as No such file or directory or Permission denied. Always include it in your die message.
Mode Meaning
< Read an existing file
> Write: create the file, or erase it if it exists
>> Append: add to the end, creating the file if needed
+< Read and write an existing file
+> Read and write, erasing the file first
+>> Read and append: reads anywhere, every write goes to the end

use autodie; at the top of a script makes open, close and many other built-ins die automatically with a clear message, so you can drop the or die ... parts. It is part of core Perl and a good habit in scripts:

PERL
use v5.36;
use autodie;

open(my $in, '<', "notes.txt");     # dies by itself if it fails

Reading lines

In scalar context, <$in> reads one line, including the trailing newline. chomp removes that newline. The usual loop:

PERL
open(my $in, '<', "colors.txt") or die "Cannot open: $!";
while (my $line = <$in>) {
    chomp $line;
    say "$.: $line";
}
close($in);

If colors.txt contains red, green and blue on three lines, the output is:

TEXT
1: red
2: green
3: blue

$. is the line number of the handle that was read most recently. Notice that the loop condition is just an assignment: Perl treats while (my $line = <$in>) as a test for defined, so a line containing only 0 does not stop the loop early.

In list context the whole file is read at once, one array element per line:

PERL
chomp(my @lines = <$in>);
say scalar @lines;            # 3

To read the entire file into one string (called slurping), temporarily clear the input record separator $/:

PERL
my $content = do { local $/; <$in> };

Slurping is convenient for small files, but it loads everything into memory. For large files, read line by line.

Writing and appending

To write, open with > and print to the handle. There is no comma between the handle and the first item:

PERL
open(my $out, '>', "report.txt") or die "Cannot write: $!";
print $out "Report\n";
printf $out "%-8s %3d\n", "apples", 12;
say $out "done";              # say adds a newline
close($out) or die "Cannot close: $!";

report.txt now contains:

TEXT
Report
apples    12
done

Two cautions. If a handle expression is more complex than a plain variable, wrap it in braces: print {$handles{log}} "text\n";. And always check close on files you wrote: a full disk or a network drive may report the error only when the buffer is flushed at close time.

Opening with > erases the file immediately. To add lines to an existing file, use >>:

PERL
open(my $log, '>>', "app.log") or die "Cannot append: $!";
say $log "started";
close($log);

The standard streams are always open: STDIN for input, STDOUT for normal output (the default for print) and STDERR for errors and diagnostics: print STDERR "warning\n";.

The life of a filehandle

Open Three arguments, and check the result.
Read or write Read lines with the diamond, write with print.
Close Automatic at scope end, explicit for writes.

Always handle failure with die, or use autodie.

1 / 2
Bash Create, append and read a file (Bash stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The diamond operator

The empty handle <> (the diamond operator) reads lines from every file named on the command line, one after another, or from standard input if there are none. It is the foundation of Unix-style filter scripts:

PERL
while (my $line = <>) {
    chomp $line;
    say "$ARGV:$.: $line";
}

Run as perl numbered.pl a.txt b.txt, this prints each line with its file name and line number. $ARGV is the current file name. The double diamond <<>> (Perl 5.22 and later) is safer: it treats each argument strictly as a file name, whereas plain <> gives special meaning to names such as ls |. Prefer <<>> in new scripts.

To read from the keyboard or a pipe explicitly, use STDIN:

PERL
print "Your name? ";
chomp(my $name = <STDIN> // '');
say "Hello, $name!";

The // '' guards against end-of-input, where <STDIN> returns undef.

Encodings

A filehandle reads and writes bytes unless you tell Perl otherwise. For text in UTF-8 (the right choice almost everywhere), add an encoding layer to the mode:

PERL
open(my $in,  '<:encoding(UTF-8)', "names.txt") or die "Cannot open: $!";
open(my $out, '>:encoding(UTF-8)', "copy.txt")  or die "Cannot write: $!";

Use :encoding(UTF-8) rather than the looser :utf8, because it validates the data. For binary files such as images, use binmode($fh) (or :raw) so that Perl does no newline or encoding translation, and read chunks with read($fh, my $buf, 4096).

To apply UTF-8 to every file you open, and to the standard streams, put this near the top of the script:

PERL
use open qw(:std :encoding(UTF-8));

Do not confuse it with use utf8;, which only says that the source code of your script itself is written in UTF-8, so that string literals with accents or other letters are read correctly.

Useful extras

  • In-memory files. Pass a reference to a string and use it like a file, which is handy for tests: open(my $fh, '<', \$text).
  • Other file operations. unlink $file deletes, rename $old, $new renames, seek and tell move around, and eof($fh) tests for the end.
  • Safe updates. To rewrite a file without risking a half-written result, write a new file next to it and rename it over the old one once it is complete.
  • Do not test first. Checking -e $file and then opening it leaves a gap in which the file can change. Just try open and handle the failure. (The -e tests and friends are in Directories and File Tests.)
Bash Handling a file that does not exist (Bash stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which open call is the recommended modern form?

    The three-argument form with a lexical filehandle keeps the mode separate from the file name, and the or die reports the system error held in $!.
  2. 2. What happens when you open an existing file with mode >?

    > truncates the file as soon as it is opened. Use >> to append.
  3. 3. What does chomp do to a line read with <$fh>?

    chomp removes the line terminator (normally a newline) from the end of the string and leaves the rest alone.
  4. 4. What is the value of $. inside while (my $line = <$in>)?

    $. counts the lines read so far from the most recently read filehandle.
  5. 5. How do you read a UTF-8 text file correctly?

    The :encoding(UTF-8) layer decodes the bytes while reading. use utf8; only concerns the encoding of the script's source code.

Summary

  • Use three-argument open with a lexical filehandle, and always handle failure with or die "...: $!" or use autodie.
  • Modes: < read, > write (erases), >> append, +< read and write.
  • while (my $line = <$fh>) reads line by line; chomp removes the newline; $. is the line number.
  • print $fh ... has no comma after the handle; check close for files you wrote.
  • <> and the safer <<>> read the files named in @ARGV, or standard input.
  • Add :encoding(UTF-8) to text handles, and use binmode for binary data.

Next, find, list and test files and folders in Directories and File Tests.