record {xfun}

Run R code and record the results

Description

Run R code and capture various types of output, including text output, plots, messages, warnings, and errors.

Usage

record(
  code = NULL,
  dev = "png",
  dev.path = "xfun-record",
  dev.ext = dev_ext(dev),
  dev.args = list(),
  message = TRUE,
  warning = TRUE,
  error = NA,
  cache = list(),
  print = record_print,
  print.args = list(),
  verbose = getOption("xfun.record.verbose", 0),
  envir = parent.frame()
)

## S3 method for class 'xfun_record_results'
format(x, to = c("text", "html"), encode = FALSE, template = FALSE, ...)

## S3 method for class 'xfun_record_results'
print(
  x,
  browse = interactive(),
  to = if (browse) "html" else "text",
  template = TRUE,
  ...
)

Arguments

code

A character vector of R source code.

dev

A graphics device. It can be a function name, a function, or a character string that can be evaluated to a function to open a graphics device.

dev.path

A base file path for plots. Actual plot filenames will be this base path plus incremental suffixes. For example, if dev.path = "foo", the plot files will be ⁠foo-1.png⁠, ⁠foo-2.png⁠, and so on. If dev.path is not character (e.g., FALSE), plots will not be recorded.

dev.ext

The file extension for plot files. By default, it will be inferred from the first argument of the device function if possible.

dev.args

Extra arguments to be passed to the device. The default arguments are list(units = 'in', onefile = FALSE, width = 7, height = 7, res = 96). If any of these arguments is not present in the device function, it will be dropped.

message, warning, error

If TRUE, record and store messages / warnings / errors in the output. If FALSE, suppress them. If NA, do not process them (messages will be emitted to the console, and errors will halt the execution).

cache

A list of options for caching. See the path, id, and ... arguments of cache_exec().

print

A (typically S3) function that takes the value of an expression in the code as input and returns output. The default is record_print().

print.args

A list of arguments for the print function. By default, the whole list is not passed directly to the function, but only an element in the list with a name identical to the first class name of the returned value of the expression, e.g., list(data.frame = list(digits = 3), matrix = list()). This makes it possible to apply different print arguments to objects of different classes. If the whole list is intended to be passed to the print function directly, wrap the list in I().

verbose

2 means to always print the value of each expression in the code, no matter if the value is invisible() or not; 1 means to always print the value of the last expression; 0 means no special handling (i.e., print only when the value is visible).

envir

An environment in which the code is evaluated.

x

An object returned by record().

to

The output format (text or html).

encode

For HTML output, whether to base64 encode plots.

template

For HTML output, whether to embed the formatted results in an HTML template. Alternatively, this argument can take a file path, i.e., path to an HTML template that contains the variable ⁠$body$⁠. If TRUE, the default template in this package will be used (xfun:::pkg_file('resources', 'record.html')).

...

Currently ignored.

browse

Whether to browse the results on an HTML page.

Value

record() returns a list of the class xfun_record_results that contains elements with these possible classes: record_source (source code), record_output (text output), record_plot (plot file paths), record_message (messages), record_warning (warnings), and record_error (errors, only when the argument error = TRUE).

The format() method returns a character vector of plain-text output or HTML code for displaying the results.

The print() method prints the results as plain text or HTML to the console or displays the HTML page.

Examples

code = c("# a warning test", "1:2 + 1:3", "par(mar = c(4, 4, 1, .2))",
    "barplot(5:1, col = 2:6, horiz = TRUE)", "head(iris)",
    "sunflowerplot(iris[, 3:4], seg.col = 'purple')",
    "if (TRUE) {\n  message('Hello, xfun::record()!')\n}",
    "# throw an error", "1 + 'a'")
res = xfun::record(code, dev.args = list(width = 9, height = 6.75),
    error = TRUE)
xfun::tree(res)
format(res)
# find and clean up plot files
plots = Filter(function(x) inherits(x, "record_plot"),
    res)
file.remove(unlist(plots))