role IO

Input/output related routines

The role provides no methods, but exists so that IO() coercers, which coerce to IO::Path, correctly type-check the resultant value. The role is done by IO::Path and IO::Special.


sub mkdir

Defined as:

sub    mkdir(IO() $pathInt() $mode = 0o777 --> IO::Path:D)

Creates a new directory; see mode for explanation and valid values for $mode. Returns the IO::Path object pointing to the newly created directory on success; fails with X::IO::Mkdir if directory cannot be created.

Also creates parent directories, as needed (similar to *nix utility mkdir with -p option); that is, mkdir "foo/bar/ber/meow" will create foo, foo/bar, and foo/bar/ber directories if they do not exist, as well as foo/bar/ber/meow.

sub chdir

Defined as:

sub chdir(IO() $path:$d = True:$r:$w:$x --> IO::Path:D)

Changes value of $*CWD variable to the provided $path, optionally ensuring the new path passes several file tests. NOTE: that this routine does NOT alter the process's current directory (see &*chdir).

Returns IO::Path representing new $*CWD on success. On failure, returns Failure and leaves $*CWD untouched. The $path can be any object with an IO method that returns an IO::Path object. The available file tests are:

By default, only :d test is performed.

chdir         '/tmp'# change $*CWD to '/tmp' and check its .d is True 
chdir :r:w'/tmp'# … check its .r and .w are True 
chdir '/not-there';   # returns Failure 

Note that the following construct is a mistake:

my $*CWD = chdir '/tmp/';

Use indir instead.

sub &*chdir

Defined as:

PROCESS::<&chdir> = sub (IO() $path --> IO::Path:D{ }

Changes value of $*CWD variable to the provided $path and sets the process's current directory to the value of $path.absolute. NOTE: that in most cases, you want to use chdir routine instead.

Returns IO::Path representing new $*CWD on success. On failure, returns Failure and leaves $*CWD untouched. The $path can be any object with an IO method that returns an IO::Path object.

Note that unlike regular chdir, there are no arguments to specify which file tests to perform.

&*chdir('/tmp');  # change $*CWD and process's current directory to '/tmp' 
&*chdir('/not-there'); # returns Failure 

Note that the following construct is a mistake:

my $*CWD = &*chdir('/tmp');

Use the following, instead; or see indir if you do not need to change process's current directory:

temp $*CWD;

sub chmod

Defined as:

sub chmod(Int() $mode*@filenames --> List)

Coerces all @filenames to IO::Path and calls IO::Path.chmod with $mode on them. Returns a List containing a subset of @filenames for which chmod was successfully executed.

chmod 0o755, <myfile1  myfile2># make two files executable by the owner 

sub indir

Defined as:

sub indir(IO() $path&code:$d = True:$r:$w:$x --> Mu)

Takes Callable &code and executes it after locally (to &code) changing $*CWD variable to an IO::Path object based on $path, optionally ensuring the new path passes several file tests. If $path is relative, it will be turned into an absolute path, even if an IO::Path object was given. NOTE: that this routine does NOT alter the process's current directory (see &*chdir). The $*CWD outside of the &code is not affected, even if &code explicitly assigns a new value to $*CWD.

Returns the return value of &code on success. On failure to successfully change $*CWD, returns Failure. WARNING: keep in mind that lazily evaluated things might end up NOT having the $*CWD set by indir in their dynamic scope by the time they're actually evaluated. Either ensure the generators have their $*CWD set or eagerly evaluate them before returning the results from indir:

say indir("/tmp"{
    gather { take ".".IO }
}.CWD# OUTPUT: «(/home/camelia)␤» 
say indir("/tmp"{
    eager gather { take ".".IO }
}.CWD# OUTPUT: «(/tmp)␤» 
say indir("/tmp"{
    my $cwd = $*CWD;
    gather { temp $*CWD = $cwdtake ".".IO }
}.CWD# OUTPUT: «(/tmp)␤» 

The routine's $path argument can be any object with an IO method that returns an IO::Path object. The available file tests are:

By default, only :d test is performed.

say $*CWD;                   # OUTPUT: «"/home/camelia".IO␤» 
indir '/tmp'{ say $*CWD }# OUTPUT: «"/tmp".IO␤» 
say $*CWD;                   # OUTPUT: «"/home/camelia".IO␤» 
indir '/not-there'{;};     # returns Failure; path does not exist 

sub print

Defined as:

multi sub print(**@args --> True)
multi sub print(Junction:D --> True)

Prints the given text on standard output (the $*OUT filehandle), coercing non-Str objects to Str by calling .Str method. Junction arguments autothread and the order of printed strings is not guaranteed.

print "Hi there!\n";   # OUTPUT: «Hi there!␤» 
print "Hi there!";     # OUTPUT: «Hi there!» 
print [123];       # OUTPUT: «1 2 3» 

To print text and include the trailing newline, use put.

sub put

Defined as:

multi sub put(**@args --> True)
multi sub put(Junction:D --> True)

Same as print, except it uses print-nl (which prints a newline, by default) at the end. Junction arguments autothread and the order of printed strings is not guaranteed.

put "Hi there!\n";   # OUTPUT: «Hi there!␤␤» 
put "Hi there!";     # OUTPUT: «Hi there!␤» 
put [123];       # OUTPUT: «1 2 3␤» 

sub say

Defined as:

multi sub say(**@args --> True)

Prints the "gist" of given objects. Same as put, except uses .gist method to obtain string representation of the object.

NOTE: the .gist method of some objects, such as Lists, returns only partial information about the object (hence the "gist"). If you mean to print textual information, you most likely want to use put instead.

say Range;        # OUTPUT: «(Range)␤» 
say class Foo {}# OUTPUT: «(Foo)␤» 
say 'I ♥ Perl6';  # OUTPUT: «I ♥ Perl6␤» 
say 1..Inf;       # OUTPUT: «1..Inf␤» 

routine note

Defined as:

method note(Mu: -->Bool:D)
multi sub note(            --> Bool:D)
multi sub note(Str:D $note --> Bool:D)
multi sub note(**@args     --> Bool:D)

Like say, except prints output to $*ERR handle (STDERR). If no arguments are given to subroutine forms, will use string "Noted".

note;       # STDERR OUTPUT: «Noted␤» 
note 'foo'# STDERR OUTPUT: «foo␤» 
note 1..*;  # STDERR OUTPUT: «1..Inf␤» 

sub prompt

multi sub prompt()
multi sub prompt($msg)

Prints $msg to $*OUT handle if $msg was provided, then gets a line of input from $*IN handle. By default, this is equivalent to printing $msg to STDOUT, reading a line from STDIN, removing the trailing new line, and returning the resultant string. As of Rakudo 2018.08, prompt will create allomorphs for numeric values, equivalent to calling val prompt.

my $name = prompt "What's your name? ";
say "Hi, $name! Nice to meet you!";
my $age = prompt("Say your age (number)");
my Int $years = $age;
my Str $age-badge = $age;

In the code above, $age will be duck-typed to the allomorph IntStr if it's entered correctly as a number.

sub open

multi sub open(IO() $path|args --> IO::Handle:D)

Creates a handle with the given $path, and calls, passing any of the remaining arguments to it. Note that IO::Path type provides numerous methods for reading and writing from files, so in many common cases you do not need to open files or deal with IO::Handle type directly.

my $fh = open :w'/tmp/some-file.txt';
$fh.say: 'I ♥ writing Perl code';
$fh = open '/tmp/some-file.txt';
print $fh.readchars: 4;
$ 7SeekFromCurrent;
say $fh.readchars: 4;
# OUTPUT: «I ♥ Perl␤» 

sub slurp

Defined as:

multi sub slurp(IO::Handle:D $fh = $*ARGFILES|c)
multi sub slurp(IO() $path|c)

Slurps the contents of the entire file into a Str (or Buf if :bin). Accepts :bin and :enc optional named parameters, with the same meaning as open(); possible encodings are the same as in all the other IO methods and are listed in encoding routine. The routine will fail if the file does not exist, or is a directory. Without any arguments, sub slurp operates on $*ARGFILES, which defaults to $*IN in the absence of any filenames.

# read entire file as (Unicode) Str 
my $text_contents   = slurp "path/to/file";
# read entire file as Latin1 Str 
my $text_contents   = slurp "path/to/file"enc => "latin1";
# read entire file as Buf 
my $binary_contents = slurp "path/to/file":bin;

sub spurt

Defined as:

multi spurt(IO() $path|c)

The $path can be any object with an IO method that returns an IO::Path object. Calls IO::Path.spurt on the $path, forwarding any of the remaining arguments.


The encoding with which the contents will be written.

Boolean indicating whether to append to a (potentially) existing file. If the file did not exist yet, it will be created. Defaults to False.

Boolean indicating whether to fail if the file already exists. Defaults to False.


# write directly to a file 
spurt 'path/to/file''default text, directly written';
# write directly with a non-Unicode encoding 
spurt 'path/to/latin1_file''latin1 text: äöüß':enc<latin1>;
spurt 'file-that-already-exists''some text';           # overwrite file's contents: 
spurt 'file-that-already-exists'' new text':append;  # append to file's contents: 
say slurp 'file-that-already-exists';                    # OUTPUT: «some text new text␤» 
# fail when writing to a pre-existing file 
spurt 'file-that-already-exists''new text':createonly;
# OUTPUT: «Failed to open file /home/camelia/file-that-already-exists: file already exists …» 

sub shell

sub shell($cmd --> Proc)

Runs a command through the system shell, which defaults to %*ENV<ComSpec> /c in Windows, /bin/sh -c otherwise. All shell meta characters are interpreted by the shell, including pipes, redirects, environment variable substitutions and so on. Shell escapes are a severe security concern and can cause confusion with unusual file names. Use run if you want to be safe.

The return value is of type Proc.

shell 'ls -lR | gzip -9 > ls-lR.gz';

See Proc for more details, for example on how to capture output.

Related classes

See also the related classes IO::Handle and IO::Path.

Type Graph

Type relations for IO
perl6-type-graph IO IO Mu Mu Any Any Any->Mu Cool Cool Cool->Any IO::Path IO::Path IO::Path->IO IO::Path->Cool IO::Special IO::Special IO::Special->IO IO::Special->Any IO::Path::Cygwin IO::Path::Cygwin IO::Path::Cygwin->IO::Path IO::Path::Unix IO::Path::Unix IO::Path::Unix->IO::Path IO::Path::Win32 IO::Path::Win32 IO::Path::Win32->IO::Path IO::Path::QNX IO::Path::QNX IO::Path::QNX->IO::Path

Expand above chart