jimhester / generics

Common generic methods

generics

generics is designed to alleviate the situation where multiple packages define a generic with the same name. For example, if two packages define a fit() generic and methods, there will be conflicts when both packages are loaded. One approach would be for one package to import the other but this may result in many additional package dependencies during installation.

Installation

To install generics, use:

# install.packages("devtools")
devtools::install_github("r-lib/generics")

Usage

generics is a simple, lightweight package that contains S3 generics to be used by other packages. Some examples are:

library(generics)

fit
#> function (object, ...) {
#>   UseMethod("fit")
#> }
#> <bytecode: 0x7fca3883ac68>
#> <environment: namespace:generics>

tidy
#> function (x, ...) {
#>   UseMethod("tidy")
#> }
#> <bytecode: 0x7fca3944a8d0>
#> <environment: namespace:generics>

To use this in your package we recommend that you import and re-export the generics of interest. For example, if you want to provide a method for the S3 fit() generic, you’d using the following the roxygen2 code:

#' @importFrom generics explain
#' @export
generics::explain
#> function (x, ...) {
#>   UseMethod("explain")
#> }
#> <bytecode: 0x7fca379d14a8>
#> <environment: namespace:generics>

As an example, the recipes package defines a number of tidy() S3 methods by importing this package (whereas it previously depended on broom).

It is also highly recommended that you add an alias in the documentation of your method for the generic, such as:

#' @alias explain

In that way, when someone uses ?explain, your specific method will show up as one of the man page options.