Evaluate input and return all details of evaluation

Compare to eval(), evaluate captures all of the information necessary to recreate the output as if you had copied and pasted the code into a R terminal. It captures messages, warnings, errors and output, all correctly interleaved in the order in which they occured. It stores the final result, whether or not it should be visible, and the contents of the current graphics device.

Usage

evaluate(
  input,
  envir = parent.frame(),
  enclos = NULL,
  debug = FALSE,
  stop_on_error = 0L,
  keep_warning = TRUE,
  keep_message = TRUE,
  log_echo = FALSE,
  log_warning = FALSE,
  new_device = TRUE,
  output_handler = NULL,
  filename = NULL,
  include_timing = FALSE
)

Arguments

input

input object to be parsed and evaluated. May be a string, file connection or function. Passed on to parse_all().

envir

environment in which to evaluate expressions.

enclos

when envir is a list or data frame, this is treated as the parent environment to envir.

debug

if TRUE, displays information useful for debugging, including all output that evaluate captures.

stop_on_error

A number between 0 and 2 that controls what happens when the code errors:

• If 0, the default, will continue running all code, just as if you'd pasted the code into the command line.

• If 1, evaluation will stop on first error without signaling the error, and you will get back all results up to that point.

• If 2, evaluation will halt on first error and you will get back no results.

keep_warning, keep_message

A single logical value that controls what happens to warnings and messages.

• If TRUE, the default, warnings and messages will be captured in the output.

• If NA, warnings and messages will not be captured and bubble up to the calling environment of evaluate().

• If FALSE, warnings and messages will be completed supressed and not shown anywhere.

Note that setting the envvar R_EVALUATE_BYPASS_MESSAGES to true will force these arguments to be set to NA.

log_echo, log_warning

If TRUE, will immediately log code and warnings (respectively) to stderr.

This will be force to TRUE if env var ACTIONS_STEP_DEBUG is true, as when debugging a failing GitHub Actions workflow.

new_device

if TRUE, will open a new graphics device and automatically close it after completion. This prevents evaluation from interfering with your existing graphics environment.

output_handler

an instance of output_handler() that processes the output from the evaluation. The default simply prints the visible return values.

filename

string overrriding the base::srcfile() filename.

include_timing

Deprecated.

Examples

evaluate(c(
  "1 + 1",
  "2 + 2"
))
#> <evaluation>
#> Source code: 
#>   1 + 1
#> Text output: 
#>   [1] 2
#> Source code: 
#>   2 + 2
#> Text output: 
#>   [1] 4

# Not that's there's a difference in output between putting multiple
# expressions on one line vs spreading them across multiple lines
evaluate("1;2;3")
#> <evaluation>
#> Source code: 
#>   1;2;3
#> Text output: 
#>   [1] 1
#> Text output: 
#>   [1] 2
#> Text output: 
#>   [1] 3
evaluate(c("1", "2", "3"))
#> <evaluation>
#> Source code: 
#>   1
#> Text output: 
#>   [1] 1
#> Source code: 
#>   2
#> Text output: 
#>   [1] 2
#> Source code: 
#>   3
#> Text output: 
#>   [1] 3

# This also affects how errors propagate, matching the behaviour
# of the R console
evaluate("1;stop(2);3")
#> <evaluation>
#> Source code: 
#>   1;stop(2);3
#> Text output: 
#>   [1] 1
#> Condition: 
#>   Error:
#>   2
evaluate(c("1", "stop(2)", "3"))
#> <evaluation>
#> Source code: 
#>   1
#> Text output: 
#>   [1] 1
#> Source code: 
#>   stop(2)
#> Condition: 
#>   Error:
#>   2
#> Source code: 
#>   3
#> Text output: 
#>   [1] 3