run: Run external command, and wait until finishes

Description Usage Arguments Details Value Callbacks Examples

View source: R/run.R

Description

run provides an interface similar to base::system() and base::system2(), but based on the process class. This allows some extra features, see below.

Usage

1
2
3
4
5
6
run(command = NULL, args = character(), error_on_status = TRUE,
  wd = NULL, echo_cmd = FALSE, echo = FALSE, spinner = FALSE,
  timeout = Inf, stdout_line_callback = NULL, stdout_callback = NULL,
  stderr_line_callback = NULL, stderr_callback = NULL, env = NULL,
  windows_verbatim_args = FALSE, windows_hide_window = FALSE,
  encoding = "", cleanup_tree = FALSE)

Arguments

command

Character scalar, the command to run.

args

Character vector, arguments to the command.

error_on_status

Whether to throw an error if the command returns with a non-zero status, or it is interrupted. The error clases are system_command_status_error and system_command_timeout_error, respectively, and both errors have class system_command_error as well.

wd

Working directory of the process. If NULL, the current working directory is used.

echo_cmd

Whether to print the command to run to the screen.

echo

Whether to print the standard output and error to the screen. Note that the order of the standard output and error lines are not necessarily correct, as standard output is typically buffered.

spinner

Whether to show a reassuring spinner while the process is running.

timeout

Timeout for the process, in seconds, or as a difftime object. If it is not finished before this, it will be killed.

stdout_line_callback

NULL, or a function to call for every line of the standard output. See stdout_callback and also more below.

stdout_callback

NULL, or a function to call for every chunk of the standard output. A chunk can be as small as a single character. At most one of stdout_line_callback and stdout_callback can be non-NULL.

stderr_line_callback

NULL, or a function to call for every line of the standard error. See stderr_callback and also more below.

stderr_callback

NULL, or a function to call for every chunk of the standard error. A chunk can be as small as a single character. At most one of stderr_line_callback and stderr_callback can be non-NULL.

env

Environment of the child process, a named character vector. IF NULL, the environment of the parent is inherited.

windows_verbatim_args

Whether to omit the escaping of the command and the arguments on windows. Ignored on other platforms.

windows_hide_window

Whether to hide the window of the application on windows. Ignored on other platforms.

encoding

The encoding to assume for stdout and stderr. By default the encoding of the current locale is used. Note that processx always reencodes the output of both streams in UTF-8 currently.

cleanup_tree

Whether to clean up the child process tree after the process has finished.

Details

run supports

Value

A list with components:

Callbacks

Some notes about the callback functions. The first argument of a callback function is a character scalar (length 1 character), a single output or error line. The second argument is always the process object. You can manipulate this object, for example you can call $kill() on it to terminate it, as a response to a message on the standard output or error.

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
## Different examples for Unix and Windows
## Not run: 
if (.Platform$OS.type == "unix") {
  run("ls")
  system.time(run("sleep", "10", timeout = 1,
    error_on_status = FALSE))
  system.time(
    run(
      "sh", c("-c", "for i in 1 2 3 4 5; do echo $i; sleep 1; done"),
      timeout = 2, error_on_status = FALSE
    )
  )
} else {
  run("ping", c("-n", "1", "127.0.0.1"))
  run("ping", c("-n", "6", "127.0.0.1"), timeout = 1,
    error_on_status = FALSE)
}

## End(Not run)

r-pkgs/processx documentation built on Oct. 7, 2018, 9:09 a.m.