src/library/methods/man/MethodsList.Rd

% File src/library/methods/man/MethodsList.Rd
% Part of the R package, https://www.R-project.org
% Copyright 1995-2016 R Core Team
% Distributed under GPL 2 or later

\name{MethodsList}
\title{MethodsList Objects}
%
\alias{listFromMlist}%  only used in listFromMlist(), deprecated below
\alias{linearizeMlist}% only used in showMlist(), deprecated below
%
% but finalDefaultMethod() and loadMethod() seem somewhat important :
\alias{finalDefaultMethod}
\alias{loadMethod}
\alias{loadMethod-methods}
\alias{loadMethod,ANY-method}
\alias{loadMethod,MethodDefinition-method}
\alias{loadMethod,MethodWithNext-method}
%% ALl the following are deprecated since R 3.2.0:
\alias{MethodsList}
\alias{makeMethodsList}
\alias{SignatureMethod}
\alias{insertMethod}
\alias{inheritedSubMethodLists}
\alias{showMlist}
\alias{print.MethodsList}
\alias{emptyMethodsList}
\alias{insertMethodInEmptyList}
\alias{mergeMethods}
\alias{MethodsListSelect}
\description{
  These functions create and manipulate \code{MethodsList} objects, the
  objects formerly used in \R to store methods for dispatch.  Use of
  these objects is deprecated since \R 3.2.0, as it will rarely be a
  good idea.  Where methods dispatch is
  to be studied, see \code{\link{selectMethod}}.  For computations
  that iterate over methods or over method signatures, see
  \code{\link{findMethods}}, which returns a linearized methods list
  to hold method definitions, usually more convenient for iteration
  than the recursive \code{MethodsList} objects.
}
\usage{
listFromMlist(mlist, prefix = list(), sigs. = TRUE, methods. = TRUE)

linearizeMlist(mlist, inherited = TRUE)

finalDefaultMethod(method)

loadMethod(method, fname, envir)

##--------- These are all deprecated, since R 3.2.0 ----------

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() )
\method{print}{MethodsList}(x, ...)

mergeMethods(m1, m2, genericLabel)
}

\section{Details}{

  \describe{

    %% \item{\code{MethodsList}:}{
    %%   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 \code{""}) 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.
    %% }

    %% \item{\code{SignatureMethod}:}{
    %%   construct a MethodsList object containing (only) this method,
    %%   corresponding to the signature; i.e., such that
    %%   \code{signature[[1]]} is the match for the first argument,
    %%   \code{signature[[2]]} for the second argument, and so on.  The
    %%   string \code{"missing"} means a match for a missing argument, and
    %%   \code{"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.
    %% }

    %% \item{\code{insertMethod}:}{
    %%   insert the definition \code{def} into the MethodsList object,
    %%   \code{mlist}, corresponding to the signature.  By default, insert
    %%   it in the slot \code{"methods"}, but \code{cacheOnly=TRUE} inserts
    %%   it into the \code{"allMethods"} slot (used for dispatch but not saved).
    %% }

    %% \item{\code{inheritedSubMethodLists}:}{
    %%   Utility function to match the object  or the class (if the object
    %%   is \code{NULL}) to the elements of a methods list.
    %%   Used in finding inherited methods, and not meant to be called
    %%   directly.
    %% }

    %% \item{\code{showMlist}:}{
    %%   Prints the contents of the MethodsList.  If \code{includeDefs} the
    %%   signatures and the corresponding definitions will be printed;
    %%   otherwise, only the signatures.
    %% }

    \item{\code{listFromMlist}:}{
      Undo the recursive nature of the methods list, making a list of
      \code{list(sigs,methods)} of function definitions, i.e.\sspace{}of
      matching signatures and methods.
      \code{prefix} is the partial signature (a named list of classes)
      to be prepended to the signatures in this object.  If \code{sigs.}
      or \code{methods.} are \code{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.
    }

    \item{\code{linearizeMlist}:}{
      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
      \code{listFromMlist} instead.
    }

    \item{\code{finalDefaultMethod}:}{
      The default method or NULL.  With the demise of
      \code{"MethodsList"} objects, this function only checks that the
      value given it is a method definition, primitive or NULL.
    }

    %% \item{\code{mergeMethods}:}{
    %%   Merges the methods in the second MethodsList object into the
    %%   first, and returns the merged result.  Called from
    %%   \code{\link{getAllMethods}}.  For a primitive function,
    %%   \code{genericLabel} is supplied as the name of the generic.
    %% }

    \item{\code{loadMethod}:}{
      Called, if necessary, just before a call to \code{method} is
      dispatched in the frame \code{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 \code{MethodDefinition} has a method that stores the target
      and defined signatures in the environment.  Class
      \code{MethodWithNext} has a method taking account of the
      mechanism for storing the method to be used in a call to
      \code{\link{callNextMethod}}.

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

  %% \item{\code{MethodsListSelect}}{
  %%     The function \code{MethodsListSelect} performs a full search
  %%     (including all inheritance and group generic information: see the
  %%     \link{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 \code{allMethods}
  %%     slot.  This search was used by the evaluator when methods lists
  %%     were the metadata for methods dispatch.  This function is now deprecated.
  %%   }
  }
}
%% \note{
%%   Note that \code{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.
%% }
\references{
 Chambers, John M. (2008)
 \emph{Software for Data Analysis: Programming with R}
  Springer.  (For the R version.)

 Chambers, John M. (1998)
 \emph{Programming with Data}
 Springer (For the original S4 version.)
}
\keyword{internal}