catchr (version 0.2.31)

user_exit: Force an exit

Description

These functions force a catchr plan to immediately exit the evaluation of an expression (and the rest of the plan), similar to how exit works. But unlike exit and most catchr functions or special reserved terms, these functions are meant to be used in the user-defined functions of a plan.

user_exit() forces the code to exit, and after exiting, evaluate whatever expression was supplied. This function should be used within a custom function, i.e., function(x) {user_exit(print("DONE!"))}.

exit_with() can be used at the "top" level of a plan, since it returns a function that calls user_exit(). Thus exit_with(print("DONE!")) is equivalent to the example above. Additionally, if as_fn is set to TRUE, it will attempt to coerce expr into a function via rlang's rlang::as_function(). If expr can be converted, exit_with() will return a function that takes in a condition, modifies it via expr, and then supplies this to user_exit. E.g., exit_with(~.$message) is equivalent to function(cond) {user_exit(cond$message)}

Usage

user_exit(expr = NULL)
exit_with(expr, as_fn = FALSE)

Arguments

expr

An optional expression which if specified, will be evaluated after user_exit exits the evaluation.

as_fn

A logical; if TRUE, catchr will try to convert expr into a function via rlang::as_function() which will be applied to the condition. It will fall back to normal behavior if this coercion raises an error.

See Also

the exit special term, which essentially becomes exit_with(NULL); user_display() and display_with() for parallel functions for the display special term, and beep_with() for a parallel function for the beep special term..

Examples

# NOT RUN {
yay <- catch_expr({warning("oops"); "done!"},
                  warning = exit_with("YAY"))

# This won't work, since `user_exit("YAY")` doesn't evaluate to a function/string
# }
# NOT RUN {
yay <- catch_expr({warning("oops"); "done!"},
                  warning = user_exit("YAY"))
# }
# NOT RUN {
check <- function(cond) {
  if (inherits(cond, "simpleWarning"))
    user_exit(rlang::warn(paste0("Check it: ", cond$message)))
  else
    invokeRestart(first_muffle_restart(cond))
  NULL
}

result <- catch_expr(
  { rlang::warn("This will be muffled")
    warning("This won't be muffled") },
  warning = check)
# Notice that `result` takes whatever the last (invisibly)
#   returned value is. Here, that's the message from the warning
result

# If you don't want to accidentally assign what is returned by `user_exit`,
#   either add `NULL` to the end of the expresion:
result2 <- catch_expr(
  { rlang::warn("This will be muffled")
    warning("This won't be muffled")},
  warning = function(x) { user_exit({ warning("This won't be assigned"); NULL})})
result2

# Or you can just do the assignment _within_ the expression being evaluated:
result3 <- NULL
catch_expr({result3 <- {
    rlang::warn("This will be muffled")
    warning("This won't be muffled")}},
  warning = check)
result3
# }