-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.Rmd
137 lines (107 loc) · 3.83 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# rror
<!-- badges: start -->
[](https://www.tidyverse.org/lifecycle/#experimental)
[](https://CRAN.R-project.org/package=rror)
[](https://travis-ci.org/alistaire47/rror)
[](https://ci.appveyor.com/project/alistaire47/rror)
[](https://codecov.io/gh/alistaire47/rror?branch=master)
<!-- badges: end -->
`rror` is a package to make using classed conditions in R easier. It contains
utilities for creating, raising, and catching conditions including but not
limited to messages, warnings, and errors. It is built on top of the base
condition handling system, and is fully compatible with it.
## Installation
`rror` is not on CRAN yet, but can be installed from GitHub with
``` r
# install.packages("remotes")
remotes::install_github("alistaire47/rror")
```
## What are conditions?
_Conditions_ are a formalized way of providing feedback to the user and handling
runtime issues. In most languages, conditions include errors and warnings; in R,
_messages_ (usually generated with `message()`, equivalent to `warning()` or
`stop()`) are also conditions, used for generating diagnostic messages for the
user.
R also has infrastructure to create, raise, and handle conditions of your own
creation, which may or may not inherit from one of the built-in conditions.
## Why `rror`?
The condition handling system of R is very powerful, but unfortunately most
users don't take advantage of its full power, because it is not trivial to
understand, a process further hindered by limited documentation.
`rror` makes it very simple to leverage more of the power of this system—in
particular working with classed errors. For instance, if a package maintainer
is validating arguments and wants to raise an error for bad input, instead of
generating a `simpleError` from `stop()`, e.g.
```{r}
plus1 <- function(x) {
if (!is.numeric(x)) {
stop("`x` must be numeric")
}
x + 1
}
plus1(2)
tryCatch(
plus1("a"),
error = function(e) str(e)
)
```
the maintainer can raise a classed error, e.g.
```{r}
plus2 <- function(x){
if (!is.numeric(x)) {
rror::raise(rror::error_condition("`x` must be numeric", class = "value_error"))
}
x + 2
}
plus2(3)
rror::except(
plus2("b"),
value_error = function(e) str(e) # we can catch specific error classes!
)
```
Common conditions can be predefined and reused.
`rror`'s condition handling function, `except()`, also has some benefits over
`tryCatch()`. In particular, because the handlers registered in `tryCatch()` are
exiting handlers, it is not very useful for suppressing repeated warnings or
messages and continuing:
```{r}
f1 <- function(i) warning("warning ", i)
tryCatch(
{
for (i in 1:3) f1(i)
2 + 2
},
warning = function(w) print(w)
)
```
`except()` handles errors with exiting handlers, but non-fatal conditions use
local handlers, which lets specific errors be easily suppressed:
```{r}
f2 <- function(i) {
rror::raise(
rror::warning_condition(
paste("warning", i),
class = "number_warning"
)
)
}
rror::except(
{
for (i in 1:3) f2(i)
2 + 2
},
number_warning = function(w) print(w)
)
```