system3: Run a system command quietly unless there's errors

In OchoaLab/genbin: R wrappers for binaries in genetics

Run a system command quietly unless there's errors

Description

A wrapper around system2() with some modified behaviors for error cases. When the command is successful, all STDOUT/STDERR output from the binary is omitted (assumes it is useless most of the time). When the command fails, by default the R command stops, showing the full STDOUT/STDERR output as the error message. However, when ret = TRUE the full STDOUT/STDERR output is returned as a string, and the return value is returned as the "status" attribute (just as system2() returns it, see that for more info). The ret = TRUE case tries to avoid producing errors and warnings, allowing for error recovery, though in some cases this is unavoidable (for example, when "command" doesn't exist).

Usage

system3(command, args = character(), verbose = TRUE, ret = FALSE)

Arguments

command	The command name, passed to system2().
args	Optional arguments, passed to system2().
verbose	If TRUE (default), prints the command line before it is executed, otherwise it is ommitted.
ret	If TRUE, returns STDOUT/STDERR output as a string vector, with return value as the "status" attribute, just as system2() returns it when its options are set to stdout = TRUE and stderr = TRUE. If FALSE (default), nothing is returned, and execution is quiet if successful and stops with full STDOUT/STDERR output if unsuccessful.

Value

Nothing if ret = FALSE (default), otherwise the STDOUT/STDERR output with return value as the "status" attribute (see ret option above).

See Also

system2()

Examples

# an example where nothing really happens and nothing is returned
system3( 'ls', '-lh' )

# an example that returns the output of `ls`
# (detailed table of files in current dir)
out <- system3( 'ls', '-lh', ret = TRUE )

# error handling is the cool part!

# passing a command that doesn't exist produces an error no matter what
try( system3( 'flmsdmfr' ) )
try( out <- system3( 'flmsdmfr', ret = TRUE ) )

# passing a good command with bad arguments, or other behaviors that lead the 
# command to start executing but fail and return a non-zero exit status makes
# `system3` fail by default, and output STDOUT/STDERR as the error message...
try( system3( 'ls', 'file-that-doesnt-exist' ) )

# ... but not if `ret = TRUE`, allowing for easier error recovery by examining
# its output.
out <- system3( 'ls', 'file-that-doesnt-exist', ret = TRUE )
# error status is this attribute:
attr( out, "status" )

OchoaLab/genbin documentation built on Nov. 14, 2024, 7:33 p.m.