Methods               package:methods               R Documentation

_G_e_n_e_r_a_l _I_n_f_o_r_m_a_t_i_o_n _o_n _M_e_t_h_o_d_s

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

     This documentation section covers some general topics on how
     methods work and how the methods package interacts with the rest
     of R.  The information is usually not needed to get started with
     methods and classes, but may be helpful for moderately ambitious
     projects, or when something doesn't work as expected.

     The section How Methods Work describes the underlying mechanism;
     Class Inheritance and Method Selection provides more details on
     how class definitions determine which methods are used.

     The section Changes with the Methods Package outlines possible
     effects on other computations when running with package `methods'.

_H_o_w _M_e_t_h_o_d_s _W_o_r_k:

     A generic function is a function that has associated with it a
     collection of other functions (the methods), all of which agree in
     formal arguments with the generic.  In R, the ``collection'' is an
     object of class `"MethodsList"', which contains a named list of
     methods (the `methods' slot), and the name of one of the formal
     arguments to the function (the `argument' slot).  The names of the
     methods are the names of classes, and the corresponding element
     defines the method or methods to be used if the corresponding
     argument has that class.  For example, suppose a function `f' has
     formal arguments `x' and `y'.  The methods list object for that
     function has the object `as.name("x")' as its `argument' slot.  An
     element of the methods named `"track"' is selected if the actual
     argument corresponding to `x' is an object of class `"track"'.  If
     there is such an element, it can generally be either a function or
     another methods list object.

     In the first case, the function defines the method to use for any
     call in which `x' is of class `"track"'.  In the second case, the
     new methods list object defines the selection of methods depending
     on the remaining formal arguments, in this example, `y'.  The same
     selection process takes place, recursively, using the new methods
     list. Eventually, the selection returns either a function or
     `NULL', meaning that no method matched the actual arguments.

     Each method selected corresponds conceptually to a signature; that
     is a named list of classes, with names corresponding to some or
     all of the formal arguments.  In the previous example, if
     selecting class `"track"' for `x', finding that the selection was
     another methods list and then selecting class `"numeric"' for `y'
     would produce a method associated with the signature `x = "track",
     y = "numeric"'.

     The actual selection is done recursively, but you can see the
     methods arranged by signature by calling the function
     `showMethods', and objects with the methods arranged this way (in
     two different forms) are returned by the functions `listFromMlist'
     and `linearizeMlist'.

     In an R session, each generic function has a single methods list
     object defining all the currently available methods.  The session
     methods list object is created the first time the function is
     called by merging all the relevant method definitions currently
     visible. Whenever something happens that might change the
     definitions (such as attaching or detaching a package with methods
     for this function, or explicitly defining or removing methods),
     the merged methods list object is removed.  The next call to the
     function will recompute the merged definitions.

     When methods list are merged, they can come from two sources:

        1.  {Methods list objects for the same function anywhere on the
           current search list.  These are merged so that methods in an
           environment earlier in the search list override methods for
           the same function later in the search list. A method
           overrides only another method for the same signature.  See
           the comments on class `"ANY"' in the section on Inheritance.
           }

        2.  {Methods list objects corresponding the group generic
           functions, if any, for this function.  Any generic function
           can be defined to belong to a group generic.  The methods
           for the group generic are available as methods for this
           function.  The group generic can itself be defined as belong
           to a group; as a result there is a list of group generic
           functions.  A method defined for a function and a particular
           signature overrides a method for the same signature for that
           function's group generic. }

     Merging is done first on all methods for a particular function,
     and then over the generic and its group generics.

     The result is a single methods list object that contains all the
     methods directly defined for this function.  As calls to the
     function occur, this information may be supplemented by inherited
     methods, which we consider next.

_C_l_a_s_s _I_n_h_e_r_i_t_a_n_c_e _a_n_d _M_e_t_h_o_d _S_e_l_e_c_t_i_o_n:

     If no method is found directly for the actual arguments in a call
     to a generic function, an attempt is made to match the available
     methods to the arguments by using inheritance.

     Each class definition potentially includes the names of one or
     more classes that the new class extends.  (These are sometimes
     called the superclasses of the new class.)  These classes
     themselves may extend other classes.  Putting all this information
     together produces the full list of superclasses for this class.
     (You can see this list for any class `"A"' from the expression
     `extends("A")'.) In addition, any class implicitly extends class
     `"ANY"'.

     A method will be selected by inheritance if we can find a method
     in the methods list for a signature corresponding to any
     combination of superclasses for each of the relevant arguments.
     The search for such a method is performed by the function
     `MethodsListSelect', working as follows.

     For the first formal argument of the function, a list of classes
     is made up from the class itself, all its superclasses, and class
     `"ANY"'. For each of these, the selection computation looks for an
     element of the methods with the corresponding name.  Each time it
     finds one, it then calls the selection process recursively if
     necessary to select a method directly or by inheritance for the
     remaining arguments.

     Each one of these recursive calls can fail or it can return a
     function (the method).  As long as the calls fail, the selection
     process moves on to the next superclass and tries again. The last
     step corresponds to class `"ANY"', the default method defined at
     this level.

     The effect of this definition of the selection process is to order
     all possible inherited methods, first by the superclasses for the
     first argument, then within this by the superclasses for the
     second argument, and so on. Superclasses are ordered by how direct
     they are:  first, the direct superclasses, then the superclasses
     of these classes.

_C_h_a_n_g_e_s _w_i_t_h _t_h_e _M_e_t_h_o_d_s _P_a_c_k_a_g_e:

     The methods package is designed to leave other computations in R
     unchanged.  There are, however, a few areas where the default
     functions and behavior are overridden when running with the
     methods package attached.  This section outlines those known to
     have some possible effect.


     `_c_l_a_s_s': The methods package enforces the notion that every object
          has a class; in particular, `class(x)' is never `NULL', as it
          would be for basic vectors, for example, when not using
          methods.

          In addition, when assigning a class, the value is required to
          be a single string.  (However, objects can have multiple
          class names if these were generated by old-style class
          computations.  The methods package does not hide the
          ``extra'' class names.)

          Computations using the notion of `NULL' class attributes or
          of class attributes with multiple class names are not really
          compatible with the ideas in the methods package.  Formal
          classes and class inheritance are designed to give more
          flexible and reliable implementations of similar ideas.

          If you do have to mix the two approaches, any operations that
          use class attributes in the old sense should be written in
          terms of `attr(x, "class")', not `class(x)'.  In particular,
          test for no class having been assigned with `is.null(attr(x,
          "class"))'.


     _P_r_i_n_t_i_n_g To provide appropriate printing automatically for objects
          with formal class definitions, the methods package overrides
          `print.default', to look for methods for the generic function
          `show', and to use a default method for objects with formal
          class definitions.

          The revised version of `print.default' is intended to produce
          identical printing to the original version for any object
          that does not have a formally defined class, including
          honoring old-style print methods.  So far, no exceptions are
          known.


     `_p_l_o_t' A version of the `plot' function is included in the current
          methods package, differing from the one in the base package
          in that it has a `y' argument (necessary if methods for plot
          are to be defined for the `y' data; see the examples for
          `setMethod').  This version will move into base as soon as it
          is tested.

_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 emulate the facility for classes and
     methods described in Programming with Data (John M. Chambers,
     Springer, 1998).  See this book for further details and examples.

_S_e_e _A_l_s_o:

     `setGeneric', `setClass'

