catchr (version 0.2.31)

make_plans: Making catchr plans

Description

Customizing how conditions are handled in catchr is done by giving catchr 'plans' for when it encounters particular conditions. These plans are essentially just lists of functions that are called in order, and that take in the particular condition as an argument.

However, since catchr evaluates things slightly differently than base R, the user input to make these plans has to first be passed into make_plans (or, for setting the default plan, set_default_plan()). make_plans also lets users specify options for how they want these plans to be evaluated with the .opts argument (see catchr_opts() for more details).

See the 'Input' section below and the examples for how to use make_plans.

Usage

make_plans(..., .opts = catchr_opts())

Arguments

…

Named and unnamed arguments for making plans. See 'Input' for more detail.

.opts

The options to be used for the plan. Generally passed in using catchr_opts().

Input

User input to make_plans is very similar to how one makes handlers for base::withCallingHandlers(), base::tryCatch() and rlang's rlang::with_handlers(), albeit with some important differences.

Like the functions above, the name of each argument determines which type of condition it will be the plan for. Hence, warnings = fn will apply the fn function to the warnings raised in evaluating expr.

However, unnamed arguments are also accepted: the value of any unnamed arguments will be treated as the type of a condition, which will then have the default plan assigned to it, as specified either in .opts = catchr_opts(...) or via getOption("catchr.default_plan"). Unnamed arguments must be either strings or unquoted expressions which will then be converted to strings. Currently, unnamed arguments are never evaluated, so cannot be calls that evaluate to strings.

However, this may change in future versions of catchr.

Passing input in programmatically

make_plans supports quasiquotation, so if for some reason one wishes to pass input into make_plans via a different function, programmatically, etc., one may do so by splicing in quosures. See below for examples.

Examples

# NOT RUN {
# ### INPUT EXAMPLES ###########################

# Named arguments --------------------------------------

#   * single functions:
p <- make_plans(warning = str, message = function(x) print(x))

#   * single unquoted expressions and strings
#     (must match catchr's special reserved terms, e.g., 'muffle', 'exit', etc.):
p <- make_plans(message = muffle, condition = "collect")

#   * lists or vectors of any combinatin of the above:
p <- make_plans(error = list(collect, "exit"),
                message = c(cat, "muffle"))

#   * anything that evaluates to the above:
fn <- function() { list(cat, "muffle") }
p <- make_plans(message = fn() )

# Unnamed arguments ----------------------

#   * single strings:
p <- make_plans("warning","condition")

#   * unquoted expressions:
p <- make_plans(warning,condition)

#   * Currently, does NOT accept anything that evaluates to strings:
#       (However, this may change in the future)
# }
# NOT RUN {
string_fn <- function() { "condition" }
make_plans(string_fn()) # will currently raise error
# }
# NOT RUN {
# Mixes of both --------------------------
p <- make_plans("warning", message = c(towarning, muffle),
                condition = print)

# ### Quasiquotation and splicing in the arguments ###############

q <- rlang::quo(function(cond) {print(cond)})
name <- "warning"

print_plan <- make_plans(!!name := !!q)

# 'message' will be assigned the default plan
qs <- rlang::quos(warning = muffle, error = exit, message)
random_plan <- make_plans(!!!qs)

# }