Package catchr. R topics documented: December 30, Type Package. Title Catch, Collect, and Raise Conditions. Version 0.1.0

Transcription

1 Package catchr December 30, 2018 Type Package Title Catch, Collect, and Raise Conditions Version Maintainer Zachary Burchill Simple code to catch, collect, and raise conditions (errors, warnings, messages, etc.) without halting/restarting processes. License MIT + file LICENSE Encoding UTF-8 LazyData true RoxygenNote NeedsCompilation no Author Zachary Burchill [aut, cre] Repository CRAN Date/Publication :40:07 UTC R topics documented: collect_conditions raise_conditions signal_custom_condition warn_now Index 7 1

2 2 collect_conditions collect_conditions Collect conditions, without halting processes collect_conditions (and its shorter alias, col_cond) evaluates an expression, and will catch and collect all the conditions specified (e.g., warnings, errors, messages, etc.), without halting/restarting the evaluation of the expression (unless it encounters an error). It will then return a named list with the result of the expression and sublists that contain all the collected conditions (see Value). collect_conditions(expr, catcherrors = TRUE, asstrings = FALSE, dropmiscifempty = TRUE) col_cond(expr, catcherrors = TRUE, asstrings = FALSE, dropmiscifempty = TRUE) expr catcherrors The expression to be evaluated. A logical which, if TRUE, will catch any error, prevent it from being raised, and return it in the named list. The process will still halt when an error occurs however. asstrings A logical which, if TRUE, will convert the captured conditions into strings of their messages, instead of keeping them as S3 condition objects. dropmiscifempty A logical which, if TRUE, will drop the "conditions" sublist from the returned list if there were no miscellaneous conditions signalled (ie 99% of the time). Details The way this function suppresses conditions is simply by attempting to find the first available restart with "muffle" in its name and invoke that. This works well for most warnings and messages, which are muffled by default with "mufflewarning" and "mufflemessage". Barring any restarts with this property, it will simply return NULL as a restart (i.e., most likely the case for custom miscellaneous conditions). If you have some really funky conditions being signalled that somehow 1) don t have "muffle<condition>" as a restart or 2) have a custom restart with "muffle" in the name that takes precedence, this might lead to unexpected results, and you probably shouldn t use this function. For a more descriptive account of the object returned, see Value. If no warnings or message are raised in the expression, their named sublists will still be present, but empty. Additionally, if the expression encounters an error, the value of the "value" sublist will be returned as NULL.

3 raise_conditions 3 Value A named list with the following structure: Examples value: The output of the expression, if it did not encounter an error. warnings: A list of the warnings raised in evaluating the expression. messages: A list of the warnings raised in evaluating the expression. errors: A list of errors raised in evaluating the expression. If catcherrors==false, then this will not be returned. conditions: A list of miscellaneous conditions (defined as conditions that do not inherit from warnings, errors, or messages) raised in evaluating the expression. If dropmiscifempty==true, this sublist will not be included unless these rare conditions are signalled. res <- collect_conditions({ warning("warning 1") message("message 1") warning("warning 2") signal_custom_condition("custom condition #1!") signal_custom_condition("custom condition #2!") stop("error 1") message("message 2 (not signalled)") "test value" }, asstrings = FALSE, catcherrors = TRUE, dropmiscifempty = TRUE) print(res) # Without the dropmiscifempty=true and no miscellaneous conditions being raised, # there won't be any res$conditions res <- collect_conditions({ warning("warning 1") message("message 1") warning("warning 2") stop("error 1") message("message 2 (not signalled)") "test value" }, asstrings = TRUE, catcherrors = TRUE, dropmiscifempty = FALSE) print(res) raise_conditions Raise and display collected conditions There are times where you might want to raise the conditions that you have collected via collect_conditions, for example, after your code has processed them, etc. These functions help with that

4 4 raise_conditions raise_conditions(col_conds, display_errors = TRUE, raise_errors = TRUE, added_text = ":") evaluate_results(col_conds, raise_errors = TRUE) raise_col_warnings(conditions, added_text = ":") raise_col_messages(conditions, added_text = ":") raise_col_conditions(conditions, added_text = ":", tostderr = TRUE) print_errors(conditions, added_text = ":") Details col_conds A named list of the kind returned from collect_conditions. display_errors A logical, which, if TRUE, will display the errors to stderr just like the messages and warnings. raise_errors added_text conditions tostderr A logical, which, if TRUE, will raise the collected errors. Otherwise, errors will not be signalled. A string that will be appended immediately after the title of each type of condition being raised. E.g., a value of " in x[1]:" would print "Messages in x[1]:" followed by a newline for the messages. A list of conditions (i.e., a sublist from what is returned from collect_conditions). A logical, which, if TRUE, prints the results to stderr() rather than stdout(). raise_conditions will raise all the conditions from the named list returned from collect_conditions, and display them in a pretty, readable way at the same time, returning the input invisibly. You have the option to raise errors or not. evaluate_results will strip away the condition sublists of a list returned from collect_conditions, and optionally raise errors if there are any. raise_col_warnings, raise_col_messages, and raise_col_conditions will raise and display lists of conditions, while print_errors will display errors rather than raise them. See Also collect_conditions, warn_now Examples res <- collect_conditions({ warning("warning 1") message("message 1")

5 signal_custom_condition 5 warning("warning 2") signal_custom_condition("custom condition #1!") signal_custom_condition("custom condition #2!") stop("error 1") message("message 2 (not signalled)") "test value" }, catcherrors = TRUE) raise_conditions(res, raise_errors = FALSE) # A demonstration of how it can be used with packages like purrr ## Not run: # Let's pretend you got l from doing a purrr::map on some data l <- list( collect_conditions({warning("bad!"); warning("uh oh!"); 1}), collect_conditions({message("this is fine"); warning("this is bad!"); 2}), collect_conditions({message("have a nice day!"); stop("die!"); 3}, catcherrors=true) ) results <- purrr::imap(l, function(e, i) raise_conditions(e, raise_errors=false, added_text=paste0(" in x[",i,"]:"))) %>% evaluate_results() ## End(Not run) signal_custom_condition Signal custom conditions If you want to signal your own custom conditions (i.e., not messages or warnings), you can do so with this function. However, most of the time (other than testing code), you should probably stick to warnings and errors. signal_custom_condition(msg, type = "custom") msg type The message you want your condition to have. Your name for the type of condition you want to raise.

6 6 warn_now warn_now Custom functions to display signals (experimental) R has "issues" signalling pre-made message and warning conditions: when you pass these objects to warning or message, they ignore all the additional arguments, so you can t use, say, immediate. = TRUE or appendlf = TRUE. These two functions take care of those problems, respectively. These functions are probably best let be and are more "experimental" in many senses, but they have been exported in case the user wants to make code similar to the other functions in this package. warn_now: The function warning lets you immediately output warnings with immediate.=true, but not if the input is already a condition object (weird, I know). This function is a modified Frankenstein mashup of warning and message that will immediately output warnings regardless of the form of the input (as well as appending a newline character). The downside is that no other additional arguments can be used, but I can t seem to do anything about that at the moment. This is used primarily for raise_conditions and raise_col_warnings. addlf_message: The function message lets you automatically append a newline to a message that you signal, regardless of its form. It suffers from the same argument restrictions as warn_now. warn_now(...) addlf_message(...)... An S3 condition object or whatever values one wants to pass into the original warning or message functions

7 Index addlf_message (warn_now), 6 col_cond (collect_conditions), 2 collect_conditions, 2, 3, 4 evaluate_results (raise_conditions), 3 message, 6 print_errors (raise_conditions), 3 raise_col_conditions (raise_conditions), 3 raise_col_messages (raise_conditions), 3 raise_col_warnings, 6 raise_col_warnings (raise_conditions), 3 raise_conditions, 3, 6 restart, 2 signal_custom_condition, 5 warn_now, 4, 6 warning, 6 7