The R Project SVN R

% File src/library/methods/man/implicitGeneric.Rd

% Part of the R package, https://www.R-project.org

% Copyright 1995-2007 R Core Team

% Distributed under GPL 2 or later

\name{implicitGeneric}

\alias{implicitGeneric}

\alias{setGenericImplicit}

\alias{prohibitGeneric}

\alias{registerImplicitGenerics}

\alias{implicit generic}

\title{Manage Implicit Versions of Generic Functions}

\description{

  The implicit generic mechanism stores generic versions of

  functions

  in a table in a package. The package does not want the current

  version of the function to be a generic, however, and retains the

  non-generic version.

  When a call to \code{\link{setMethod}} or

  \code{\link{setGeneric}} creates a generic version for one of these

  functions, the object in the table is used.

  This mechanism is only needed if special arguments were used to

  create the generic; e.g., the \code{signature} or the \code{valueClass}

  options.

    Function \code{implicitGeneric()} returns the implicit

  generic version, \code{setGenericImplicit()} turns a generic implicit,

  \code{prohibitGeneric()} prevents your function from being made

  generic, and \code{registerImplicitGenerics()} saves a set of implicit

  generic definitions in the cached table of the current session.

}

\usage{

implicitGeneric(name, where, generic)

setGenericImplicit(name, where, restore = TRUE)

prohibitGeneric(name, where)

registerImplicitGenerics(what, where)

}

\arguments{

  \item{name}{ Character string name of the function.}

  \item{where}{ Package or environment in which to register the implicit

    generics.  When using the functions from the top level of your own

    package source, this argument should be omitted.}

  \item{generic}{ Obsolete, and likely to be deprecated.}

  \item{restore}{Should the non-generic version of the function be

    restored?.}

  \item{what}{Optional table of

    the implicit generics to register, but nearly always omitted, when

    it defaults to a standard metadata name.}

}

\details{

  Multiple packages may define methods for the same function, to apply

  to classes defined in that package.  Arithmetic and other operators,

  \code{plot()} and many other basic computations are typical

  examples. It's essential that all such packages write methods for

  the \emph{same} definition of the generic function.  So long as that

  generic uses the default choice for signature and other parameters,

  nothing needs to be done.

  If the generic has special properties, these need to be ensured for

  all packages creating methods for it.  The simplest solution is just

  to make the function generic in the package that originally owned

  it.  If for some reason the owner(s) of that package are unwilling

  to do this, the alternative is to define the correct generic,

  save it in a special table and restore the non-generic version by

  calling \code{setGenericImplicit}.

  Note that the package containing the function can define methods for the implicit generic as

  well; when the implicit generic is made a real generic, those methods

  will be included.

  The usual reason for having a

  non-default implicit generic is to provide a non-default signature,

  and the usual reason for \emph{that} is to allow lazy evaluation of

  some arguments.  All arguments in the signature of a

  generic function must be evaluated at the time the function needs to

  select a method.

  In the base function \code{with()} in the example below, evaluation of the argument

  \code{expr} must be delayed; therefore, it is excluded from the signature.

  If you want to completely prohibit anyone from turning your function

  into a generic, call \code{prohibitGeneric()}.

  Function \code{implicitGeneric()} returns the implicit generic

  version of the named function.  If there is no table of these or if

  this function is not in the table, the result of a simple call

  \code{setGeneric(name)} is returned.

}

\section{Implicit Generics for Base Functions}{

Implicit generic versions exist for some functions in the packages

supplied in the distribution of \R itself.  These are stored in the

\sQuote{methods} package itself and will always be available.

As emphasized repeatedly in the documentation,

\code{\link{setGeneric}()} calls for a function in  another package

should never have non-default settings for arguments such as

\code{signature}.

The reasoning applies specially to functions in supplied packages,

since methods for these are likely to exist in multiple packages.

A call to \code{implicitGeneric()} will show the generic version.

}

\value{

  Function \code{implicitGeneric()} returns the implicit generic

  definition (and caches that definition the first time if it has to

  construct it).

  The other functions exist for their side effect and return nothing

  useful.

}

\seealso{\code{\link{setGeneric}}}

\examples{

### How we would make the function with() into a generic:

## Since the second argument, 'expr' is used literally, we want

## with() to only have "data" in the signature.

\dontrun{

setGeneric("with", signature = "data")

## Now we could predefine methods for "with" if we wanted to.

## When ready, we store the generic as implicit, and restore the

original

setGenericImplicit("with")

}

implicitGeneric("with")

# (This implicit generic is stored in the 'methods' package.)

}

\keyword{programming}

\keyword{methods}