The R Project SVN R

  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 \bold{How Methods Work} describes the underlying

  mechanism; \bold{Class Inheritance and Method Selection} provides more

  details on how class definitions determine which methods are used.

  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 \code{"\link{MethodsList}"}, which contains a named

  list of methods (the \code{methods} slot), and the name of one of the

  formal arguments to the function (the \code{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 \code{f} has

  formal arguments \code{x} and \code{y}.  The methods list object for

  that function has the object \code{as.name("x")} as its

  \code{argument} slot.  An element of the methods named \code{"track"}

  is selected if the actual argument corresponding to \code{x} is an

  object of class \code{"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 \code{x} is of class \code{"track"}.  In the second case, the

  new methods list object defines the selection of methods depending on

  the remaining formal arguments, in this example, \code{y}.  The same

  selection process takes place, recursively, using the new methods list.

  Eventually, the selection returns either a function or \code{NULL},

  meaning that no method matched the actual arguments.

  Each method selected corresponds conceptually to a \emph{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 \code{"track"} for \code{x}, finding that the selection was

  another methods list and then selecting class \code{"numeric"} for

  \code{y} would produce a method associated with the signature

  \code{x = "track", y = "numeric"}.

  The actual selection is done recursively, but you can see the methods

  arranged by signature by calling the function

  \code{\link{showMethods}}, and objects with the methods arranged this

  way (in two different forms) are returned by the functions

  \code{\link{listFromMlist}} and \code{\link{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:

  \enumerate{

    \item {Methods list objects for the same function on one or more

      currently attached databases.  These are merged so that methods in

      a database 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

      \code{"ANY"} in the section on \bold{Inheritance}.

    }

    \item {Methods list objects corresponding to the generic function

      itself and to 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 over databases for a particular function, and

  then over the generic and its group generics.

  possible effect.

    \item{Printing}{

      To provide appropriate printing automatically for objects with

      formal class definitions, the methods package overrides

      \code{print.default}, to look for methods for the generic function

      \code{show}, and to use a default method for objects with formal

      class definitions.

      The revised version of \code{print.default} is intended to produce

      identical printing to the original version for any object that

      does \emph{not} have a formally defined class, including honoring

      old-style print methods.  So far, no exceptions are known.

    }

    \item{\code{plot}}{

      A version of the \code{plot} function is included in the current

      methods package, differing from the one in the base package in

      that it has a \code{y} argument (necessary if methods for plot are

      to be defined for the \code{y} data; see the examples for

      \code{\link{setMethod}}).  This version will move into base as

      soon as it is tested.

    }

  }

  primary documentation.

\seealso{

  \code{\link{setClass}}

}