stopperr: Error Checking, Banking, and Processing

In j-martineau/uj: Utilities by JAM

Error Checking, Banking, and Processing

Description

Bank error messages in the immediate environment of a function to allow for exhaustive error checking before throwing an exception. Results in a possibly multiple-error, accumulated message to be processed upon completion of error checking.

Usage

stopperr(..., fun = "", stack = "")

getterr()

purgerr()

stopper(..., fun = "", stack = "")

getter()

purger()

err_if(test, ..., fun = "", stack = "", d = " ")

err_if_not(test, ..., fun = "", stack = "", d = " ")

errs_ifs(..., fun = "", stack = "", d = " ")

errs_if_nots(..., fun = "", stack = "", d = " ")

err_if_pop(..., fun = "", stack = "", d = " ")

errs_if_pop(..., fun = "", stack = "")

errs(errs, stack = "")

err(..., stack = "", d = " ")

banked_errs(gens = 0)

checkerr(gens = 0)

checker(gens = 0)

bankerr(..., gens = 0, d = "")

bankerrs(..., gens = 0)

Arguments

...	Unnamed arguments.
fun	A character scalar naming the function generating an error or errors.
stack	An optional character vector naming the lineage of the function generating the error. If NULL, retrieves the stack under the assumption that the immediate calling function is Where the error is generated.
test	A non-NA logical scalar.
d	A non-NA character scalar delimiter for collapsing ... into a an error message.
gens	A complete non-negative whole-number scalar indicating the number of generations back in the call stack in which to bank and/or check for error messages.
funs	A complete character vec containing 1 or more property function names.

Details

Primary stopping functions

stopperr or stopper	Stops execution by:
	Posting an alert header the console with the following components: an error 'ERROR' title and a subheader identifying the function Where the error originated (from FUN). Posting one or more error message to the console following the header, each preceded by a bullet, Where each element of each ... arg is a separate error message. Creating a simpleError object with an error message consisting of an abbreviated function call lineage given as a vector in stack. Attaching the function identity, package identity, and associated message(s) to the simpleError object as attributes. Archiving the simpleError object in the global variable .ppp_LAST_ERR_ppp. (which can be retrieved by calling getter() and can be purged by calling purger()). Allows for error tracing in the circumstance that R purges the last error in final error processing. Calling stop with the simpleError object as the argument.
checkerr or checker	Calls stopper with any error messages banked by the functions described in sections error banking utilities functions and condition-based error-checking functions. If none are banked, does nothing.
purgerr or purger	Purges the most recent simpleError object generated by this family of functions.
getterr or getter	Gets the most recent simpleError object generated by this family of functions.

Both stopperr / stopper and checkerr / checker can identify error-generating functions further up the call Stack than the function in which they are called:

• stopperr / stopper uses args fun, and stack to identify the error-generating function.

• checkerr / checker uses arg gens to identify the error-generating function.

Secondary stopping functions

These functions are designed to be called directly from the function Where an error is generated. It gathers the name of the function generating the error rather than requiring the user to provide the function name. These functions operate as follows:

Errs	Calls stopperr treating each element of each ... arg as a separate error message, allowing for compiling multiple error message before processing.
err	Calls stopperr with a single error message constructed by collapsing all elements of all ... args into a character scalar error message before processing.

Multiple-error conditional stopping functions

These functions conditionally compile multiple errors, and if any are compiled, they notify the user and stop execution.

errs_if_nots	Conditionally compiles errors, treating each odd-numbered ... arg as a test and each even-numbered ... arg as the corresponding error message if the test is FALSE, and calls stopperr if any are compiled.
errs_if_pop	Calls stopperr if there are any ... args, treating each ... arg as a separate error message.
errs_ifs	Conditionally compiles errors, treating each odd-numbered ... arg as a test and each even-numbered ... arg as the corresponding error message if the test is TRUE, and calls stopperr if any are compiled.

Single-error conditional stopping functions

These functions conditionally construct a single error, and if one is constructed, they notify the user and stop execution.

err_if_pop	If there are any ... args, collapsing them into a character scalar error message, and calls stopperr.
err_if_not	If TEST = FALSE, collapses ... args to a character scalar error message and calls stopperr.
err_if	If TEST = TRUE, collapses ... args to a character scalar error message and calls stopperr.

Utility functions

These functions purge and retrieve the most recent error generated by this family of functions.

Primary error banking functions

Error banking utility functions: These functions are utilities for banking user-defined error messages within a function to allow for checking for multiple errors in separate statements and banking those error messages as they are checked, waiting to process banked error messages until an error checking block is completed. These functions also allow for generating and checking for error messages further up the call Stack than the function in which the error banking/processing occurs by specifying the number of generations back in the call Stack Where error banking/processing occurs in gens:

banked_errs	Retrieves the bank of error message stored in the environment of the function gens generations back in the call Stack.
bankerrs	Banks each element of complete character vec as an individual error message.
bankerr	Banks an arbitrary error message (built by collapsing ... args) in the environment of the function gens generations back in the call Stack.

All functions in family check_xxx also check for specific types of errors and incrementally bank errors if any are found.

Error checking / conditional error banking functions

checkerr checks for any banked error messages. If there are any, processes them and stops execution. Otherwise, does nothing.

Value

**A **simpleError object

getterr

A character vector

banked_Errs

All others are called for their side effects.

See Also

Other Errs: check_xxx_help()

Examples

egStopper <- function() {stopperr('stopper demo')}
egErrs    <- function() {Errs('Errs demo1', 'Errs demo2')}
egErr     <- function() {err('err', 'demo')}
egErrors  <- function(..., tf = NA, lgl = 42, not = FALSE, pop = NULL,
                           fail = simpleError('error'), funs = 2:4, spec = 42,
                           vals = 42, class = 42, nas.or = NULL, nll.or = NA,
                           chars = '5', when.a = "error.a", when.b = "error.b") {
  bankerr(...elt(1))
  bankErrs(...elt(2), ...elt(3))
  check_tf(tf = tf)
  check_lgl(lgl = lgl)
  check_t(not = not)
  check_pop(pop = pop)
  check_fail(fail = fail)
  check_funs(c('cmp_ch1_vec', 'cmp_ngw_vec'), funs = funs)
  check_spec('cmp_ch1_vec|nll|nas', spec = spec)
  check_vals(letters, vals = vals)
  check_cls('data.frame', class)
  check_nas_or(c('cmp_ch1_vec', 'cmp_ngw_vec'), nas.or = nas.or)
  check_nll_or(c('cmp_ch1_vec', 'cmp_ngw_vec'), nll.or = nll.or)
  check_chars(letters, chars = chars)
  check_when(when.a = when.a, when.b = when.b, c('error.a', ''), c('error.b', ''))
  checkerr()
}
## Not run: 
  egstopperr()
  getterr()
  purgerr()
  getter()
  egErrs()
  egErrs()
  egErrors()

## End(Not run)

j-martineau/uj documentation built on Sept. 14, 2024, 4:40 a.m.