Evaluate expressions in a REPL-like fashion

Rserve.eval evaluates a given expression in a way that is very close to the behavior on the console Read/Evaluate/Print Loop (REPL). Among other things this means printing the result of each expression if visible. The function is guaranteed to not raise an error and in case of an error it returns an object of class Rserve-eval-error with details including the error and the stack trace.

Rserve.eval(what, where = .GlobalEnv, last.value = FALSE, exp.value = FALSE,
            context = NULL, handlers = list(error=.save.condition))

Arguments

what: expressions to evaluate
where: environment to evaluate in
last.value: logical, if TRUE then the result of the evaluation is returned, otherwise the evaluation is only performed for its side-efects and returns TRUE instead.
exp.value: logical, it TRUE then an error object will include the actual expression that triggered the error, otherwise it will only store the index of the expression in what.
context: optional object that will be used as the Rserve context for the duration of the evaluation (see Rserve.context).
handlers: optional named list of calling handlers to register for the duration of the evaluation. The default is to register an error handlers which stores the error condition so it can be reported in the result - see below.

Details

If what contains one or more expressions, they are evaluated one by one while printing the result of each if visible. Upon error subsequent expressions are not evaluated. If what is not an expression then the only a single evaluation of what is performed and the result is not printed.

The main purpose of this function is to implement console front-ends where the front-end uses parse() + Rserve.eval() to simulate the action of a GUI. Because the function returns in all circumstances it allows clients to rely on a well-define messaging behavior.

Value

If the evaluation triggered an error, the result is an object of class

Rserve-eval-error with components:

error: character, error message
traceback: list of contexts in the traceback
expression: if what contains multiple expressions then this will be either an index to the expression that caused the error (exp.value=FALSE) or the actual expression (otherwise).
context: current Rserve context, NULL if none has been set
condition: if any condition has been saved via .save.condition (which is the default) then on error the captured condition object is stored here, NULL otherwise

If the evaluation finished without an error then the result is either

TRUE if last.value=FALSE or the value of the last expression otherwise.

Note

Rserve versions up to 1.8-10 did not include the condition component, no calling handlers were registered and there was no condition component in the result. To replicate that behavior or if you don't need that information, you can set handlers=NULL which removes the overhead of adding calling handlers.

No error checking is performed on the handlers parameter, so make sure it is avalid, named list of functions, otherwise an error will occur at evaluation time.

Author

Simon Urbanek

Examples

  g <- function() stop("foo")
  f <- function() g()
  (Rserve.eval(expression(f())))
#> $error
#> [1] "Error: could not find function \"f\"\n"
#> 
#> $traceback
#> NULL
#> 
#> $expression
#> [1] 1
#> 
#> $context
#> NULL
#> 
#> $condition
#> <simpleError: could not find function "f">
#> 
#> attr(,"class")
#> [1] "Rserve-eval-error"
  (Rserve.eval(parse(text="1:5\n1+1")))
#> [1] 1 2 3 4 5
#> [1] 2
#> [1] TRUE
  (Rserve.eval(quote(1+1), last.value=TRUE))
#> [1] 2

  error_with_condition = function(object = NULL) {
    cond = errorCondition("this is a custom error with condition",
                          object = object, 
                          class = "CustomError")
    stop(cond)
  }
  str(Rserve.eval(quote(error_with_condition("hello")), last.value = TRUE))
#> Class 'Rserve-eval-error'  hidden list of 5
#>  $ error     : chr "Error: could not find function \"error_with_condition\"\n"
#>  $ traceback : NULL
#>  $ expression: int NA
#>  $ context   : NULL
#>  $ condition :List of 2
#>   ..$ message: chr "could not find function \"error_with_condition\""
#>   ..$ call   : NULL
#>   ..- attr(*, "class")= chr [1:3] "simpleError" "error" "condition"