| % File src/library/methods/man/testInheritedMethods.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 2009-2015 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{testInheritedMethods} |
| \alias{testInheritedMethods} |
| \alias{MethodSelectionReport-class} |
| \alias{.Other-class} |
| \title{ |
| Test for and Report about Selection of Inherited Methods |
| } |
| \description{ |
| A set of distinct inherited signatures is generated to test |
| inheritance for all the methods of a specified generic function. If |
| method selection is ambiguous for some of these, a summary of the |
| ambiguities is attached to the returned object. This test should be |
| performed by package authors \emph{before} releasing a package. |
| } |
| \usage{ |
| testInheritedMethods(f, signatures, test = TRUE, virtual = FALSE, |
| groupMethods = TRUE, where = .GlobalEnv) |
| } |
| \arguments{ |
| \item{f}{a generic function or the character string name of one. By default, |
| all currently defined subclasses of all the method signatures for this |
| generic will be examined. The other arguments are mainly options to |
| modify which inheritance patterns will be examined. |
| } |
| \item{signatures}{ |
| An optional set of subclass signatures to use instead of the relevant |
| subclasses computed by \code{testInheritedMethods}. See the Details |
| for how this is done. This argument might be supplied after a call |
| with \code{test = FALSE}, to test selection in batches. |
| } |
| \item{test}{ |
| optional flag to control whether method selection is actually tested. |
| If \code{FALSE}, returns just the list of relevant signatures for |
| subclasses, without calling \code{\link{selectMethod}} for each signature. |
| If there are a very large number of signatures, you may want to collect the full list and then test them in batches. |
| } |
| \item{virtual}{ |
| should virtual classes be included in the relevant subclasses. |
| Normally not, since only the classes of actual arguments will trigger |
| the inheritance calculation in a call to the generic function. |
| Including virtual classes may be useful if the class has no current |
| non-virtual subclasses but you anticipate your users may define such |
| classes in the future. |
| } |
| \item{groupMethods}{ |
| should methods for the group generic function be included? |
| } |
| \item{where}{ |
| the environment in which to look for class definitions. Nearly |
| always, use the default global environment after attaching all the |
| packages with relevant methods and/or class definitions. |
| } |
| } |
| \details{ |
| The following description applies when the optional arguments are |
| omitted, the usual case. |
| First, the defining signatures for all methods are computed by calls |
| to \code{\link{findMethodSignatures}}. |
| From these all the known non-virtual subclasses are found for each |
| class that appears in the signature of some method. |
| These subclasses are split into groups according to which class they |
| inherit from, and only one subclass from each group is retained (for |
| each argument in the generic signature). |
| So if a method was defined with class \code{"vector"} for some |
| argument, one actual vector class is chosen arbitrarily. |
| The case of \code{"ANY"} is dealt with specially, since all classes |
| extend it. A dummy, nonvirtual class, \code{".Other"}, is used to |
| correspond to all classes that have no superclasses among those being |
| tested. |
| |
| All combinations of retained subclasses for the |
| arguments in the generic signature are then computed. |
| Each row of the resulting matrix is a signature to be tested by a call |
| to \code{\link{selectMethod}}. |
| To collect information on ambiguous selections, |
| \code{testInheritedMethods} establishes a calling handler for the |
| special signal \code{"ambiguousMethodSelection"}, by setting the |
| corresponding option. |
| } |
| \value{ |
| An object of class \code{"methodSelectionReport"}. The details of |
| this class are currently subject to change. It has slots |
| \code{"target"}, \code{"selected"}, \code{"candidates"}, and |
| \code{"note"}, all referring to the ambiguous cases (and so of length |
| 0 if there were none). These slots are intended to be examined by the |
| programmer to detect and preferably fix ambiguous method selections. |
| The object contains in addition slots \code{"generic"}, the name of |
| the generic function, and |
| \code{"allSelections"}, giving the vector of labels for all |
| the signatures tested. |
| } |
| \references{ |
| Chambers, John M. (2008) |
| \emph{Software for Data Analysis: Programming with R} |
| Springer. (Section 10.6 for basics of method selection.) |
| |
| Chambers, John M. (2009) |
| \emph{Class Inheritance in R} |
| \url{https://statweb.stanford.edu/~jmc4/classInheritance.pdf}. |
| } |
| \examples{ |
| ## if no other attached packages have methods for `+` or its group |
| ## generic functions, this returns a 16 by 2 matrix of selection |
| ## patterns (in R 2.9.0) |
| testInheritedMethods("+") |
| } |
| |
| \keyword{programming} |
| \keyword{classes} |
| \keyword{methods} |