Capturing evaluation information with evals

Roman Tsegelskyi, Gergely Daróczi

2021-06-11

evals is aimed at collecting as much information as possible while evaluating R code. It can evaluate a character vector of R expressions, and it returns a list of information captured while running them:

• src holds the R expression,
• result contains the raw R object as-is,
• output represents how the R object is printed to the standard output,
• type is the class of the returned R object,
• msg is a list of messages captured while evaluating the R expression. Among other messages, warnings/errors will appear here.
• stdout contains what, if anything, was written to the standard output.

Besides capturing evaluation information, evals is able to automatically identify whether an R expression is returning anything to a graphical device, and can save the resulting image in a variety of file formats.

Another interesting evals feature is caching the results of evaluated expressions. Read the caching section for more details.

evals has a large number of options, which allow users to customize the call exactly as needed. Here we will focus on the most useful features, but the full list of options, with explanations, can be viewed by calling ?evalsOptions. Also evals support permanent options that will persist for all calls to evals, this can be achieved by calling evalsOptions.

Let’s start with a basic example by evaluating 1:10 and collecting all information about it:

evals('1:10')
#> [[1]]
#> $src
#> [1] "1:10"
#> 
#> $result
#>  [1]  1  2  3  4  5  6  7  8  9 10
#> 
#> $output
#> [1] " [1]  1  2  3  4  5  6  7  8  9 10"
#> 
#> $type
#> [1] "integer"
#> 
#> $msg
#> $msg$messages
#> NULL
#> 
#> $msg$warnings
#> NULL
#> 
#> $msg$errors
#> NULL
#> 
#> 
#> $stdout
#> NULL
#> 
#> attr(,"class")
#> [1] "evals"

Not all the information might be useful, so evals makes it is possible to capture only some of the information, by specifying the output parameter:

evals('1:10', output = c('result', 'output'))
#> [[1]]
#> $result
#>  [1]  1  2  3  4  5  6  7  8  9 10
#> 
#> $output
#> [1] " [1]  1  2  3  4  5  6  7  8  9 10"
#> 
#> attr(,"class")
#> [1] "evals"

One of the neat features of evals that it catches errors/warnings without interrupting the evaluation and saves them.

evals('x')[[1]]$msg
#> $messages
#> NULL
#> 
#> $warnings
#> NULL
#> 
#> $errors
#> [1] "object 'x' not found"
evals('as.numeric("1.1a")')[[1]]$msg
#> $messages
#> NULL
#> 
#> $warnings
#> [1] "NAs introduced by coercion"
#> 
#> $errors