reserved-conditions: Special condition names

In burchill/catchr: Taking the Pain Out of Catching and Handling Conditions

Description

In addition to having reserved terms for use in making condition-handling plans, catchr also places special meaning on two types of conditions, misc and last_stop. The misc is very useful, last_stop is something most users should probably avoid.

The misc condition

The names of the named arguments passed to make_plans correspond to the type of conditions each plan is designed for—specifically, if any of a condition's classes match a plan's name, it will be caught by that plan. By default, all conditions have a class of "condition".

There is nothing special about a condition with a class of "misc" in base R, although there are no normal base R functions that would automatically raise such a condition. However, in catchr, using the name misc for a plan means that this plan will be applied to any condition that does not already have a plan specified for it. Consider the following example:

plans <- make_plans(warning = collect, message = collect, error = exit, misc = collect)

These plans will collect every non-error condition into three sublists, one for warnings, one for messages, and one for everything else—"misc". If one used condition = collect instead of misc, warnings and messages would be collected twice: once in each of their respective sublists, and another time in "condition", since each type also has that class. misc will not catch warnings or messages in the scenario above.

Since ~99\

The last_stop condition

This condition name is reserved for exit, user_exit() and exit_with(). There is basically zero chance any code other than catchr will ever raise a condition of "last_stop", so this shouldn't be a problem, but until catchr becomes more mature, do not use this name for any condition or plan.

burchill/catchr documentation built on Sept. 22, 2021, 10:34 p.m.