xfun (version 0.43)

record: 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 = tempfile("record-", "."),
  dev.ext = dev_ext(dev),
  dev.args = list(),
  error = FALSE,
  verbose = getOption("xfun.record.verbose", 0),
  envir = parent.frame()
)
# S3 method for xfun_record_results
format(x, to = c("text", "html"), encode = FALSE, template = FALSE, ...)
# S3 method for xfun_record_results
print(
  x,
  browse = interactive(),
  to = if (browse) "html" else "text",
  template = TRUE,
  ...
)

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.

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 (by default, a temporary path under the current working directory). 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.

error

Whether to record errors. If TRUE, errors will not stop the execution and error messages will be recorded. If FALSE, errors will be thrown normally.

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.

Examples

code = c("# a message 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))