File-related operations

Here we present a quick overview of the file-related input/output operations. Details can be found in the documentation for the IO role, as well as the IO::Handle and IO::Path types.

Reading from files

One way to read the contents of a file is to open the file via the open function with the :r (read) file mode option and slurp in the contents:

my $fh = open "testfile", :r;
my $contents = $fh.slurp-rest;

Here we explicitly close the file handle using the close method on the IO::Handle object. This is a very traditional way of reading the contents of a file. However, the same can be done more easily and clearly like so:

my $contents = "testfile".IO.slurp;
# or in procedural form:
$contents = slurp "testfile"

By adding the IO role to the file name string, we are effectively able to refer to the string as the file object itself and thus slurp in its contents directly. Note that the slurp takes care of opening and closing the file for you.

Line by line

Of course, we also have the option to read a file line-by-line. The new line separator (i.e., $* will be excluded.

for 'huge-csv'.IO.lines -> $line {
    # Do something with $line
# or if you'll be processing later
my @lines = 'huge-csv'.IO.lines;

Writing to files

To write data to a file, again we have the choice of the traditional method of calling the open function – this time with the :w (write) option -- and printing the data to the file:

my $fh = open "testfile", :w;
$fh.print("data and stuff\n");

Or equivalently with say, thus the explicit newline is no longer necessary:

my $fh = open "testfile", :w;
$fh.say("data and stuff");

We can simplify this by using spurt to open the file in write mode, writing the data to the file and closing it again for us:

spurt "testfile", "data and stuff\n";

By default all (text) files are written as UTF-8, however if necessary, an explicit encoding can be specified via the :enc option:

spurt "testfile", "latin1 text: äöüß", enc => "latin1";

Writing formatted strings to a file is not directly supported at the moment because function 'printf' is not yet a method of IO::Handle. However, as a work-around, one can use function 'sprintf' to assign a formatted string to a Str object that can then be used with methods '.say' or '.print' as desired.

To append to a file, specify the :a option when opening the file handle explicitly,

my $fh = open "testfile", :a;
$fh.print("more data\n");

or equivalently with say, thus the explicit newline is no longer necessary,

my $fh = open "testfile", :a;
$fh.say("more data");

or even simpler with the :append option in the call to spurt:

spurt "testfile", "more data\n", :append;

To explicitly write binary data to a file, open it with the :bin option. The input/output operations then will take place using the Buf type instead of the Str type.

Checking files and directories

Use the e method on an IO::Handle object to test whether the file or directory exists.

if "nonexistent_file".IO.e {
    say "file exists";
else {
    say "file doesn't exist";

It is also possible to use the colon pair syntax to achieve the same thing:

if "path/to/file".IO ~~ :e {
    say 'file exists';
my $file = "path/to/file";
if $file.IO ~~ :e {
    say 'file exists';

Similarly to the file existence check, one can also check to see if a path is a directory. For instance, assuming that the file testfile and the directory lib exist, we would obtain from the existence test method e the same result, namely that both exist:

say "testfile".IO.e;  # True
say "lib".IO.e;       # True

However, since only one of them is a directory, the directory test method d will give a different result:

say "testfile".IO.d;  # False
say "lib".IO.d;       # True

Naturally the tables are turned if we check to see if the path is a file via the file test method f:

say "testfile".IO.f;  # True
say "lib".IO.f;       # False

Getting a directory listing

To list the contents of the current directory, use the dir function. It returns a list of IO::Path objects.

say dir;    # "/path/to/testfile".IO "/path/to/lib".IO

To list the files and directories in a given directory, simply pass a path as an argument to dir:

say dir "/etc/";    # "/etc/".IO "/etc/shadow".IO ....

Creating and removing directories

To create a new directory, simply call the mkdir function with the directory name as its argument:

mkdir "newdir";

The function returns the name of the created directory on success and Nil on failure. Thus the standard Perl idiom works as expected:

mkdir "newdir" or die "$!";

Use rmdir to remove empty directories:

rmdir "newdir" or die "$!";