Run R code and record the results

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(),
  dev.keep = TRUE,
  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", "markdown", "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.
dev.keep: Indices of plots to be kept. The indices can be either numeric (positive or negative integers) or logical. Negative integers and false values will remove the corresponding plots. For example, if the code generated 3 plots, dev.keep = c(1, 3), -2, and c(T, F, T) are equivalent ways to remove the second plot. The special value dev.keep = 'last' means to keep the last plot only.
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(). If a non-function value (e.g., NA) is passed to this argument, print() (or show() for S4 objects) will be used.
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, markdown, 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)
#> List of 13
#>  |-: 'record_source' chr [1:2] "# a warning test" "1:2 + 1:3"
#>  |  - attr(*, "lines")= int [1:2] 1 2
#>  |-: 'record_warning' chr "longer object length is not a multiple of shorter object length"
#>  |-: 'record_output' chr "[1] 2 4 4"
#>  |-: 'record_source' chr [1:2] "par(mar = c(4, 4, 1, .2))" "barplot(5:1, col = 2:6, horiz = TRUE)"
#>  |  - attr(*, "lines")= int [1:2] 3 3
#>  |-: 'record_plot' chr "xfun-record-1.png"
#>  |-: 'record_source' chr "head(iris)"
#>  |  - attr(*, "lines")= int [1:2] 5 5
#>  |-: 'record_output' chr [1:7] "  Sepal.Length Sepal.Width Petal.Length Petal.Width Species" "1          5.1         3.5          1.4         0.2  setosa" "2          4.9         3.0          1.4         0.2  setosa" "3          4.7         3.2          1.3         0.2  setosa" ...
#>  |-: 'record_source' chr "sunflowerplot(iris[, 3:4], seg.col = 'purple')"
#>  |  - attr(*, "lines")= int [1:2] 6 6
#>  |-: 'record_plot' chr "xfun-record-2.png"
#>  |-: 'record_source' chr [1:3] "if (TRUE) {" "  message('Hello, xfun::record()!')" "}"
#>  |  - attr(*, "lines")= int [1:2] 7 9
#>  |-: 'record_message' chr "Hello, xfun::record()!\n"
#>  |-: 'record_source' chr [1:2] "# throw an error" "1 + 'a'"
#>  |  - attr(*, "lines")= int [1:2] 10 11
#>  |-: 'record_error' chr "Error in 1 + \"a\": non-numeric argument to binary operator"
#>  - attr(*, "class")= chr "xfun_record_results"
format(res)
#> # a warning test
#> 1:2 + 1:3
#> 
#> #> longer object length is not a multiple of shorter object length
#> 
#> #> [1] 2 4 4
#> 
#> par(mar = c(4, 4, 1, .2))
#> barplot(5:1, col = 2:6, horiz = TRUE)
#> 
#> #> xfun-record-1.png
#> 
#> head(iris)
#> 
#> #>   Sepal.Length Sepal.Width Petal.Length Petal.Width Species
#> #> 1          5.1         3.5          1.4         0.2  setosa
#> #> 2          4.9         3.0          1.4         0.2  setosa
#> #> 3          4.7         3.2          1.3         0.2  setosa
#> #> 4          4.6         3.1          1.5         0.2  setosa
#> #> 5          5.0         3.6          1.4         0.2  setosa
#> #> 6          5.4         3.9          1.7         0.4  setosa
#> 
#> sunflowerplot(iris[, 3:4], seg.col = 'purple')
#> 
#> #> xfun-record-2.png
#> 
#> if (TRUE) {
#>   message('Hello, xfun::record()!')
#> }
#> 
#> #> Hello, xfun::record()!
#> 
#> # throw an error
#> 1 + 'a'
#> 
#> #> Error in 1 + "a": non-numeric argument to binary operator
#> 
# find and clean up plot files
plots = Filter(function(x) inherits(x, "record_plot"),
    res)
file.remove(unlist(plots))
#> [1] TRUE TRUE