MethodsList             package:methods             R Documentation

_M_e_t_h_o_d_s_L_i_s_t _O_b_j_e_c_t_s

_D_e_s_c_r_i_p_t_i_o_n:

     These functions create and manipulate 'MethodsList' objects, the
     objects formerly used in R to store methods for dispatch.  Use of
     these objects is no longer required, and while not yet formally
     deprecated, will rarely be a good idea.  Where methods dispatch is
     to be studied, see 'selectMethod'.  For computations that iterate
     over methods or over method signatures, see 'findMethods', which
     returns a linearized methods list to hold method definitions,
     usually more convenient for iteration than the recursive
     'MethodsList' objects.

_U_s_a_g_e:

     MethodsList(.ArgName, ...)

     makeMethodsList(object, level=1)

     SignatureMethod(names, signature, definition)

     insertMethod(mlist, signature, args, def, cacheOnly)

     inheritedSubMethodLists(object, thisClass, mlist, ev)

     showMlist(mlist, includeDefs = TRUE, inherited = TRUE,
        classes, useArgNames, printTo = stdout() )

     ## S3 method for class 'MethodsList':
     print(x, ...)

     listFromMlist(mlist, prefix = list(), sigs. = TRUE, methods. = TRUE)

     linearizeMlist(mlist, inherited = TRUE)

     finalDefaultMethod(mlist, fname = "NULL")

     mergeMethods(m1, m2, genericLabel)

     loadMethod(method, fname, envir)

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

_D_e_t_a_i_l_s:



     '_M_e_t_h_o_d_s_L_i_s_t': Create a MethodsList object out of the arguments.

          Conceptually, this object is a named collection of methods to
          be dispatched when the (first) argument in a function call
          matches the class corresponding to one of the names.  A
          final, unnamed element (i.e., with name '""') corresponds to
          the default method.

          The elements can be either a function, or another
          MethodsList.  In the second case, this list implies
          dispatching on the second argument to the function using that
          list, given a selection of this element on the first
          argument.  Thus, method dispatching on an arbitrary number of
          arguments is defined.

          MethodsList objects are used primarily to dispatch OOP-style
          methods and, in R, to emulate S4-style methods.


     '_S_i_g_n_a_t_u_r_e_M_e_t_h_o_d': construct a MethodsList object containing
          (only) this method, corresponding to the signature; i.e.,
          such that 'signature[[1]]' is the match for the first
          argument, 'signature[[2]]' for the second argument, and so
          on.  The string '"missing"' means a match for a missing
          argument, and '"ANY"' means use this as the default setting
          at this level.

          The first argument is the argument names to be used for
          dispatch corresponding to the signatures.


     '_i_n_s_e_r_t_M_e_t_h_o_d': insert the definition 'def' into the MethodsList
          object, 'mlist', corresponding to the signature.  By default,
          insert it in the slot '"methods"', but 'cacheOnly=TRUE'
          inserts it into the '"allMethods"' slot (used for dispatch
          but not saved).


     '_i_n_h_e_r_i_t_e_d_S_u_b_M_e_t_h_o_d_L_i_s_t_s': Utility function to match the object 
          or the class (if the object is 'NULL') to the elements of a
          methods list. Used in finding inherited methods, and not
          meant to be called directly.


     '_s_h_o_w_M_l_i_s_t': Prints the contents of the MethodsList.  If
          'includeDefs' the signatures and the corresponding
          definitions will be printed; otherwise, only the signatures.


     '_l_i_s_t_F_r_o_m_M_l_i_s_t': Undo the recursive nature of the methods list,
          making a list of 'list(sigs,methods)' of function
          definitions, i.e. of matching signatures and methods.
          'prefix' is the partial signature (a named list of classes)
          to be prepended to the signatures in this object.  If 'sigs.'
          or 'methods.' are 'FALSE', the resulting part of the return
          value will be empty.

          A utility function used to iterate over all the individual
          methods in the object, it calls itself recursively.


     '_l_i_n_e_a_r_i_z_e_M_l_i_s_t': Undo the recursive nature of the methods list,
          making a list of function definitions, with the names of the
          list being the corresponding signatures.

          Designed for printing; for looping over the methods, use the
          above 'listFromMlist' instead.


     '_f_i_n_a_l_D_e_f_a_u_l_t_M_e_t_h_o_d': The true default method for the methods list
          object 'mlist' (the method that matches class '"ANY"' for as
          many arguments as are used in methods matching for this
          generic function).  If 'mlist' is null or no matching method
          is found, returns the function called 'fname', or 'NULL' if
          there is no such function.


     '_m_e_r_g_e_M_e_t_h_o_d_s': Merges the methods in the second MethodsList
          object into the first, and returns the merged result.  Called
          from 'getAllMethods'.  For a primitive function,
          'genericLabel' is supplied as the name of the generic.


     '_l_o_a_d_M_e_t_h_o_d': Called, if necessary, just before a call to 'method'
          is dispatched in the frame 'envir'.  The function exists so
          that methods can be defined for special classes of objects. 
          Usually the point is to assign or modify information in the
          frame environment to be used evaluation.  For example, the
          standard class 'MethodDefinition' has a method that stores
          the target and defined signatures in the environment.  Class
          'MethodWithNext' has a method taking account of the mechanism
          for storing the method to be used in a call to
          'callNextMethod'.

          Any methods defined for 'loadMethod' must return the function
          definition to be used for this call; typically, this is just
          the 'method' argument.


     '_M_e_t_h_o_d_s_L_i_s_t_S_e_l_e_c_t' 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.  This search was used by the
          evaluator when methods lists were the metadata for methods
          dispatch.  This function is now deprecated.


_N_o_t_e:

     Note that 'MethodsList' objects represent methods only in the R
     implementation.  You can use them to find or manipulate
     information about methods, but avoid doing so if you want your
     code to port to S-Plus.

_R_e_f_e_r_e_n_c_e_s:

     Chambers, John M. (2008) _Software for Data Analysis: Programming
     with R_ Springer.  (For the R version.)

     Chambers, John M. (1998) _Programming with Data_ Springer (For the
     original S4 version.)