Skip to main content

module util::ShellExec

rascal-0.34.0

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)

int 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.