testInheritedMethods         package:methods         R Documentation

_T_e_s_t _f_o_r _a_n_d _R_e_p_o_r_t _a_b_o_u_t  _S_e_l_e_c_t_i_o_n _o_f _I_n_h_e_r_i_t_e_d _M_e_t_h_o_d_s

_D_e_s_c_r_i_p_t_i_o_n:

     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 _before_ releasing a
     package.

_U_s_a_g_e:

     testInheritedMethods(f, signatures, test = TRUE, virtual = FALSE, groupMethods = TRUE, where = .GlobalEnv)

_A_r_g_u_m_e_n_t_s:

       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. 

signatures: An optional set of subclass signatures to use instead of
          the relevant subclasses computed by 'testInheritedMethods'. 
          See the Details for how this is done.  This argument might be
          supplied after a call with 'test = FALSE', to test selection
          in batches. 

    test: optional flag to control whether method selection is actually
          tested. If 'FALSE', returns just the list of relevant
          signatures for subclasses, without calling '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. 

 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. 

groupMethods: should methods for the group generic function be
          included? 

   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. 

_D_e_t_a_i_l_s:

     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 '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 '"vector"' for some argument, one actual vector
     class is chosen arbitrarily. The case of '"ANY"' is dealt with
     specially, since all classes extend it.  A dummy, nonvirtual
     class, '".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 'selectMethod'. To
     collect information on ambiguous selections,
     'testInheritedMethods' establishes a calling handler for the
     special signal '"ambiguousMethodSelection"', by setting the
     corresponding option.

_V_a_l_u_e:

     An object of class '"methodSelectionReport"'.  The details of this
     class are currently subject to change.  It has slots '"target"',
     '"selected"', '"candidates"', and '"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 '"generic"', the name of the generic function, and
     '"allSelections"',  giving the vector of labels for all the
     signatures tested.

_R_e_f_e_r_e_n_c_e_s:

     Chambers, John M. (2008) _Software for Data Analysis: Programming
     with R_ Springer.  (Section 10.6 for basics of method selection.)

     Chambers, John M.(2009) _Class Inheritance in R_ <URL:
     http://stat.stanford.edu/~jmc4/classInheritance.pdf> (to be
     submitted to the R Journal).

_E_x_a_m_p_l_e_s:

     ## 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("+")

