R: Signal a condition

cnd_signal {rlang} | R Documentation

## Signal a condition

### Description

Signal a condition to handlers that have been established on the stack. Conditions signalled with `cnd_signal()` are assumed to be benign. Control flow can resume normally once the condition has been signalled (if no handler jumped somewhere else on the evaluation stack). On the other hand, `cnd_abort()` treats the condition as critical and will jump out of the distressed call frame (see `rst_abort()`), unless a handler can deal with the condition.

### Usage

    cnd_signal(cnd, .cnd, .mufflable)

### Arguments

`cnd` | A condition object (see `cnd()`).
`.cnd, .mufflable` | These arguments are retired. `.cnd` has been renamed to `cnd` and `.mufflable` no longer has any effect as non-critical conditions are always signalled with a muffling restart.

### Details

If `.critical` is `FALSE`, this function has no side effects beyond calling handlers. In particular, execution will continue normally after signalling the condition (unless a handler jumped somewhere else via `rst_jump()` or by being `exiting()`). If `.critical` is `TRUE`, the condition is signalled via `base::stop()` and the program will terminate if no handler dealt with the condition by jumping out of the distressed call frame.

`calling()` handlers are called in turn when they decline to handle the condition by returning normally. However, it is sometimes useful for a calling handler to produce a side effect (signalling another condition, displaying a message, logging something, etc), prevent the condition from being passed to other handlers, and resume execution from the place where the condition was signalled. The easiest way to accomplish this is by jumping to a restart point (see `with_restarts()`) established by the signalling function. `cnd_signal()` always installs a muffle restart (see `cnd_muffle()`).

### Lifecycle

- Modifying a condition object with `cnd_signal()` is defunct. Consequently the `.msg` and `.call` arguments are retired and defunct as of rlang 0.3.0. In addition `.cnd` is renamed to `cnd` and soft-deprecated.

- The `.mufflable` argument is soft-deprecated and no longer has any effect. Non-critical conditions are always signalled with a muffle restart.

- Creating a condition object with `cnd_signal()` is soft-deprecated. Please use `signal()` instead.

### See Also

`abort()`, `warn()` and `inform()` for signalling typical R conditions. See `with_handlers()` for establishing condition handlers.

### Examples

    # Creating a condition of type "foo"
    cnd <- cnd("foo")

    # If no handler capable of dealing with "foo" is established on the
    # stack, signalling the condition has no effect:
    cnd_signal(cnd)

    # To learn more about establishing condition handlers, see
    # documentation for with_handlers(), exiting() and calling():
    with_handlers(cnd_signal(cnd),
      foo = calling(function(c) cat("side effect!\n"))
    )

    # By default, cnd_signal() creates a muffling restart which allows
    # calling handlers to prevent a condition from being passed on to
    # other handlers and to resume execution:
    undesirable_handler <- calling(function(c) cat("please don't call me\n"))
    muffling_handler <- calling(function(c) {
      cat("muffling foo...\n")
      cnd_muffle(c)
    })

    with_handlers(foo = undesirable_handler,
      with_handlers(foo = muffling_handler, {
        cnd_signal(cnd("foo"))
        "return value"
      }))

[Package rlang version 0.3.2 Index]