Execute single or multiple R, R Markdown, and Quarto scripts

Executes and logs the execution of the scripts. Logs for each script are stored in the same folder as the script.

The way the execution is logged is configurable through several options for e.g. the verbosity of the logs. See options on how to configure these.

Usage

run(
  input,
  steps = NULL,
  summary_file = "summary.html",
  n_workers = options::opt("n_workers", env = "whirl"),
  check_renv = options::opt("check_renv", env = "whirl"),
  verbosity_level = options::opt("verbosity_level", env = "whirl"),
  track_files = options::opt("track_files", env = "whirl"),
  out_formats = options::opt("out_formats", env = "whirl"),
  log_dir = options::opt("log_dir", env = "whirl")
)

Arguments

input: A character vector of file path(s) to R, R Markdown, Quarto scripts, or files in a folder using regular expression, or to to a whirl config file. The input can also be structured in a list where each element will be executed sequentially, while scripts within each element can be executed in parallel.
steps: An optional argument that can be used if only certain steps within a config files (or list) is to be executed. Should be equivalent to the names of the steps found in the config file. If kept as NULL (default) then all steps listed in the config file will be executed.
summary_file: A character string specifying the file path where the summary log will be stored.
n_workers: Number of simultanous workers used in the run function. A maximum of 128 workers is allowed. (Defaults to 1, overwritable using option 'whirl.n_workers' or environment variable 'R_WHIRL_N_WORKERS')
check_renv: Should the projects renv status be checked? (Defaults to FALSE, overwritable using option 'whirl.check_renv' or environment variable 'R_WHIRL_CHECK_RENV')
verbosity_level: How chatty should the log be? Possibilities are quiet, minimal and verbose. (Defaults to "verbose", overwritable using option 'whirl.verbosity_level' or environment variable 'R_WHIRL_VERBOSITY_LEVEL')
track_files: Should files read and written be tracked? Currently only supported on Linux. (Defaults to FALSE, overwritable using option 'whirl.track_files' or environment variable 'R_WHIRL_TRACK_FILES')
out_formats: Which log format(s) to produce. Possiblities are html, json, and markdown formats:gfm, commonmark, and markua. (Defaults to "html", overwritable using option 'whirl.out_formats' or environment variable 'R_WHIRL_OUT_FORMATS')
log_dir: The output directory of the log files. Default is the folder of the excuted script. log_dir can be a path as a character or it can be a function that takes the script path as input and returns the log directory. For more information see the examples of run() or vignette('whirl'). (Defaults to dirname, overwritable using option 'whirl.log_dir' or environment variable 'R_WHIRL_LOG_DIR')

Value

A tibble containing the execution results for all the scripts.

Examples

# Start by copying the following three example scripts:
file.copy(
  from = system.file("examples", c("success.R", "warning.R", "error.R"), package = "whirl"),
  to = "."
  )
#> [1] TRUE TRUE TRUE

# Run a single script
run("success.R")
#> ══ Executing scripts and generating logs ═══════════════════════════════════════
#> Executing scripts in parallel using 1 cores
#> The following steps will be executed
#> • Step 1: Unnamed chunk
#> 
#> ── Step 1: Unnamed chunk ───────────────────────────────────────────────────────
#> ✔ success.R: Completed succesfully
#> 
#> ══ End of process ══════════════════════════════════════════════════════════════

# Run several scripts in parallel on up to 2 workers
run(c("success.R", "warning.R", "error.R"), n_workers = 2)
#> ══ Executing scripts and generating logs ═══════════════════════════════════════
#> Executing scripts in parallel using 2 cores
#> The following steps will be executed
#> • Step 1: Unnamed chunk
#> 
#> ── Step 1: Unnamed chunk ───────────────────────────────────────────────────────
#> ✔ success.R: Completed succesfully
#> ⚠ warning.R: Completed with warnings
#> ✖ error.R: Completed with errors
#> 
#> ══ End of process ══════════════════════════════════════════════════════════════

# Run scripts in two steps by providing them as list elements
run(
  list(
    c("success.R", "warning.R"),
    "error.R"
    ),
   n_workers = 2)
#> ══ Executing scripts and generating logs ═══════════════════════════════════════
#> Executing scripts in parallel using 2 cores
#> The following steps will be executed
#> • Step 1: Unnamed chunk
#> • Step 2: Unnamed chunk
#> 
#> ── Step 1: Unnamed chunk ───────────────────────────────────────────────────────
#> ✔ success.R: Completed succesfully
#> ⚠ warning.R: Completed with warnings
#> 
#> 
#> ── Step 2: Unnamed chunk ───────────────────────────────────────────────────────
#> ✖ error.R: Completed with errors
#> 
#> ══ End of process ══════════════════════════════════════════════════════════════

if (FALSE) {

# Re-directing the logs to a sub-folder by utilizing the log_dir argument in
# run(). This will require that the sub-folder exist and the code is therefore
# not executed

# Specifying the path using a manually defined character
run("success.R", log_dir = getwd())

# Specifying the path with a generic function that can handle the scripts
# individually.
run("success.R", log_dir = function(x) {paste0(dirname(x), "/logs")})
}