Augment Abort & co.; add rlang condition tutorial, helpers

.Rbuildignore

@@ -1,3 +1,4 @@
 ^.*\.Rproj$
 ^\.Rproj\.user$
 ^LICENSE\.md$
+^man-roxygen$

NAMESPACE

@@ -31,7 +31,15 @@ export(epi_slide)
 export(epix_as_of)
 export(epix_merge)
 export(epix_slide)
+export(global_handlers_list)
+export(global_handlers_push)
+export(global_handlers_remove)
 export(growth_rate)
+export(handle_via_dump_frames)
+export(handle_via_entrace)
+export(handle_via_muffle_message)
+export(handle_via_muffle_warning)
+export(handle_via_recover)
 export(is_epi_archive)
 export(is_epi_df)
 export(quiet)
@@ -53,18 +61,42 @@ importFrom(dplyr,ungroup)
 importFrom(lubridate,days)
 importFrom(lubridate,weeks)
 importFrom(magrittr,"%>%")
+importFrom(purrr,map2_lgl)
+importFrom(purrr,map_chr)
+importFrom(purrr,map_dbl)
+importFrom(purrr,map_lgl)
 importFrom(rlang,"!!!")
 importFrom(rlang,"!!")
 importFrom(rlang,.data)
 importFrom(rlang,.env)
+importFrom(rlang,abort)
+importFrom(rlang,arg_match)
+importFrom(rlang,base_env)
+importFrom(rlang,caller_env)
+importFrom(rlang,chr)
+importFrom(rlang,dbl)
+importFrom(rlang,empty_env)
 importFrom(rlang,enquo)
 importFrom(rlang,enquos)
+importFrom(rlang,env_label)
+importFrom(rlang,fn_env)
+importFrom(rlang,global_env)
+importFrom(rlang,inform)
+importFrom(rlang,inject)
+importFrom(rlang,is_function)
 importFrom(rlang,is_quosure)
+importFrom(rlang,is_reference)
+importFrom(rlang,names2)
 importFrom(rlang,sym)
 importFrom(rlang,syms)
+importFrom(rlang,warn)
 importFrom(stats,cor)
 importFrom(stats,median)
+importFrom(stats,setNames)
+importFrom(tibble,lst)
 importFrom(tidyr,unnest)
 importFrom(tidyselect,eval_select)
 importFrom(tidyselect,starts_with)
 importFrom(tsibble,as_tsibble)
+importFrom(utils,capture.output)
+importFrom(utils,str)

R/utils.R

@@ -1,11 +1,3 @@
-break_str = function(str, nchar = 79, init = "") {
-  str = paste(strwrap(str, nchar, init = init), collapse = "\n")
-  str[1] = substring(str, nchar(init)+1)
-  return(str)
-}
-
-Abort = function(msg, ...) rlang::abort(break_str(msg, init = "Error: "), ...)
-Warn = function(msg, ...) rlang::warn(break_str(msg, init = "Warning: "), ...)
 
 ##########
 

man-roxygen/Condition.R

@@ -0,0 +1,17 @@
+#' @param message character vector; an `rlang` non-`cli`-format message; this
+#'   will be line-wrapped and augmented with information about
+#'   `display_subfields` and how to access any `more_subfields`
+#' @param class_suffix string or NULL; if non-NULL, and we are in a package,
+#'   then `"<pkgname>__<class_suffix>"` will be tacked on as an S3 class of the
+#'   condition object; if we are not in a package, then the suffix (without any
+#'   prefix) will be added as an S3 class. Additionally, regardless of whether
+#'   `class_suffix` is `NULL`, if we are in a package, two additional S3 classes
+#'   will be added as well: `"<pkgname>__<conditiontype>"` and
+#'   `"<pkgname>__condition"`
+#' @param display_subfields list of objects to display as part of the condition
+#'   message using [`utils::str`] and save in the condition object
+#' @param more_subfields list of objects to save in the condition object but
+#'   only point to, not display, in the condition message
+#' @param call environment; the calling environment from which the trace should
+#'   be produced
+NULL

man-roxygen/handler_dots.R

@@ -0,0 +1,6 @@
+#' @param ... named calling handlers: each a function that takes a condition
+#'   object as an argument and performs some handling (such as printing or
+#'   recording a stack trace), passed by name, where the name associates the
+#'   handler with a class of conditions it should be called on (e.g.,
+#'   `"condition"` as a catch-all, `"error"`, `"warning"`, `"message"`, or more
+#'   specific classes provided by some packages)

man-roxygen/handler_fn.R

@@ -0,0 +1,32 @@
+# See notes on the use of `r ...` dynamic R code in roxygen2 comments
+# `utils_conditions.R`. We have to use a bit different code to get this to work
+# inside this template tag file, leading to long `r ...` chunks; don't
+# wrap/fill/format these, or else current roxygen2 at time of writing will not
+# properly process them. Keep the blank lines around them to help prevent
+# accidental auto-formatting.
+
+#' @description
+#'
+#' This is a very simple function, but simply repeating its definition
+#' everywhere of interest prevents
+
+#' `r paste0(if(getRversion()>="4")"["else"","\x60base::globalCallingHandlers\x60",if(getRversion()>="4")"]"else"")`
+
+#' and straightforward handler-related functions from recognizing these repeated
+#' redefinitions as the same things (due to differing bytecode, srcrefs, closure
+#' environments, and/or other things). This function provides a consistent
+#' identity for this type of handler, and attempts to maintain this identity
+#' even across package reloads (by setting its closure environment to a
+#' something that should always be available and never reloaded; to match
+#' `rlang:::hnd_entrace`, this is [`base::baseenv()`]; this means that things
+#' not available from `base` require use of `<pkg>::` to access).
+#'
+#' @param cnd a condition object (e.g., an error, warning, or message)
+#'
+#' @seealso [`base::withCallingHandlers`] to tie this handler to a condition
+#'   subclass for a block of code, or
+
+#' `r paste0(if(getRversion()>="4")"["else"","\x60base::globalCallingHandlers\x60",if(getRversion()>="4")"]"else"")`,
+
+#'   [`global_handlers_push`], [`global_handlers_remove`],
+#'   [`global_handlers_list`] to enable/disable/list these associations globally

man-roxygen/handler_fn_env_test.R

@@ -0,0 +1,25 @@
+# See notes on the use of `r ...` dynamic R code in roxygen2 comments
+# `utils_conditions.R`. We have to use a bit different code to get this to work
+# inside this template tag file, leading to long `r ...` chunks; don't
+# wrap/fill/format these, or else current roxygen2 at time of writing will not
+# properly process them. Keep the blank lines around them to help prevent
+# accidental auto-formatting.
+
+#' @param .fn_env_test optional; a single string, selected from the choices
+#'   listed in the nominal default value, with the effective default being the
+#'   first choice listed; indicates how [`rlang::fn_env`]s of handler functions
+#'   should be tested for equality when comparing handler functions for
+#'   equality. Here, `fn_env` is the closure environment for closure functions,
+#'   or the base namespace environment for primitive functions. Choosing
+#'   `"label"` means to test the [`rlang::env_label`]s of these environments,
+#'   intended to be somewhat strict while allowing a package function to remain
+#'   equal to "itself" if its formals and body haven't changed; `"identical"`
+#'   means to use [`base::identical`] with its defaults (ignoring bytecode and
+#'   srcref); `"ignore"` means to ignore the `fn_env`s when comparing functions.
+#'   The more lenient comparisons provide some flexibility when working with
+#'   handler functions that aren't carefully crafted to work with functions
+#'   based on stricter equality tests that
+
+#' `r paste0(if(getRversion()>="4")"["else"","\x60base::globalCallingHandlers\x60",if(getRversion()>="4")"]"else"")`
+
+#'   uses.