cnd_muffle: Muffle a condition

In rlang: Functions for Base Types and Core R and 'Tidyverse' Features

Muffle a condition

Description

Unlike exiting() handlers, calling() handlers must be explicit that they have handled a condition to stop it from propagating to other handlers. Use cnd_muffle() within a calling handler (or as a calling handler, see examples) to prevent any other handlers from being called for that condition.

Usage

cnd_muffle(cnd)

Arguments

cnd	A condition to muffle.

Value

If cnd is mufflable, cnd_muffle() jumps to the muffle restart and doesn't return. Otherwise, it returns FALSE.

Mufflable conditions

Most conditions signalled by base R are muffable, although the name of the restart varies. cnd_muffle() will automatically call the correct restart for you. It is compatible with the following conditions:

• warning and message conditions. In this case cnd_muffle() is equivalent to base::suppressMessages() and base::suppressWarnings().

• Bare conditions signalled with signal() or cnd_signal(). Note that conditions signalled with base::signalCondition() are not mufflable.

• Interrupts are sometimes signalled with a resume restart on recent R versions. When this is the case, you can muffle the interrupt with cnd_muffle(). Check if a restart is available with base::findRestart("resume").

If you call cnd_muffle() with a condition that is not mufflable you will cause a new error to be signalled.

• Errors are not mufflable since they are signalled in critical situations where execution cannot continue safely.

• Conditions captured with base::tryCatch(), with_handlers() or catch_cnd() are no longer mufflable. Muffling restarts must be called from a calling handler.

Examples

fn <- function() {
  inform("Beware!", "my_particular_msg")
  inform("On your guard!")
  "foobar"
}

# Let's install a muffling handler for the condition thrown by `fn()`.
# This will suppress all `my_particular_wng` warnings but let other
# types of warnings go through:
with_handlers(fn(),
  my_particular_msg = calling(function(cnd) {
    inform("Dealt with this particular message")
    cnd_muffle(cnd)
  })
)

# Note how execution of `fn()` continued normally after dealing
# with that particular message.

# cnd_muffle() can also be passed to with_handlers() as a calling
# handler:
with_handlers(fn(),
  my_particular_msg = calling(cnd_muffle)
)

rlang documentation built on June 22, 2024, 9:31 a.m.