Documentation for routine run assembled from the following types:

class Thread

From Thread

(Thread) method run

method run(Thread:D:)

Runs the thread, and returns the invocant. It is an error to run a thread that has already been started.

language documentation Independent routines

From Independent routines

(Independent routines) sub run

Defined as:

sub run(
    *@args ($, *@),
    :$in = '-',
    :$out = '-',
    :$err = '-',
    Bool :$bin = False,
    Bool :$chomp = True,
    Bool :$merge = False,
    Str:D :$enc = 'UTF-8',
    Str:D :$nl = "\n",
    :$cwd = $*CWD,
    Hash() :$env = %*ENV
--> Proc:D)

Runs an external command without involving a shell and returns a Proc object. By default, the external command will print to standard output and error, and read from standard input.

run 'touch', '>foo.txt'; # Create a file named >foo.txt 
 
run <<rm >foo.txt>>; # Another way to use run, using word quoting for the 
                     # arguments

If you want to pass some variables you can still use < >, but try to avoid using « » as it will do word splitting if you forget to quote variables:

my $file = ‘--my arbitrary filename’;
run ‘touch’, ‘--’, $file;  # RIGHT 
run <touch -->, $file;     # RIGHT 
 
run «touch -- "$file"»;    # RIGHT but WRONG if you forget quotes 
run «touch -- $file»;      # WRONG; touches ‘--my’, ‘arbitrary’ and ‘filename’ 
run ‘touch’, $file;        # WRONG; error from `touch` 
run «touch "$file"»;       # WRONG; error from `touch` 

Note that -- is required for many programs to disambiguate between command-line arguments and filenames that begin with hyphens.

A sunk Proc object for a process that exited unsuccessfully will throw. If you wish to ignore such failures, simply use run in non-sink context:

run 'false';     # SUNK! Will throw 
run('false').so; # OK. Evaluates Proc in Bool context; no sinking

If you want to capture standard output or error instead of having it printed directly you can use the :out or :err arguments, which will make them available using their respective methods: Proc.out and Proc.err.

my $proc = run 'echo', 'Perl 6 is Great!', :out, :err;
$proc.out.slurp(:close).say; # OUTPUT: «Perl 6 is Great!␤» 
$proc.err.slurp(:close).say; # OUTPUT: «␤»

You can use these arguments to redirect them to a filehandle, thus creating a kind of pipe:

my $ls-alt-handle = open :w, '/tmp/cur-dir-ls-alt.txt';
my $proc = run "ls", "-alt", :out($ls-alt-handle);
# (The file will contain the output of the ls -alt command)

These argument are quite flexible and admit, for instance, handles to redirect them. See Proc and Proc::Async for more details.

See also new for more examples.