
<!-- README.md is generated from README.Rmd. Please edit that file -->

# ellipsis

<!-- badges: start -->

[![Lifecycle:
superseded](https://lifecycle.r-lib.org/articles/figures/lifecycle-superseded.svg)](https://lifecycle.r-lib.org/articles/stages.html)
[![CRAN
status](https://www.r-pkg.org/badges/version/ellipsis)](https://cran.r-project.org/package=ellipsis)
[![R-CMD-check](https://github.com/r-lib/ellipsis/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/r-lib/ellipsis/actions/workflows/R-CMD-check.yaml)
[![Codecov test
coverage](https://codecov.io/gh/r-lib/ellipsis/graph/badge.svg)](https://app.codecov.io/gh/r-lib/ellipsis)
<!-- badges: end -->

Superseded by rlang. All the functionality in ellipsis is now provided
by rlang.

------------------------------------------------------------------------

Adding `...` to a function is a powerful technique because it allows you
to accept any number of additional arguments. Unfortunately it comes
with a big downside: any misspelled or extraneous arguments will be
silently ignored. This package provides tools for making `...` safer:

- `check_dots_evaluated()` errors if any components of `...` are not
  evaluated. This allows an S3 generic to state that it expects every
  input to be evaluated.

- `check_dots_unnamed()` errors if any components of `...` are named.
  This allows you to collect arbitrary unnamed arguments, warning if the
  user misspells a named argument.

- `check_dots_empty()` errors if `...` is used. This allows you to use
  `...` to force the user to supply full argument names, while still
  warning if an argument name is misspelled.

Thanks to [Jenny Bryan](https://github.com/jennybc) for the idea, and
[Lionel Henry](https://github.com/lionel-) for the heart of the
implementation.

## Installation

Install the released version from CRAN:

``` r
install.packages("ellipsis")
```

Or the development version from GitHub:

``` r
devtools::install_github("r-lib/ellipsis")
```

## Example

`mean()` is a little dangerous because you might expect it to work like
`sum()`:

``` r
sum(1, 2, 3, 4)
#> [1] 10
mean(1, 2, 3, 4)
#> [1] 1
```

This silently returns the incorrect result because `mean()` has
arguments `x` and `...`. The `...` silently swallows up the additional
arguments. We can use `ellipsis::check_dots_used()` to check that every
input to `...` is actually used:

``` r
safe_mean <- function(x, ..., trim = 0, na.rm = FALSE) {
  ellipsis::check_dots_used()
  mean(x, ..., trim = trim, na.rm = na.rm)
}

safe_mean(1, 2, 3, 4)
#> Error in `safe_mean()`:
#> ! Arguments in `...` must be used.
#> ✖ Problematic arguments:
#> • ..1 = 2
#> • ..2 = 3
#> • ..3 = 4
#> ℹ Did you misspell an argument name?
```
