The
generics package is now on CRAN. generics is a lightweight package that is designed to help developers reduce dependencies for their packages.
The idea is to have many generic S3 functions live in a single package that has almost no dependencies. Normally, if you wanted to create a broom::tidy() method, you would import broom as a dependency, import the tidy() generic, then export it so that package users can have access to that specific method. One issue with this is that your package now carries along the dependencies of the package that defines the generic (in this case, broom).
Consider fit(). There are at least 15 packages that export an object called fit (either a function or method), and at least 12 have specific S3 fit() methods. When more than one is loaded, there is a potential for conflicts to arise:
library(NMF)
library(text2vec)
#>
#> Attaching package: 'text2vec'
#> The following object is masked from 'package:NMF':
#>
#> fit
generics provides a way to avoid such conflicts. To do so, a package would include generics as an import dependency, import the generic function of interest, then re-export using the roxygen2 commands:
#' @importFrom generics fit
#' @export
generics::fit
One interesting aspect of the package is that the generics function documentation is dynamic. Suppose that generics is loaded in a clean R session. If you look at the help file ?generics::tidy, the documentation page has:
Methods:
No methods found in currently loaded packages.
However, once another package is loaded with an exported tidy() method, ?generics::tidy shows a list of all exported methods and includes a link to the help page specific to each one. For example, after loading the embed package:
Methods:
See the following help topics for more details about individual
methods:
‘embed’
• ‘step_embed’: ‘step_embed’
• ‘step_lencode_bayes’: ‘step_lencode_bayes’
• ‘step_lencode_glm’: ‘step_lencode_glm’
• ‘step_lencode_mixed’: ‘step_lencode_mixed’
‘recipes’
• ‘check_cols’: ‘check_cols’
• ‘check_missing’: ‘check_missing’
• ‘check_range’: ‘check_range’
The current list of S3 generics that are included in the package are: as.factor, as.ordered, augment, calculate, compile, components, equation, estfun, evaluate, explain, fit, fit_xy, generate, glance, hypothesize, interpolate, intersect, is.element, learn, prune, refit, setdiff, setequal, specify, tidy, train, union, var_imp, varying_args, and visualize.
Thanks to those who contributed to the discussion prior to releasing the package: Achim Zeileis, Alex Hayes, Andrew Bray, Andy Liaw, Chester Ismay, Davis Vaughan, Hadley Wickham, Mitchell O’Hara-Wild, Przemyslaw Biecek, Rob Hyndman, Thomas Lin Pedersen, and Torsten Hothorn.