The R Project SVN – R – Diff – /trunk/src/library/methods/man/getMethod.Rd

 \alias{findMethod}
 \alias{existsMethod}
 \alias{selectMethod}
 \alias{hasMethod}
 \description{
+  The function \code{selectMethod()} returns the method that
-  Functions to look for a method corresponding to a given generic function and signature.
+  would be selected for a call to function \code{f} if the arguments had
-  The functions \code{getMethod} and \code{selectMethod} return the method; the functions
+  classes as specified by \code{signature}.  Failing to find a method
+  is an error, unless argument \code{optional = TRUE}, in which case
+  \code{NULL} is returned.
-  \code{existsMethod} and \code{hasMethod} test for its existence.  In both
+  The function \code{findMethod()} returns a list of
-  cases the first function only gets direct definitions and the second
+  environments that contain a method for the specified function and signature; by
-  uses inheritance.  In all cases, the search is in the generic function itself or in
+  default, these are a subset of the packages in the current search
-  the package/environment specified by argument \code{where}.
+  list.  See section \dQuote{Using \code{findMethod()}} for details.
-  The function \code{findMethod} returns the package(s) in the search
+The function \code{getMethod()} returns the method corresponding to the
-  list (or in the packages specified by the \code{where} argument) that
+function and signature supplied similarly to \code{selectMethod}, but
+without using inheritance or group generics.
+The functions  \code{hasMethod()}  and
+\code{existsMethod()} test whether \code{selectMethod()} or
-  contain a method for this function and signature.
+\code{getMethod()}, respectively, finds a matching method.
+}
 \usage{
-existsMethod(f, signature = character(), where)
+  selectMethod(f, signature, optional = FALSE, useInherited =,
+             mlist = , fdef = , verbose = , doCache = )
   findMethod(f, signature, where)
-   getMethod(f, signature = character(), where, optional = FALSE, mlist, fdef)
+  getMethod(f, signature = character(), where, optional = FALSE,
+             mlist, fdef)
-   hasMethod(f, signature = character(), where)
+  existsMethod(f, signature = character(), where)
-selectMethod(f, signature, optional = FALSE, useInherited =,
+  hasMethod(f, signature = character(), where)
-             mlist = , fdef = , verbose = , doCache = )
+}
 \arguments{
   \item{f}{a generic function or the character-string name of one.}
   \item{signature}{the signature of classes to match to the arguments
     of \code{f}.  See the details below.}
-  \item{where}{the position or environment in which to look for the
+  \item{where}{the environment in which to look for the
-    method(s):  by default, the table of methods defined in the generic
+    method(s).  By default, if the call comes from the command line, the table of methods defined in the generic
+    function itself is used, except for \code{findMethod} (see the
-    function itself is used.}
+    section below).}
   \item{optional}{if the selection in \code{selectMethod} does not find
     a valid method an error is generated, unless \code{optional} is
-    true.  In that case, the value returned is \code{NULL} if no method
+    \code{TRUE},  in which case the value returned is \code{NULL}.}
-    matches.}
   \item{mlist, fdef, useInherited, verbose, doCache}{optional arguments
     to  \code{getMethod} and \code{selectMethod} for internal use.  Avoid
     these: some will work as expected and others will not, and none of
-    them is required for normal use of the functions.}
+    them is required for normal use of the functions.  But see the
+    section \dQuote{Methods for \code{as()}} for nonstandard inheritance.}
+}
+\section{Using \code{findMethod()}}{
+As its name suggests, this function is intended to behave like
+\code{\link{find}}, which produces a list of the packages on the
+current search list which have, and have exported, the object named.
+That's what \code{findMethod} does also, by default.  The
+\dQuote{exported} part in this case means that the package's namespace
+has an \code{exportMethods} directive for this generic function.
+An important distinction is that the absence of such a directive does
+not prevent methods from the package from being called once the
+package is loaded.  Otherwise, the code in the package could not use
+un-exported methods.
+So, if your question is whether loading package \code{thisPkg} will define a
+method for this function and signature, you need to ask that question
+about the namespace of the package:
+\code{findMethod(f, signature, where = asNamespace("thisPkg"))}
+If the package did not export the method, attaching it and calling
+\code{findMethod} with no \code{where} argument will not find the
+method.
+Notice also that the length of the signature must be what the
+corresponding package used.  If \code{thisPkg} had only methods for
+one argument, only length-1 signatures will match (no trailing
+\code{"ANY"}), even if another currently loaded package had signatures
+with more arguments.
+}
+\section{Methods for \code{as()}}{
+The function \code{\link{setAs}} allows packages to define methods for
+coercing one class of objects to another class.  This works internally
+by defining methods for the generic function \code{\link{coerce}(from,
+to)},
+which can not be called directly.
+The \R evaluator selects
+methods for this purpose using a different form of inheritance.  While
+methods can be inherited for the object being coerced, they cannot
+inherit for the target class, since the result would not be a valid
+object from that class.
+If you want to
+examine the selection procedure, you must supply the optional argument
+\code{useInherited = c(TRUE, FALSE)} to \code{selectMethod}.
+}
 \details{
   The \code{signature} argument specifies classes, corresponding to
   formal arguments of the generic function; to be precise, to the
   \code{signature} slot of the generic function object.  The argument
   selection.  Arguments not supplied in the signature implicitly
   correspond to class \code{"ANY"}; in particular, giving an empty
   signature means to look for the default method.
   A call to \code{getMethod} returns the method for a particular
-  function and signature.  As with other \code{get} functions,
-  argument \code{where} controls where the function looks (by default
-  anywhere in the search list) and argument \code{optional} controls
-  whether the function returns \code{NULL} or generates an error if
-  the method is not found.  The search for the method makes no use of
+  function and signature.   The search for the method makes no use of
   inheritance.
   The function \code{selectMethod} also looks for a method given the
   function and signature, but makes full use of the method dispatch
   mechanism; i.e., inherited methods and group generics are taken into
   corresponding signature, with the one exception that conditional
   inheritance is not used.  Like \code{getMethod}, \code{selectMethod}
   returns \code{NULL} or generates an error if
   the method is not found, depending on the argument \code{optional}.
+Both \code{selectMethod} and \code{getMethod} will normally use the
+current version of the generic function in the R session, which has a
+table of the methods obtained from all the packages loaded in the
+session. Optional arguments can cause a search for the generic function from a
+specified environment, but this is rarely a useful idea.  In contrast,
+\code{findMethod} has a different default and the optional
+\code{where=} argument may be needed.  See the  section \dQuote{Using
+  \code{findMethod()}}.
   The functions \code{existsMethod} and \code{hasMethod} return
   \code{TRUE} or \code{FALSE} according to whether a method is found,
   the first corresponding to \code{getMethod} (no inheritance) and the
   second to \code{selectMethod}.
   Otherwise an error is thrown if \code{optional} is \code{FALSE}  and  \code{NULL} is returned if
   \code{optional} is \code{TRUE}.
 The returned method object is a
   \code{\linkS4class{MethodDefinition}} object, \emph{except} that the default method for a primitive function is required to be the primitive itself.
-Note therefore that the only reliable test that the search failed is \code{is.null()}.
+Note therefore that the only reliable test that the search failed is
+\code{is.null()}.
+The returned value of \code{findMethod} is a list of
+environments in which a corresponding method was found; that is, a
+table of methods including the one specified.
+}
 \references{
+ Chambers, John M. (2016)
+ \emph{Extending R},
+  Chapman & Hall.
+(Chapters 9 and 10.)
  Chambers, John M. (2008)
  \emph{Software for Data Analysis: Programming with R}
-  Springer.  (For the R version.)
- Chambers, John M. (1998)
- \emph{Programming with Data}
- Springer (For the original S4 version.)
+  Springer. (Section 10.6 for some details of method selection.)
+}
 \seealso{\code{\link{Methods_Details}} for the details of method
   selection; \code{\link{GenericFunctions}} for other functions
   manipulating methods and generic function objects;
   \code{\linkS4class{MethodDefinition}} for the class that represents
   method definitions.}
 \examples{
+testFun <-  function(x)x
-setGeneric("testFun", function(x)standardGeneric("testFun"))
+setGeneric("testFun")
 setMethod("testFun", "numeric", function(x)x+1)
 hasMethod("testFun", "numeric")
 \dontrun{[1] TRUE}
 hasMethod("testFun", "integer") #inherited
 \dontrun{[1] TRUE}
 existsMethod("testFun", "integer")
 \dontrun{[1] FALSE}
 hasMethod("testFun") # default method
-\dontrun{[1] FALSE}
+\dontrun{[1] TRUE}
 hasMethod("testFun", "ANY")
 \dontrun{[1] FALSE}
 \dontshow{
 stopifnot(isGeneric("testFun"),
           hasMethod("testFun", "numeric"),
           hasMethod("testFun", "integer"),
           !existsMethod("testFun", "integer"),
-          !hasMethod("testFun"),
+          hasMethod("testFun"),
-          !hasMethod("testFun", "ANY") )
+          hasMethod("testFun", "ANY") )
 removeGeneric("testFun")
+}
+}
 \keyword{programming}
 \keyword{classes}

The R Project SVN R

(root)/trunk/src/library/methods/man/getMethod.Rd @ 63243 – Rev 71366 → 71961