motus.org

safeSys

R Documentation

Call an external program safely, return its output and propagate any error into R.

Description

This function provides the sole access point to external programs for this package.

Usage

safeSys(cmd, ..., shell = TRUE, quote = TRUE, minErrorCode = 1,
  splitOutput = FALSE)

Arguments

`cmd`	full path to the executable file (can be a shell script, for example)
`...`	list of named or unnamed parameters to the command; if `shell == TRUE`, the unnamed parameters are quoted as appropriate for a bash-type shell. Otherwise, they are passed as-is. Named parameters are always left unquoted, on the assumption that the caller has verified they are already safe.
`shell`	logical scalar; if TRUE, invoke command using a shell; otherwise, invoke cmd directly.
`quote`	logical scalar; if TRUE (the default) and if `shell == TRUE`, quote individual arguments for the shell
`minErrorCode`	the smallest integer return value that indicates an error. Some programs (e.g. 'grep') violate the usual convention that 0 = no error, and > 0 indicates an error. Default: 1
`splitOutput`	logical; if TRUE, output is returned as a vector with one item per line. Otherwise, the default, output is returned as a character scalar with embedded newlines.

Details

If the exit status of the command is non-zero, then this function triggers an error using stop(E) where the message E will be a character scalar consisting of the lines written to stderr by the command, pasted together with "\n".

Otherwise, this function returns a character scalar with liens written to stdout by the command, pasted together with "\n".

The point of internalizing errors is so that we save the intermediate files and record a full stack dump. Otherwise, the server might delete downloaded files, thinking (incorrectly) that it has processed them successfully.

Value

character vector of the stdout stream from running cmd, as one long item. This will have attribute "exitCode" giving the exit code of the command, which will be in the range 0: (minErrorCode - 1)