Skip to main content

module util::ShellExec

rascal-0.40.16

Execute and manage external processes.

Usage​

import util::ShellExec;

function createProcess​

Start a new external process.

PID createProcess(str processCommand, loc workingDir=|cwd:///|, list[str] args = [], map[str,str] envVars = ())

function createProcess​

Start a new external process.

PID createProcess(loc processCommand, loc workingDir=|cwd:///|, list[value] args = [], map[str, value] envVars = ())

The file schemes that are allowed for the processCommand are limited to the file:/// schemes and all logical schemes that directly resolve to file:/// such as cwd:/// and tmp:///. PATH:/// is also a handy scheme for processCommand since it searches for the binary/script in the underlying system's search path.

The arguments to args given are all converted to strings before passing them into the command. Special treatment is given to loc arguments, which are first resolved to file:/// schemes and then printed to OS-specific absolute path names.

For environment variables in envVars the same treatment is given to convert values to strings.

function exec​

Start, run and kill an external process returning its output as a string.

str exec(str processCommand, loc workingDir=|cwd:///|, list[str] args = [], map[str, str] env = ())

function exec​

Start, run and kill an external process returning its output as a string.

str exec(loc processCommand, loc workingDir=|cwd:///|, list[value] args = [], map[str, value] env = ())

function execWithCode​

tuple[str output, int exitCode] execWithCode(str processCommand, loc workingDir=|cwd:///|, list[str] args = [], map[str, str] env = ())

function execWithCode​

Start, run and kill an external process returning its output as a string with an exit code.

tuple[str output, int exitCode] execWithCode(loc processCommand, loc workingDir=|cwd:///|, list[value] args = [], map[str, value] env = ())

function killProcess​

Kill a running process, or a zombie process (a process which is not alive yet not killed).

void killProcess(PID processId, bool force=false)

function isAlive​

Check whether a process is still alive.

bool isAlive(PID processId)

function isZombie​

Check whether a process is still registered but not actually running anymore. A zombie process may be cleaned up using killProcess.

bool isZombie(PID processId)

function exitCode​

Waits for the process to exit and then returns its return code. This is a blocking operation.

int exitCode(PID processId)

function readFrom​

Read from an existing process's output stream. This is non-blocking.

str readFrom(PID processId)

function readWithWait​

Read from an existing process's output stream with a given wait timeout. Some processes are a little slower in producing output. The wait is used to give the process some extra time in producing output. This is non-blocking apart from the waiting.

str readWithWait(PID processId, int wait)

function readFromErr​

Read from an existing process's error output stream. This is non-blocking.

str readFromErr(PID processId)

function readLineFromErr​

Read from an existing process's error output stream. This blocks until a full line is read and waits for one second maximally for this line to appear.

str readLineFromErr(PID processId, int wait=200, int maxTries=5)

function readEntireStream​

Read the entire stream from an existing process's output stream. This is blocking.

str readEntireStream(PID processId)

function readEntireErrStream​

Read the entire error stream from an existing process's output stream. This is blocking.

str readEntireErrStream(PID processId)

function writeTo​

Write to an existing process's input stream.

void writeTo(PID processId, str msg)

alias PID​

Process Identifiers (PID).

int

A PID is returned by Create Process and is required for any further interaction with the created process.