R: Create a restarting handler

restarting {rlang} | R Documentation

## 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 support tidy dots features.
`.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

    # 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"))

[Package rlang version 0.2.2 Index]