| % File src/library/methods/man/setGeneric.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2016 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{setGeneric} |
| \alias{setGeneric} |
| \title{Create a Generic Version of a Function} |
| \description{ |
| Create a generic version of the named function so that methods may |
| be defined for it. A call to \code{\link{setMethod}} will call |
| \code{setGeneric} automatically if applied to a non-generic |
| function. |
| |
| An explicit call to \code{setGeneric} is usually not required, but |
| doesn't hurt and makes explicit that methods are being defined for a |
| non-generic function. |
| |
| Standard calls will be of the form: |
| |
| \code{setGeneric(name)} |
| |
| where \code{name} specifies an existing function, possibly in another |
| package. An alternative when creating a new generic function in this package is: |
| |
| \code{setGeneric(name, def)} |
| |
| where the function definition \code{def} specifies the formal |
| arguments and becomes the default method. |
| |
| } |
| \usage{ |
| setGeneric(name, def= , group=list(), valueClass=character(), |
| where= , package= , signature= , useAsDefault= , |
| genericFunction= , simpleInheritanceOnly = ) |
| } |
| \arguments{ |
| \item{name}{ The character string name of the generic function. |
| } |
| \item{def}{An optional function object, defining the non-generic |
| version, to become the default method. This is equivalent in |
| effect to assigning \code{def} as the function and then using |
| the one-argument call to \code{setGeneric}. |
| |
| \emph{The following arguments are specialized, optionally used |
| when creating a new generic function with non-standard |
| features. They should not be used when the non-generic is in |
| another package.} |
| |
| } |
| \item{group}{ The name of the group |
| generic function to which this function belongs. See |
| \link{Methods_Details} for details of group generic functions in method |
| selection and \link{S4groupGeneric} for existing groups. |
| } |
| \item{valueClass}{ A character vector specifying one or more class |
| names. The value returned by the generic function must |
| have (or extend) this class, or one of the classes; otherwise, |
| an error is generated. |
| } |
| \item{signature}{ |
| The vector of names from among the formal arguments to |
| the function, that will be allowed in the signature of methods for this |
| function, in calls to \code{\link{setMethod}}. By default and |
| usually, this will be all formal arguments except \code{\dots}. |
| |
| A non-standard signature for the generic function may be |
| used to exclude arguments that take advantage of lazy evaluation; |
| in particular, if the argument may \emph{not} be evaluated then it |
| cannot be part of the signature. |
| |
| While \code{\dots} cannot be used as part of a general signature, |
| it is possible to have this as the \emph{only} element of the |
| signature. |
| Methods will then be selected if their signature matches |
| all the \code{\dots} arguments. See the documentation for topic |
| \link{dotsMethods} for details. It is not |
| possible to mix \code{\dots} and other arguments in the signature. |
| |
| It's usually a mistake to omit arguments from the signature in the |
| belief that this improves efficiency. For method selection, the |
| arguments that are used in the signatures for the \emph{methods} |
| are what counts, and then only seriously on the first call to the |
| function with that combination of classes. |
| } |
| \item{simpleInheritanceOnly}{ |
| Supply this argument as \code{TRUE} to require that methods selected |
| be inherited through simple inheritance only; that is, from |
| superclasses specified in the \code{contains=} argument to |
| \code{\link{setClass}}, or by simple inheritance to a class union or |
| other virtual class. Generic functions should require simple |
| inheritance if they need to be assured that they get the complete |
| original object, not one that has been transformed. Examples of |
| functions requiring simple inheritance are \code{\link{initialize}}, |
| because by definition it must return an object from the same class |
| as its argument, and \code{\link{show}}, because it claims to give a |
| full description of the object provided as its argument. |
| |
| } |
| \item{useAsDefault}{ |
| Override the usual default method mechanism. Only relevant when |
| defining a nonstandard generic function. |
| See the section \sQuote{Specialized Local Generics}. |
| |
| \emph{The remaining arguments are obsolete for normal applications.} |
| } |
| \item{package}{ The name of the package with which this function is |
| associated. Should be determined automatically from the |
| non-generic version. |
| |
| } |
| \item{where}{ Where to store the resulting objects as side effects. |
| The default, to store in the package's namespace, is the only |
| safe choice. |
| } |
| \item{genericFunction}{Obsolete.} |
| } |
| \section{Basic Use}{ |
| The \code{setGeneric} function is called to initialize a generic |
| function as preparation for defining some methods for that function. |
| |
| The simplest and most common situation is that \code{name} specifies |
| an existing function, usually in another package. You now want to |
| define methods for this function. In this case you should |
| supply only \code{name}, for example: |
| |
| \code{setGeneric("colSums")} |
| |
| There must be an existing function of this name (in this case in |
| package \code{"base"}). The non-generic function can be in the same |
| package as the call, typically the case when you are creating a new |
| function plus methods for it. When the function is in |
| another package, it must be available by name, for |
| example through an \code{importFrom()} directive in this package's |
| \code{NAMESPACE} file. Not required for functions in \code{"base"}, |
| which are implicitly imported. |
| |
| A generic version of |
| the function will be created in the current package. The existing function |
| becomes the default method, and the package slot of the new generic |
| function is set to the location of the original function |
| (\code{"base"} in the example). |
| |
| Two special types of non-generic should be noted. |
| Functions that dispatch S3 methods by calling |
| \code{\link{UseMethod}} are ordinary functions, not objects from the |
| \code{"genericFunction"} class. They are made generic like any |
| other function, but some special considerations apply to ensure that |
| S4 and S3 method dispatch is consistent (see \link{Methods_for_S3}). |
| |
| Primitive functions are handled in C code and don't exist as normal |
| functions. |
| A call to \code{setGeneric} is allowed in the simple form, but no |
| actual generic function object is created. Method dispatch will |
| take place in the C code. See the section on Primitive Functions for |
| more details. |
| |
| It's an important feature that the |
| identical generic function definition is created in every package that |
| uses the same \code{setGeneric()} call. |
| When any of these packages is loaded into an \R session, this |
| function will be added to a table of generic functions, and will |
| contain a methods table of all the available methods for the |
| function. |
| |
| Calling \code{setGeneric()} is not strictly |
| necessary before calling \code{setMethod()}. If |
| the function specified in the call to \code{setMethod} is not generic, |
| \code{setMethod} will execute the call to \code{setGeneric} itself. |
| In the case that the non-generic is in another package, does not |
| dispatch S3 methods and is not a primitive, a message is printed noting the |
| creation of the generic function the first time \code{setMethod} is called. |
| |
| The second common use of \code{setGeneric()} is to create a new |
| generic function, unrelated to any existing function. See the |
| \code{asRObject()} example below. |
| This case can be handled just like the previous examples, with only |
| the difference that the non-generic function exists in the |
| current package. |
| Again, the non-generic version becomes the default method. |
| For clarity it's best for the assignment to immediately precede the |
| call to \code{setGeneric()} in the source code. |
| |
| Exactly the same result can be obtained by supplying the default as |
| the \code{def} argument instead of assigning it. |
| In some applications, there will be no completely general default |
| method. While there is a special mechanism for this (see the |
| \sQuote{Specialized Local Generics} section), the recommendation is to provide a |
| default method that signals an error, but with a message that |
| explains as clearly as you can why a non-default method is needed. |
| |
| } |
| \section{Specialized Local Generics}{ |
| The great majority of calls to \code{setGeneric()} should either |
| have one argument to ensure that an existing function can have |
| methods, or arguments \code{name} and \code{def} to create a new |
| generic function and optionally a default method. |
| |
| It is possible to create generic functions with nonstandard |
| signatures, or functions that do additional computations besides |
| method dispatch or that belong to a group of generic functions. |
| |
| None of these mechanisms should be used with a non-generic function |
| from a \emph{different} package, because the result is to create a |
| generic function that may not be consistent from one package to another. |
| When any such options are used, |
| the new generic function will be assigned with a |
| package slot set to the \emph{current} package, not the one in which |
| the non-generic version of the function is found. |
| |
| There is a mechanism to define a specialized generic version of a |
| non-generic function, the \code{\link{implicitGeneric}} |
| construction. |
| This defines the generic version, but then reverts the function to |
| it non-generic form, saving the implicit generic in a table to be |
| activated when methods are defined. |
| However, the mechanism can only legitimately be used either for a non-generic |
| in the same package or by the \code{"methods"} package itself. |
| And in the first case, there is no compelling reason not to simply |
| make the function generic, with the non-generic as the default |
| method. |
| See \code{\link{implicitGeneric}} for details. |
| |
| The body of a generic function usually does nothing except for |
| dispatching methods by a call to \code{standardGeneric}. Under some |
| circumstances you might just want to do some additional computation in |
| the generic function itself. As long as your function eventually |
| calls \code{standardGeneric} that is permissible. |
| See the example \code{"authorNames"} below. |
| |
| In this case, the \code{def} argument will define the nonstandard |
| generic, not the default method. |
| An existing non-generic of the same name and calling sequence should |
| be pre-assigned. It will become the default method, as usual. |
| (An alternative is the \code{useAsDefault} argument.) |
| |
| By default, the generic function can return any object. If |
| \code{valueClass} is supplied, it should be a vector of class names; |
| the value returned by a method is then required to satisfy |
| \code{is(object, Class)} for one of the specified classes. An empty |
| (i.e., zero length) vector of classes means anything is allowed. Note |
| that more complicated requirements on the result can be specified |
| explicitly, by defining a non-standard generic function. |
| |
| If the \code{def} argument calls \code{standardGeneric()} (with or |
| without additional computations) and there is no existing |
| non-generic version of the function, the generic is created without |
| a default method. This is not usually a good idea: better to have a |
| default method that signals an error with a message explaining why |
| the default case is not defined. |
| |
| A new generic function can be created belonging to an existing group |
| by including the \code{group} argument. The argument list of the |
| new generic must agree with that of the group. See |
| \code{\link{setGroupGeneric}} for defining a new group generic. |
| For the role of group generics in |
| dispatching methods, see \link{GroupGenericFunctions} and section |
| 10.5 of the second reference. |
| |
| |
| } |
| |
| \section{Generic Functions and Primitive Functions}{ |
| A number of the basic \R functions are specially implemented as |
| primitive functions, to be evaluated directly in the underlying C code |
| rather than by evaluating an \R language definition. Most have |
| implicit generics (see \code{\link{implicitGeneric}}), and become |
| generic as soon as methods (including group methods) are defined on |
| them. Others cannot be made generic. |
| |
| |
| Calling \code{setGeneric()} for |
| the primitive functions in the base package differs in that it does not, in fact, |
| generate an explicit generic function. |
| Methods for primitives are selected and dispatched from |
| the internal C code, to satisfy concerns for efficiency. |
| The same is true for a few |
| non-primitive functions that dispatch internally. These include |
| \code{unlist} and \code{as.vector}. |
| |
| Note, that the implementation restrict methods for |
| primitive functions to signatures in which at least one of the classes |
| in the signature is a formal S4 class. |
| Otherwise the internal C code will not look for methods. |
| This is a desirable restriction in principle, since optional |
| packages should not be allowed to change the behavior of basic R |
| computations on existing data types. |
| |
| To see the generic version of a primitive function, use |
| \code{\link{getGeneric}(name)}. The function |
| \code{\link{isGeneric}} will tell you whether methods are defined |
| for the function in the current session. |
| |
| Note that S4 methods can only be set on those primitives which are |
| \sQuote{\link{internal generic}}, plus \code{\%*\%}. |
| } |
| |
| \value{ |
| The \code{setGeneric} function exists for its side effect: saving the |
| generic function to allow methods to be specified later. It returns |
| \code{name}. |
| } |
| \references{ |
| Chambers, John M. (2016) |
| \emph{Extending R}, |
| Chapman & Hall. |
| (Chapters 9 and 10.) |
| |
| Chambers, John M. (2008) |
| \emph{Software for Data Analysis: Programming with R} |
| Springer. (Section 10.5 for some details.) |
| |
| } |
| \examples{ |
| |
| ## Specify that this package will define methods for plot() |
| setGeneric("plot") |
| |
| ## create a new generic function, with a default method |
| setGeneric("props", function(object) attributes(object)) |
| |
| ### A non-standard generic function. It insists that the methods |
| ### return a non-empty character vector (a stronger requirement than |
| ### valueClass = "character" in the call to setGeneric) |
| |
| setGeneric("authorNames", |
| function(text) { |
| value <- standardGeneric("authorNames") |
| if(!(is(value, "character") && any(nchar(value)>0))) |
| stop("authorNames methods must return non-empty strings") |
| value |
| }) |
| |
| ## the asRObject generic function, from package XR |
| ## Its default method just returns object |
| ## See the reference, Chapter 12 for methods |
| |
| setGeneric("asRObject", function(object, evaluator) { |
| object |
| }) |
| |
| |
| \dontshow{ |
| setMethod("authorNames", "character", function(text)text) |
| |
| tryIt <- function(expr) tryCatch(expr, error = function(e) e) |
| stopifnot(identical(authorNames(c("me", "you")), c("me", "you")), |
| is(tryIt(authorNames(character())), "error"), # empty value |
| is(tryIt(authorNames(NULL)), "error")) # no default method |
| } |
| \dontshow{ |
| removeGeneric("authorNames") |
| removeGeneric("props") |
| removeGeneric("asRObject") |
| } |
| } |
| \seealso{ |
| \code{\link{Methods_Details}} and the links there for a general discussion, |
| \code{\link{dotsMethods}} for methods that dispatch on |
| \code{\dots}, and \code{\link{setMethod}} for method definitions. |
| } |
| \keyword{ programming } |
| \keyword{ methods } |
| |
| |
| % The description above is the effect when the package that owns the |
| % non-generic function has not created an implicit generic version. |
| % Otherwise, it is this implicit generic function that is used. See the |
| % section on Implicit Generic Functions below. Either way, the |
| % essential result is that the \emph{same} version of the generic |
| % function will be created each time. |
| |
| % The \code{useAsDefault} argument controls the default method for the |
| % new generic. If not told otherwise, \code{setGeneric} will try to |
| % find a non-generic version of the function to use as a default. So, |
| % if you do have a suitable default method, it is often simpler to first |
| % set this up as a non-generic function, and then use the one-argument |
| % call to \code{setGeneric} at the beginning of this section. See the |
| % first example in the Examples section below. |
| |
| % If you \emph{don't} want the existing function to be taken as default, |
| % supply the argument \code{useAsDefault}. That argument can be the |
| % function you want to be the default method, or \code{FALSE} to force |
| % no default (i.e., to cause an error if there is no direct or inherited |
| % method selected for a call to the function). |