getMethod              package:methods              R Documentation

_G_e_t _t_h_e _D_e_f_i_n_i_t_i_o_n _o_f _a _M_e_t_h_o_d

_D_e_s_c_r_i_p_t_i_o_n:

     A call to `getMethod' returns the method corresponding a
     particular generic function and signature; a call to `findMethod'
     returns the vector of package names in which a matching method is
     found.

     The functions `MethodsListSelect' and `selectMethod' select
     methods using an environment in which arguments to the function
     have been assigned (they differ in the treatment of inheritance). 
     Neither is intended to be called directly, except perhaps in
     debugging.  The function `getMethods' returns all the methods for
     the generic function.

     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.

_U_s_a_g_e:

     getMethod(f, signature=character(), where, optional=FALSE)

     findMethod(f, signature, where)

     getMethods(f, where=-1)

     MethodsListSelect(f, env, mlist, fEnv, finalDefault, evalArgs, useInherited)
     selectMethod(f, signature, optional=FALSE, useInherited, mlist=getMethods(f))

_A_r_g_u_m_e_n_t_s:

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

          In `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.)

signature: The signature of classes to match to the arguments of `f'. 
          The vector of strings for the classes should be named, and
          the names must match formal argument names of `f'.  If not
          named, the signature is assumed to apply to the arguments of
          `f' in order, but note below for `selectMethod'.

          For `selectMethod', the signature can optionally be an
          environment with classes assigned to the names of the
          corresponding arguments.  If the signature is not an
          environment, it must currently be named.

   where: The position or environment in which to look for the method: 
          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: In `selectMethod', the `MethodsList' object can be explicitly
          supplied.  (Unlikely to be used, except in the recursive call
          that finds matches to more than one argument.)

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

_D_e_t_a_i_l_s:

     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 `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 `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.)

     The `selectMethod' function is similar to `MethodsListSelect' (and
     calls it) but differs in that it is intended to be used with
     control over which arguments are allowed to use inheritance.  The
     restriction is needed to make sensible method selection for coerce
     methods (the `as' function).

_V_a_l_u_e:

     The call to `selectMethod' or `getMethod' returns a function
     object, the selected method, if a unique selection exists.
     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.

_A_u_t_h_o_r(_s):

     John Chambers

_R_e_f_e_r_e_n_c_e_s:

     The web page <URL: http://www.omegahat.org/RSMethods/index.html>
     is the primary documentation.

     The functions in this package implement a facility for classes and
     methods as described in Programming with Data (John M. Chambers,
     Springer, 1998).  See this book for further details and examples.

