rlang (version 0.2.2)

exiting: Create an exiting or in place handler

Description

There are two types of condition handlers: exiting handlers, which are thrown to the place where they have been established (e.g., with_handlers()'s evaluation frame), and local handlers, which are executed in place (e.g., where the condition has been signalled). exiting() and inplace() create handlers suitable for with_handlers().

Usage

exiting(handler)
inplace(handler, muffle = FALSE)

Arguments

handler

A handler function that takes a condition as argument. This is passed to as_function() and can thus be a formula describing a lambda function.

muffle

Whether to muffle the condition after executing an inplace handler. The signalling function must have established a muffling restart. Otherwise, an error will be issued.

Details

A subtle point in the R language is that conditions are not thrown, handlers are. base::tryCatch() and with_handlers() actually catch handlers rather than conditions. When a critical condition signalled with base::stop() or abort(), R inspects the handler stack and looks for a handler that can deal with the condition. If it finds an exiting handler, it throws it to the function that established it (with_handlers()). That is, it interrupts the normal course of evaluation and jumps to with_handlers() evaluation frame (see ctxt_stack()), and only then and there the handler is called. On the other hand, if R finds an inplace handler, it executes it locally. The inplace handler can choose to handle the condition by jumping out of the frame (see rst_jump() or return_from()). If it returns locally, it declines to handle the condition which is passed to the next relevant handler on the stack. If no handler is found or is able to deal with the critical condition (by jumping out of the frame), R will then jump out of the faulty evaluation frame to top-level, via the abort restart (see rst_abort()).

See Also

with_handlers() for examples, restarting() for another kind of inplace handler.

Examples

# NOT RUN {
# You can supply a function taking a condition as argument:
hnd <- exiting(function(c) cat("handled foo\n"))
with_handlers(cnd_signal("foo"), foo = hnd)

# Or a lambda-formula where "." is bound to the condition:
with_handlers(foo = inplace(~cat("hello", .$attr, "\n")), {
  cnd_signal("foo", attr = "there")
  "foo"
})
# }