README.md
1
2<!-- README.md is generated from README.Rmd. Please edit that file -->
3
4# ellipsis
5
6<!-- badges: start -->
7
8[](https://lifecycle.r-lib.org/articles/stages.html)
10[](https://cran.r-project.org/package=ellipsis)
12[](https://travis-ci.org/r-lib/ellipsis)
14[](https://codecov.io/gh/r-lib/ellipsis?branch=master)
16<!-- badges: end -->
17
18Adding `...` to a function is a powerful technique because it allows you
19to accept any number of additional arguments. Unfortunately it comes
20with a big downside: any misspelled or extraneous arguments will be
21silently ignored. This package provides tools for making `...` safer:
22
23 - `check_dots_used()` errors if any components of `...` are not
24 evaluated. This allows an S3 generic to state that it expects every
25 input to be evaluated.
26
27 - `check_dots_unnamed()` errors if any components of `...` are named.
28 This allows you to collect arbitrary unnamed arguments, warning if
29 the user misspells a named argument.
30
31 - `check_dots_empty()` errors if `...` is used. This allows you to use
32 `...` to force the user to supply full argument names, while still
33 warning if an argument name is misspelled.
34
35Thanks to [Jenny Bryan](https://github.com/jennybc) for the idea, and
36[Lionel Henry](https://github.com/lionel-) for the heart of the
37implementation.
38
39## Installation
40
41Install the released version from CRAN:
42
43``` r
44install.packages("ellipsis")
45```
46
47Or the development version from GitHub:
48
49``` r
50devtools::install_github("r-lib/ellipsis")
51```
52
53## Example
54
55`mean()` is a little dangerous because you might expect it to work like
56`sum()`:
57
58``` r
59sum(1, 2, 3, 4)
60#> [1] 10
61mean(1, 2, 3, 4)
62#> [1] 1
63```
64
65This silently returns the incorrect result because `mean()` has
66arguments `x` and `...`. The `...` silently swallows up the additional
67arguments. We can use `ellipsis::check_dots_used()` to check that every
68input to `...` is actually used:
69
70``` r
71safe_mean <- function(x, ..., trim = 0, na.rm = FALSE) {
72 ellipsis::check_dots_used()
73 mean(x, ..., trim = trim, na.rm = na.rm)
74}
75
76safe_mean(1, 2, 3, 4)
77#> Error: 3 components of `...` were not used.
78#>
79#> We detected these problematic arguments:
80#> * `..1`
81#> * `..2`
82#> * `..3`
83#>
84#> Did you misspecify an argument?
85```
86
){kind=link}
){kind=link}
){kind=link}