rlang (version 0.1)

rst_muffle: Jump to a muffling restart

Description

Muffle restarts are established at the same location as where a condition is signalled. They are useful for two non-exclusive purposes: muffling signalling functions and muffling conditions. In the first case, rst_muffle() prevents any further side effects of a signalling function (a warning or message from being displayed, an aborting jump to top level, etc). In the second case, the muffling jump prevents a condition from being passed on to other handlers. In both cases, execution resumes normally from the point where the condition was signalled.

Usage

rst_muffle(c)

Arguments

c

A condition to muffle.

See Also

The muffle argument of inplace(), and the mufflable argument of cnd_signal().

Examples

# NOT RUN {
side_effect <- function() cat("side effect!\n")
handler <- inplace(function(c) side_effect())

# A muffling handler is an inplace handler that jumps to a muffle
# restart:
muffling_handler <- inplace(function(c) {
  side_effect()
  rst_muffle(c)
})

# You can also create a muffling handler simply by setting
# muffle = TRUE:
muffling_handler <- inplace(function(c) side_effect(), muffle = TRUE)

# You can then muffle the signalling function:
fn <- function(signal, msg) {
  signal(msg)
  "normal return value"
}
with_handlers(fn(message, "some message"), message = handler)
with_handlers(fn(message, "some message"), message = muffling_handler)
with_handlers(fn(warning, "some warning"), warning = muffling_handler)

# Note that exiting handlers are thrown to the establishing point
# before being executed. At that point, the restart (established
# within the signalling function) does not exist anymore:
# }
# NOT RUN {
with_handlers(fn(warning, "some warning"),
  warning = exiting(function(c) rst_muffle(c)))
# }
# NOT RUN {

# Another use case for muffle restarts is to muffle conditions
# themselves. That is, to prevent other condition handlers from
# being called:
undesirable_handler <- inplace(function(c) cat("please don't call me\n"))

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

# See the `mufflable` argument of cnd_signal() for more on this point
# }