These functions are specialized versions of the reapi condition functions that are intended for
use in the package's internal checking functions. They create conditions with
specific classes that can be used to identify and handle errors, warnings, and messages.
Usage
reapi_abort_check(
msg,
...,
parent = NULL,
call = rlang::caller_env(),
.envir = parent.frame()
)
reapi_warn_check(msg, ..., call = rlang::caller_env(), .envir = parent.frame())
reapi_inform_check(
msg,
...,
call = rlang::caller_env(),
.envir = parent.frame()
)
check_abort(
msg,
...,
parent = NULL,
call = rlang::caller_env(),
.envir = parent.frame()
)
check_warn(msg, ..., call = rlang::caller_env(), .envir = parent.frame())
check_inform(msg, ..., call = rlang::caller_env(), .envir = parent.frame())Arguments
- msg
Character string or vector containing the message to be displayed. This gets passed to
cli::cli_bullets()allowing forcli's custom formatting,glueinterpolation, inline markup syntax, and other features.- ...
Passed to
rlang::abort(),rlang::warn()orrlang::inform().- parent
Supply
parentwhen you rethrow an error from a condition handler (e.g. withtry_fetch()).If
parentis a condition object, a chained error is created, which is useful when you want to enhance an error with more details, while still retaining the original information.If
parentisNA, it indicates an unchained rethrow, which is useful when you want to take ownership over an error and rethrow it with a custom message that better fits the surrounding context.Technically, supplying
NAletsabort()know it is called from a condition handler. This helps it create simpler backtraces where the condition handling context is hidden by default.
For more information about error calls, see Including contextual information with error chains.
- call
The execution environment of a currently running function, e.g.
call = caller_env(). The corresponding function call is retrieved and mentioned in error messages as the source of the error.You only need to supply
callwhen throwing a condition from a helper function which wouldn't be relevant to mention in the message.Can also be
NULLor a defused function call to respectively not display any call or hard-code a code to display.For more information about error calls, see Including function calls in error messages.
- .envir
Environment to evaluate the glue expressions in.
Value
These functions do not return values, but are used for their side effects, namely
creating and signaling conditions. The reapi_abort() function will stop
execution, while reapi_warn() & reapi_inform() will allow execution
to proceed.
Details
The condition class hierarchy is structured like so:
where <reapi_condition> is the base class for all reapi conditions
and sits on top of the existing rlang and base R condition classes.
For example, a reapi error thrown without any additional custom class added
to it using reapi_abort() will have the following classes:
[1] "reapi_error" "reapi_condition" "rlang_error" "error" "condition"
This allows for filtering and handling of reapi-specific conditions while still being compatible with the broader R condition system.
Functions
reapi_abort_check(): creates anreapi_errorcondition for checks.reapi_warn_check(): creates anreapi_warningcondition for checks.reapi_inform_check(): creates anreapi_messagecondition for checks.
Aliases
check_abort(): alias forreapi_abort_check()check_warn(): alias forreapi_warn_check()check_inform(): alias forreapi_inform_check()
See also
Utility Functions:
active_config,
utils_pkg
Conditions:
reapi-conditions
Examples
if (FALSE) { # \dontrun{
reapi_abort("This is a reapi error.")
# catch a condition and check its classes
err <- rlang::catch_cnd(reapi_abort("Error Message"))
class(err)
# catch a warning and check its classes
wrn <- rlang::catch_cnd(reapi_warn("Warning Message"))
class(wrn)
# catch a message and check its classes
msg <- rlang::catch_cnd(reapi_inform("Message"))
class(msg)
} # }
