-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.Rmd
163 lines (103 loc) · 5.42 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
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
---
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%"
)
```
# assertions <a href="https://selkamand.github.io/assertions/"><img src="man/figures/logo.png" align="right" height="138"/></a>
<!-- badges: start -->
[](https://lifecycle.r-lib.org/articles/stages.html#experimental) [](https://app.codecov.io/gh/selkamand/assertions?branch=main) [](https://github.com/selkamand/assertions/actions/workflows/R-CMD-check.yaml)
[](https://github.com/selkamand/assertions)
[](https://github.com/selkamand/assertions/commits/main)
[](https://github.com/selkamand/assertions/issues?q=is%3Aissue+is%3Aclosed)
[](https://cran.r-project.org/package=assertions)
[](https://cran.r-project.org/package=assertions)
<!-- badges: end -->
Simple assertions with sensible defaults and customisable error messages.
## Overview
The goals with assertions are to provide
1. Convenient assertion calls (e.g. `assert_number()`)
2. A general `assert` function that asserts any possible condition/s and throws informative error messages
3. Extremely user friendly error message defaults.
4. Easily customisable error messages, with inline code evaluation & styling powered by the `cli` package
5. Simple creation of custom assertion functions with user-specified defaults
## Installation
``` r
install.packages("assertions")
```
### Development version
To get a bug fix or to use a feature from the development version, you can install the development version of assertions from GitHub.
``` r
# install.packages('remotes')
remotes::install_github('selkamand/assertions')
```
## Quick Start
All assertions start with `assert`, which means you just type it in and levarage autocomplete suggestions to look through all available options
```{r, eval = FALSE}
# Load library
library(assertions)
# Use premade assertions
assert_character(c('a', 'b', 'c'))
assert_number(2)
assert_flag(TRUE)
# Assert anything
assert(1000 % 2 == 0)
# Assert multiple conditions at once (all must be true)
assert(1000 % 2 == 0, 6/2 == 3)
```
## Customizing Error Messages
```{r, eval = FALSE}
# Customise any error messages using the `msg` argument
assert_number("A", msg = "Please supply a number!")
# Evaluate code in your error message using '{}' operators
foo = "A"
assert_number(foo, msg = "'{foo}' is not a number :(. Try again")
# Emphasise cetain words in error using {.strong text_to_emphasise}
assert_number("A", msg = "{.strong Try again}")
```
For advanced customisation, see [cli documentation](https://cli.r-lib.org/reference/inline-markup.html?q=.strong#classes)
## Create your own assertion functions
Have a custom assertion you want to use repeatedly?
Creating your own assertion functions is extremely easy
Just use `assert_create()`, you just need to supply:
1. a function that returns TRUE/FALSE when assertion should PASS/FAIL
2. a default error message
**How about an example?**
```{r, eval = FALSE}
# Create a function that asserts input is lowercase
assert_lowercase <- assert_create(
func = function(x) {x == tolower(x)},
default_error_msg = "'{arg_name}' must be entirely lowercase"
)
#Assertion passes if input is lowercase
assert_lowercase("all lower case")
#But throws the expected error if uppercase characters are present
assert_lowercase("NOT all lower case")
```
See `?assert_create()` for details
## Vectorised assertions
Assertions may have *vectorised* versions that test whether *all* elements in a vector/matrix meet a condition.
For example:
- `assert_greater_than()` expects a single number as an input
- `assert_all_greater_than()` works on vectors/matrices.
Vectorised functions have the `assert_all_` prefix.
## Contributing to this package
Two options
### Request an assertion
1. Open a github issue and request away. I'm happy to implement a tonne more assertions, just let me know what you want
### Creating assertions yourself
1. Create a custom `assert_something` function with a call to `assert_create()` or `assert_create_chain()`
2. Create a github issue with the assertion creation code + any helper function you pass to the `func` argument (e.g. `is_something()`)
## Similar Packages
Great alternative packages for writing assertions include:
- [`assertthat`](https://github.com/hadley/assertthat)
- [`checkmate`](https://github.com/mllg/checkmate)
- [`assertive`](https://bitbucket.org/richierocks/assertive)
- [`ensurer`](https://github.com/smbache/ensurer)
Each package has its own features and syntax. So hopefully there is one that suits your needs and preferences. I'm a big fan of `checkmate` for its speed, `assertive` for its huge library of ready-made assertion functions, and `assertthat` for its error message customization.