Rules / Types, classes & roles / domain-specific

Proc Reference

Running process (filehandle-based interface)

What it is #

Routines #

Signatures are reproduced from the documentation, including their declared return types. A routine listed here is part of the type's published interface; whether Raku++ implements it is a separate question, answered by the examples below.

routine new #

new creates a new Proc object, whereas run or shell create one and spawn it with the command and arguments provided in @args or $cmd, respectively. $in, $out and $err are the three standard streams of the to-be-launched program, and default to "-" meaning they inherit the stream from the parent process. Setting one (or more) of them to True makes the stream available as

method sink #

method sink(--> Nil)

Returns Nil.

When sunk, the Proc object will throw X::Proc::Unsuccessful if the process it ran exited unsuccessfully.

method spawn #

method spawn(*@args ($, *@), :$cwd = $*CWD, Hash() :$env = %*ENV, :$arg0,

Runs the Proc object with the given command, argument list, working directory, and environment. If :arg0 is set to a value, that value is passed as arg0 to the process instead of the program name. On Windows the flag $win-verbatim-args disables all automatic quoting of process arguments. See this blog

method shell #

method shell($cmd, :$cwd = $*CWD, :$env --> Bool:D)

Returns Bool:D.

Runs the Proc object with the given command and environment which are passed through to the shell for parsing and execution. See shell for an explanation of which shells are used by default in the most common operating systems.

method command #

method command(Proc:D: --> List:D)

Returns List:D.

The command method is an accessor to a list containing the arguments that were passed when the Proc object was executed via spawn or shell or run.

method Bool #

multi method Bool(Proc:D:)

Awaits for the process to finish and returns True if both exit code and signal of the process were 0, indicating a successful process termination. Returns False otherwise.

method pid #

method pid()

Returns the PID value of the process if available, or Nil.

method exitcode #

method exitcode(Proc:D: --> Int:D)

Returns Int:D.

Returns the exit code of the external process, or -1 if it has not exited yet.

method signal #

method signal(Proc:D:)

Returns the signal number with which the external process was killed, or 0 or an undefined value otherwise.

Examples, run three ways #

Every example below comes from the official documentation, together with the output that documentation asserts. Each was then executed by Rakudo and by Raku++ when this page was built. Where the three agree, one result is shown; where they do not, all three are — because which of them is wrong is exactly the information worth having.

8 no-output · 1 not-runnable · 1 ok

class Proc {}

Not executed: the documentation states no expected output for this example.

my $proc = run 'echo', 'Hallo world', :out;
my $captured-output = $proc.out.slurp: :close;
say "Output was $captured-output.raku()";# OUTPUT: «Output was "Hallo world\n"␤»
Output
Output was "Hallo world\n"

Documentation, Rakudo and Raku++ all agree.

my $p1 = run 'echo', 'Hello, world', :out;
my $p2 = run 'cat', '-n', :in($p1.out), :out;
say $p2.out.get;

Not executed: the documentation states no expected output for this example.

my $p = run "cat", "-n", :in, :out;
$p.in.say: "Hello,\nworld!";
$p.in.close;
say $p.out.slurp: :close;
# OUTPUT: «1  Hello,␤
#          2  world!␤»

Not executed: the documentation states no expected output for this example.

my $p = run "ls", "-l", ".", "qqrq", :out, :err;
my $captured-output = $p.out.slurp: :close;
my $captured-error  = $p.err.slurp: :close;
my $exit-code       = $p.exitcode;

Not executed: the documentation states no expected output for this example.

shell 'exit 1'
# OUTPUT: «(exit code 1) The spawned command 'exit 1' exited unsuccessfully (exit code: 1)␤»

Neither engine can run this in isolation — the example depends on context from the surrounding text.

method new(Proc:U:
    :$in = '-',
    :$out = '-',
    :$err = '-',
    Bool :$bin = False,
    Bool :$chomp = True,
    Bool :$merge = False,
    Str:D :$enc = 'UTF-8',
    Str:D :$nl = "\n",
--> Proc:D)

sub shell(
    $cmd,
    :$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)

Not executed: the documentation states no expected output for this example.

my $p-name = "/tmp/program.raku";
my $program = Q:to/END/;
#!/usr/bin/env raku

$*OUT.say( qq/\t$*PROGRAM: This goes to standard output/ );
END

spurt $p-name, $program;

$*OUT.put: "1. standard output before doing anything weird";

{
temp $*OUT = open '/tmp/out.txt', :w;
$*OUT.put: "2. temp redefine standard output before this message";
shell( "raku $p-name" ).so;
}

$*OUT.put: "3. everything should be back to normal";
# OUTPUT
# 1. standard output before doing anything weird
#     /tmp/program.raku: This goes to standard output
# 3. everything should be back to normal

# /tmp/out.txt will contain:
# 2. temp redefine standard output before this message

Not executed: the documentation states no expected output for this example.

shell 'ls /qqq';
# OUTPUT:
# (exit code 1) ls: cannot access '/qqq': No such file or directory
# The spawned command 'ls /qqq' exited unsuccessfully (exit code: 2)
#   in block <unit> at /tmp/3169qXElwq line 1
#

Not executed: the documentation states no expected output for this example.

             :$win-verbatim-args = False --> Bool:D)

Not executed: the documentation states no expected output for this example.