The R Project SVN R

\name{getMethod}
\alias{getMethod}
\alias{findMethod}
\alias{existsMethod}
\alias{getMethods}
\alias{selectMethod}
\alias{hasMethod}
\alias{MethodsListSelect}
\title{ Get or Test for the Definition of a Method }
\description{
  The functions \code{getMethod} and \code{selectMethod} get the
  definition of a particular method; the functions \code{existsMethod}
  and \code{hasMethod} test for the existence of a method.  In both
  cases the first function only gets direct definitions and the second
  uses inheritance.
  The function \code{findMethod} returns the package(s) in the search
  list (or in the packages specified by the \code{where} argument) that
  contain a method for this function and signature.

  The other functions are support functions: see the details below.
}
\usage{
getMethod(f, signature=character(), where, optional=FALSE)

findMethod(f, signature, where)

getMethods(f, where=-1)

existsMethod(f, signature = character(), where)

hasMethod(f, signature=character())

selectMethod(f, signature, optional=FALSE, useInherited,
             mlist=getMethods(f), fdef = getGeneric(f))

MethodsListSelect(f, env, mlist, fEnv, finalDefault, evalArgs,
                  useInherited, fdef)

}
\arguments{
  \item{f}{ The character-string name of the generic function.

    In \code{getMethods} only, this argument may be a function
    definition, in which case the special methods list object, if any,
    stored in the environment of the function is returned.  (This usage
    is largely for internal purposes; you aren't likely to have such a
    function definition for direct use.)}
  \item{signature}{ The signature of classes to match to the arguments
    of \code{f}.  The vector of strings for the classes should be named,
    and the names must match formal argument names of \code{f}.  If not
    named, the signature is assumed to apply to the arguments of
    \code{f} in order, but note below for \code{selectMethod}.

    For \code{selectMethod}, the signature can optionally be an
    environment with classes assigned to the names of the corresponding
    arguments.  Note:  the names correspond to the names of the classes, \emph{not}
    to the objects supplied in a call to the generic function.}
  \item{where}{ The position or environment in which to look for the method:  by default,
      anywhere in
    the current search list.}
  \item{optional}{ If the selection does not produce a unique result,
    an error is generated, unless this argument is \code{TRUE}.  In that
    case, the value returned is either a \code{MethodsList} object, if
    more than one method matches this signature, or \code{NULL} if no
    method matches.}

  \item{mlist, fdef}{In \code{selectMethod}, the \code{MethodsList} object
    and/or the generic function object can be explicitly supplied.  (Unlikely to be used, except in the
    recursive call that finds matches to more than one argument.)}

  \item{env}{The environment in which argument evaluations are done in
    \code{MethodsListSelect}.  Currently must be supplied, but should
    usually be \code{sys.frame(sys.parent())} when calling the function
    explicitly for debugging purposes.}
  \item{fEnv, finalDefault, evalArgs, useInherited}{ Internal-use
    arguments for the function's environment, the method to use as
    the overall default, whether to evaluate arguments, and which
    arguments should use inheritance.}
}
\details{
  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
  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
  account just as they would be in dispatching a method for the
  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}.

  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}.

  The function \code{getMethods} returns all the methods for a
  particular generic (in the form of a generic function with the
  methods information in its environment).  The function is called
  from the evaluator to merge method information, and is not intended
  to be called directly.

  The function \code{MethodsListSelect} performs a full search
  (including all inheritance and group generic information: see the
  \link{Methods} documentation page for details on how this works).
  The call returns a possibly revised methods list object,
  incorporating any method found as part of the \code{allMethods}
  slot.

  Normally you won't call \code{MethodsListSelect} directly, but it is
  possible to use it for debugging purposes (only for distinctly
  advanced users!).

  Note that the statement that \code{MethodsListSelect} corresponds to the
  selection done by the evaluator is a fact, not an assertion, in the
  sense that the evaluator code constructs and executes a call to
  \code{MethodsListSelect} when it does not already have a cached method
  for this generic function and signature.  (The value returned is
  stored by the evaluator so that the search is not required next
  time.)


}
\value{
  The call to \code{selectMethod} or \code{getMethod} returns a
  \code{\link{MethodDefinition-class}} object, the selected method, if
  a unique selection exists.
  (This class extends \code{function}, so you can use the result
  directly as a function if that is what you want.)
  Otherwise an error is thrown if \code{optional} is \code{FALSE}.  If
  \code{optional} is \code{TRUE}, the value returned is \code{NULL} if
  no method matched, or a \code{MethodsList} object if multiple
  methods matched.

  The call to \code{getMethods} returns the \code{MethodsList} object
  containing all the methods requested.  If there are none,
  \code{NULL} is returned: \code{getMethods} does not generate an
  error in this case.
}
\references{
  The R package \code{methods} implements, with a few exceptions, the
  programming interface for classes
  and methods in the book \emph{Programming with Data} (John
  M. Chambers, Springer, 1998), in particular sections 1.6, 2.7, 2.8,
  and chapters 7 and 8.

  While the programming interface for the methods package follows the reference,
  the R software is an original implementation, so details in
  the reference that reflect the S4 implementation may appear
  differently in R.  Also, there are extensions to the programming
  interface developed more recently than the reference.  For a
  discussion of details and ongoing development, see the web page 
  \url{http://developer.r-project.org/methodsPackage.html} and the
  pointers from that page.
}
\keyword{programming}
\keyword{classes}
\keyword{methods}