ellipsis v0.2.0

0

Monthly downloads

0th

Percentile

Tools for Working with ...

The ellipsis is a powerful tool for extending functions. Unfortunately this power comes at a cost: misspelled arguments will be silently ignored. The ellipsis package provides a collection of functions to catch problems and alert the user.

Readme

ellipsis

Lifecycle:
maturing CRAN
status Travis build
status Codecov test
coverage

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 for the idea, and Lionel Henry for the heart of the implementation.

Installation

Install the released version from CRAN:

install.packages("ellipsis")

Or the development version from GitHub:

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

Example

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

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:

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: 3 components of `...` were not used.
#> 
#> We detected these problematic arguments:
#> * `..1`
#> * `..2`
#> * `..3`
#> 
#> Did you misspecify an argument?

Functions in ellipsis

Name Description
check_dots_unnamed Check that all dots are unnamed
check_dots_empty Check that dots are unused
safe_median Safe version of median
ellipsis-package ellipsis: Tools for Working with ...
dots_empty Helper for consistent documentation
check_dots_used Check that all dots have been used
No Results!

Last month downloads

Details

License GPL-3
Encoding UTF-8
LazyData true
RoxygenNote 6.1.1
URL https://github.com/r-lib/ellipsis
BugReports https://github.com/r-lib/ellipsis/issues
NeedsCompilation yes
Packaged 2019-06-20 14:19:38 UTC; lionel
Repository CRAN
Date/Publication 2019-06-20 14:50:15 UTC
suggests covr , testthat
depends R (>= 3.1)
imports rlang (>= 0.3.0)
Contributors RStudio

Include our badge in your README

[![Rdoc](http://www.rdocumentation.org/badges/version/ellipsis)](http://www.rdocumentation.org/packages/ellipsis)