getMethod              package:methods              R Documentation

Get or Test for the Definition of a Method

Description:

     The functions 'getMethod' and 'selectMethod' get the definition of
     a particular method; the functions 'existsMethod' and '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 'findMethod' returns the package(s) in
     the search list (or in the packages specified by the '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,
               mlist, fdef)

     findMethod(f, signature, where)

     getMethods(f, where)

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

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

     selectMethod(f, signature, optional = FALSE, useInherited = TRUE,
                  mlist = (if (is.null(fdef)) NULL else
                           getMethodsForDispatch(f, fdef)),
                  fdef = getGeneric(f, !optional), verbose = FALSE)

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

Arguments:

       f: The character-string name of the generic function.

signature: the signature of classes to match to the arguments of 'f'. 
          See the details below.

          For '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, _not_ to the objects supplied in a call
          to the generic function.  (You are not likely to find this
          approach convenient, but it is used internally and is
          marginally more efficient.) 

   where: The position or environment in which to look for the
          method(s):  by default, anywhere in the current search list.

optional: If the selection does not produce a unique result, an error
          is generated, unless this argument is 'TRUE'.  In that case,
          the value returned is either a 'MethodsList' object, if more
          than one method matches this signature, or 'NULL' if no
          method matches.

   mlist: Optionally, the list of methods in which to search.  By
          default, the function finds the methods for the corresponding
          generic function.  To restrict the search to a particular
          package or environment, e.g., supply this argument as
          'getMethodsMetaData(f,where)'.  For 'selectMethod', see the
          discussion of argument 'fdef'. 

    fdef: Optionally, the generic function from which the method is to
          be retrieved. (Unlikely to be used, except internally in the
          package source.)

 verbose: logical indicating if method selection should print some info
          about its progress.

     env: The environment in which argument evaluations are done in
          'MethodsListSelect'.  Currently must be supplied, but should
          usually be 'sys.frame(sys.parent())' when calling the
          function explicitly for debugging purposes.

fEnv, finalDefault, evalArgs, useInherited, resetAllowed: Internal-use
          arguments for the function's environment, the method to use
          as the overall default, whether to evaluate arguments, which
          arguments should use inheritance, and whether the cached
          methods are allowed to be reset.

Details:

     The 'signature' argument specifies classes, in an extended sense,
     corresponding to formal arguments of the generic function. As
     supplied, the argument may be a vector of strings identifying
     classes, and may be named or not.  Names, if supplied, match the
     names of those formal arguments included in the signature of the
     generic.  That signature is normally all the arguments except ....
      However, generic functions can be specified with only a subset of
     the arguments permitted, or with the signature taking the
     arguments in a different order.

     It's a good idea to name the arguments in the signature to avoid
     confusion, if you're dealing with a generic that does something
     special with its signature.   In any case, the elements of the
     signature are matched to the formal signature by the same rules
     used in matching arguments in function calls (see 'match.call').

     The strings in the signature may be class names, '"missing"' or
     '"ANY"'.  See Methods for the meaning of these in method
     selection.  Arguments not supplied in the signature implicitly
     correspond to class '"ANY"'; in particular, giving an empty
     signature means to look for the default method.

     A call to 'getMethod' returns the method for a particular function
     and signature.  As with other 'get' functions, argument 'where'
     controls where the function looks (by default anywhere in the
     search list) and argument 'optional' controls whether the function
     returns 'NULL' or generates an error if the method is not found. 
     The search for the method makes no use of inheritance.

     The function '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 'getMethod', 'selectMethod' returns
     'NULL' or generates an error if the method is not found, depending
     on the argument 'optional'.

     The functions 'existsMethod' and 'hasMethod' return 'TRUE' or
     'FALSE' according to whether a method is found, the first
     corresponding to 'getMethod' (no inheritance) and the second to
     'selectMethod'.

     The function '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.  Note that it gets _all_ the visible methods for
     the specified functions.  If you want only the methods defined
     explicitly in a particular environment, use the function
     'getMethodsMetaData' instead.

     The function 'MethodsListSelect' performs a full search (including
     all inheritance and group generic information: see the 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 'allMethods' slot.

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

     Note that the statement that '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 '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 'selectMethod' or 'getMethod' returns a
     'MethodDefinition-class' object, the selected method, if a unique
     selection exists. (This class extends 'function', so you can use
     the result directly as a function if that is what you want.)
     Otherwise an error is thrown if 'optional' is 'FALSE'.  If
     'optional' is 'TRUE', the value returned is 'NULL' if no method
     matched, or a 'MethodsList' object if multiple methods matched.

     The call to 'getMethods' returns the 'MethodsList' object
     containing all the methods requested.  If there are none, 'NULL'
     is returned: 'getMethods' does not generate an error in this case.

References:

     The R package 'methods' implements, with a few exceptions, the
     programming interface for classes and methods in the book
     _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 see '?Methods' and the links from that
     documentation.

See Also:

     'GenericFunctions'

Examples:

     setGeneric("testFun", function(x)standardGeneric("testFun"))
     setMethod("testFun", "numeric", function(x)x+1)
     hasMethod("testFun", "numeric")
     ## Not run: [1] TRUE
     hasMethod("testFun", "integer") #inherited
     ## Not run: [1] TRUE
     existsMethod("testFun", "integer")
     ## Not run: [1] FALSE
     hasMethod("testFun") # default method
     ## Not run: [1] FALSE
     hasMethod("testFun", "ANY")
     ## Not run: [1] FALSE

