rlang (version 0.1)

restarting: Create a restarting handler

Description

This constructor automates the common task of creating an inplace() handler that invokes a restart.

Usage

restarting(.restart, ..., .fields = NULL)

Arguments

.restart

The name of a restart.

...

Additional arguments passed on the restart function. These arguments are evaluated only once and immediately, when creating the restarting handler. Furthermore, they are evaluated with explicit splicing.

.fields

A character vector specifying the fields of the condition that should be passed as arguments to the restart. If named, the names (except empty names "") are used as argument names for calling the restart function. Otherwise the the fields themselves are used as argument names.

Details

Jumping to a restart point from an inplace handler has two effects. First, the control flow jumps to wherever the restart was established, and the restart function is called (with ..., or .fields as arguments). Execution resumes from the with_restarts() call. Secondly, the transfer of the control flow out of the function that signalled the condition means that the handler has dealt with the condition. Thus the condition will not be passed on to other potential handlers established on the stack.

See Also

inplace() and exiting().

Examples

# NOT RUN {
# This is a restart that takes a data frame and names as arguments
rst_bar <- function(df, nms) {
  stats::setNames(df, nms)
}

# This restart is simpler and does not take arguments
rst_baz <- function() "baz"

# Signalling a condition parameterised with a data frame
fn <- function() {
  with_restarts(cnd_signal("foo", foo_field = mtcars),
    rst_bar = rst_bar,
    rst_baz = rst_baz
  )
}

# Creating a restarting handler that passes arguments `nms` and
# `df`, the latter taken from a data field of the condition object
restart_bar <- restarting("rst_bar",
  nms = LETTERS[1:11], .fields = c(df = "foo_field")
)

# The restarting handlers jumps to `rst_bar` when `foo` is signalled:
with_handlers(fn(), foo = restart_bar)

# The restarting() constructor is especially nice to use with
# restarts that do not need arguments:
with_handlers(fn(), foo = restarting("rst_baz"))
# }