| % File src/library/methods/man/RMethodUtils.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2015 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{RMethodUtils} |
| \title{Method Utilities} |
| %% FIXME: undocumented utilities (Sep. 23/02) |
| \alias{asMethodDefinition} |
| \alias{standardGeneric-class} |
| \alias{standardGenericWithTrace-class} |
| \alias{nonstandardGeneric-class} |
| \alias{nonstandardGenericFunction-class} |
| \alias{nonstandardGroupGenericFunction-class} |
| \alias{OptionalFunction-class} |
| \alias{PossibleMethod-class} |
| \alias{optionalMethod-class} |
| \alias{derivedDefaultMethod-class} |
| \alias{internalDispatchMethod-class} |
| %% |
| \alias{substituteFunctionArgs} |
| \alias{makeGeneric} |
| \alias{makeStandardGeneric} |
| \alias{generic.skeleton} |
| \alias{defaultDumpName} |
| \alias{doPrimitiveMethod} |
| \alias{conformMethod} |
| \alias{getGeneric} |
| \alias{getGroup} |
| \alias{getGroupMembers} |
| \alias{getMethodsMetaData} |
| \alias{assignMethodsMetaData} |
| \alias{matchSignature} |
| \alias{findUnique} |
| \alias{MethodAddCoerce} |
| \alias{.saveImage} |
| \alias{cacheMetaData} |
| \alias{cacheGenericsMetaData} |
| \alias{setPrimitiveMethods} |
| \alias{missingArg} |
| \alias{balanceMethodsList} |
| \alias{sigToEnv} |
| \alias{rematchDefinition} |
| \alias{isRematched} |
| \alias{unRematchDefinition} |
| \alias{addNextMethod,MethodDefinition-method} |
| \alias{addNextMethod,MethodWithNext-method} |
| \alias{addNextMethod} |
| \alias{.valueClassTest} |
| \alias{insertClassMethods} |
| %% Not for the user to know about! |
| \alias{.ShortPrimitiveSkeletons} %% used from C code |
| \alias{.EmptyPrimitiveSkeletons} |
| \description{ |
| Utility functions to support the definition and use of formal |
| methods. Most of these functions will not normally be called directly |
| by the user. |
| } |
| \usage{ |
| getGeneric(f, mustFind=FALSE, where, package) |
| |
| getGroup(fdef, recursive, where) |
| getGroupMembers(group, recursive = FALSE, character = TRUE) |
| |
| getMethodsMetaData(f, where) |
| assignMethodsMetaData (f, value, fdef, where) |
| |
| makeGeneric(f, fdef, fdefault =, group=list(), valueClass=character(), |
| package =, signature = NULL, genericFunction = NULL, |
| simpleInheritanceOnly = NULL) |
| |
| makeStandardGeneric(f, fdef) |
| |
| generic.skeleton(name, fdef, fdefault) |
| |
| defaultDumpName(generic, signature) |
| |
| doPrimitiveMethod(name, def, call= sys.call(sys.parent()), |
| ev = sys.frame(sys.parent(2))) |
| |
| conformMethod(signature, mnames, fnames, f= , fdef, method) |
| |
| matchSignature(signature, fun, where) |
| |
| findUnique(what, message, where) |
| |
| MethodAddCoerce(method, argName, thisClass, methodClass) |
| |
| cacheMetaData(where, attach = TRUE, searchWhere = as.environment(where), |
| doCheck = TRUE) |
| |
| cacheGenericsMetaData(f, fdef, attach = TRUE, where, package, methods) |
| |
| setPrimitiveMethods(f, fdef, code, generic, mlist) |
| |
| missingArg(symbol, envir = parent.frame(), eval) |
| |
| sigToEnv(signature, generic) |
| |
| rematchDefinition(definition, generic, mnames, fnames, signature) |
| unRematchDefinition(definition) |
| isRematched(definition) |
| |
| asMethodDefinition(def, signature, sealed = FALSE, fdef) |
| |
| addNextMethod(method, f, mlist, optional, envir) |
| |
| insertClassMethods(methods, Class, value, fieldNames, returnAll) |
| |
| balanceMethodsList(mlist, args, check = TRUE) # <- deprecated since R 3.2.0 |
| } |
| \section{Summary of Functions}{ |
| |
| \describe{ |
| |
| \item{\code{getGeneric}:}{ |
| returns the definition of the function named \code{f} as a generic. |
| |
| If no definition is found, throws an |
| error or returns \code{NULL} according to the value of |
| \code{mustFind}. By default, searches in the top-level |
| environment (normally the global environment, but adjusted to |
| work correctly when package code is evaluated from the function |
| \code{\link{library}}). |
| |
| Primitive functions are dealt with specially, since there is never |
| a formal generic definition for them. The value returned is the |
| formal definition used for assigning methods to this primitive. |
| Not all primitives can have methods; if this one can't, then |
| \code{getGeneric} returns \code{NULL} or throws an error. |
| } |
| |
| \item{\code{getGroup}:}{ |
| returns the groups to which this generic belongs, searching from |
| environment \code{where} (the global environment normally by default). |
| |
| If \code{recursive=TRUE}, also all the group(s) of these groups. |
| } |
| |
| \item{\code{getGroupMembers}:}{ |
| Return all the members of the group generic function named |
| \code{group}. |
| If \code{recursive} is \code{TRUE}, and some members are group |
| generics, includes their members as well. |
| If \code{character} is \code{TRUE}, returns just a character |
| vector of the names; otherwise returns a list, whose elements may |
| (or may not) include either names with a package attribute or |
| actual generic functions. |
| |
| Note that members that are not defined as generic functions will |
| \emph{not} be included in the returned value. To see the raw data, |
| use \code{getGeneric(group)@groupMembers}. |
| } |
| |
| \item{\code{getMethodsMetaData}, |
| \code{assignMethodsMetaData}, |
| \code{mlistMetaName}:}{Utilities to get |
| (\code{getMethodsMetaData}) and assign |
| (\code{assignMethodsMetaData}) the metadata object recording the |
| methods defined in a particular package, or to return the mangled |
| name for that object (\code{mlistMetaName}). |
| |
| The assign function should not be used directly. The get |
| function may be useful if you want explicitly only the outcome of |
| the methods assigned in this package. Otherwise, use |
| \code{\link{getMethods}}. |
| } |
| |
| \item{\code{matchSignature}:}{ |
| Matches the signature object (a partially or completely named |
| subset of the signature arguments of the generic function object |
| \code{fun}), and return a vector of all the classes in the order |
| specified by \code{fun@signature}. The classes not specified by |
| \code{signature} will be \code{"ANY"} in the value, but extra |
| trailing \code{"ANY"}'s are removed. When the input signature is |
| empty, the returned signature is a single \code{"ANY"} matching |
| the first formal argument (so the returned value is always |
| non-empty). |
| |
| Generates an error if any of the supplied signature names are |
| not legal; that is, not in the signature slot of the generic |
| function. |
| |
| If argument \code{where} is supplied, a warning will be issued |
| if any of the classes does not have a formal definition visible |
| from \code{where}. |
| } |
| |
| \item{\code{MethodAddCoerce}:}{ |
| Possibly modify one or more methods to explicitly coerce this |
| argument to \code{methodClass}, the class for which the method is |
| explicitly defined. Only modifies the method if an explicit |
| coerce is required to coerce from \code{thisClass} to |
| \code{methodClass}. |
| } |
| |
| \item{\code{findUnique}:}{ |
| Return the list of environments (or equivalent) having an object named |
| \code{what}, using environment \code{where} and its parent |
| environments. If more than one is found, a warning message is |
| generated, using \code{message} to identify what was being |
| searched for, unless \code{message} is the empty string. |
| } |
| |
| \item{\code{cacheMetaData}, |
| \code{cacheGenericsMetaData}, |
| \code{setPrimitiveMethods}:}{ |
| Utilities for ensuring that the internal information about |
| class and method definitions is up to date. Should normally be |
| called automatically whenever needed (for example, when a method |
| or class definition changes, or when a package is attached or |
| detached). Required primarily because primitive functions are |
| dispatched in C code, rather than by the official model. |
| |
| The \code{setPrimitiveMethods} function resets the caching |
| information for a particular primitive function. Don't call it |
| directly. |
| } |
| |
| \item{\code{missingArg}:}{ |
| Returns \code{TRUE} if the symbol supplied is missing \emph{from |
| the call} corresponding to the environment supplied (by default, |
| environment of the call to \code{missingArg}). If \code{eval} is |
| true, the argument is evaluated to get the name of the symbol to |
| test. Note that \code{missingArg} is closer to the |
| \sQuote{Blue Book} sense of the \code{\link{missing}} function, |
| not that of the current R base package implementation. But beware |
| that it works reliably only if no assignment has yet been made to |
| the argument. (For method dispatch this is fine, because |
| computations are done at the beginning of the call.) |
| } |
| |
| \item{\code{balanceMethodsList}:}{ |
| Used to be called from \code{setMethod()} and is \emph{deprecated} |
| since \R version 3.2.0. |
| %% Called from \code{\link{setMethod}} to ensure that all nodes in |
| %% the list have the same depth (i.e., the same number of levels of |
| %% arguments). Balance is needed to ensure that all necessary |
| %% arguments are examined when inherited methods are being found and |
| %% added to the \code{allMethods} slot. No actual recomputation is |
| %% needed usually except when a new method uses a longer signature |
| %% than has appeared before. |
| |
| %% Balance requires that \emph{all} methods be added to the generic |
| %% via \code{setMethod} (how else could you do it?) or by the initial |
| %% \code{setGeneric} call converting the ordinary function. |
| } |
| |
| \item{\code{sigToEnv}:}{ |
| Turn the signature (a named vector of classes) into an environment |
| with the classes assigned to the names. The environment is then |
| suitable for calling \code{\link{MethodsListSelect}}, with |
| \code{evalArgs=FALSE}, to select a method corresponding to the |
| signature. Usually not called directly: see |
| \code{\link{selectMethod}}. |
| } |
| |
| \item{\code{.saveImage}:}{ |
| Flag, used in dynamically initializing the methods package from |
| \code{.onLoad}. |
| } |
| |
| \item{\code{rematchDefinition}, |
| \code{unRematchDefinition}, |
| \code{isRematched}:}{ |
| If the specified method in a call to \code{\link{setMethod}} |
| specializes the argument list (by replacing \dots), then |
| \code{rematchDefinition} constructs the actual method stored. |
| Using knowledge of how \code{rematchDefinition} works, |
| \code{unRematchDefinition} reverses the procedure; if given a |
| function or method definition that does not correspond to this |
| form, it just returns its argument. \code{isRematched} returns a |
| logical value indicating whether rematching was used when |
| constructing a given method. |
| } |
| |
| \item{\code{asMethodDefinition}:}{ |
| Turn a function definition into an object of class |
| \code{\linkS4class{MethodDefinition}}, corresponding to the |
| given \code{signature} (by default generates a default method |
| with empty signature). The definition is sealed according to |
| the \code{sealed} argument. |
| } |
| |
| \item{\code{addNextMethod}:}{ |
| A generic function that finds the next method for |
| the signature of the method definition \code{method} and caches |
| that method in the method definition (promoting the class to |
| \code{"MethodWithNext"}). Note that argument \code{mlist} is |
| obsolete and not used. |
| } |
| |
| \item{\code{makeGeneric}:}{ |
| Makes a generic function object corresponding to the given |
| function name, optional definition and optional default method. |
| Other arguments supply optional elements for the slots of class |
| \code{\linkS4class{genericFunction}}. |
| } |
| |
| \item{\code{makeStandardGeneric}:}{ |
| a utility function that makes a valid function calling |
| \code{standardGeneric} for name \code{f}. Works (more or less) |
| even if the actual definition, \code{fdef}, is not a proper |
| function, that is, it's a primitive or internal. |
| } |
| |
| \item{\code{conformMethod}:}{ |
| If the formal arguments, \code{mnames}, are not identical to the |
| formal arguments to the function, \code{fnames}, |
| \code{conformMethod} determines whether the signature and the two |
| sets of arguments conform, and returns the signature, possibly |
| extended. The function name, \code{f} is supplied for error |
| messages. The generic function, \code{fdef}, supplies the |
| generic signature for matching purposes. |
| |
| The method assignment conforms if method and generic function have |
| identical formal argument lists. It can also conform if the |
| method omits some of the formal arguments of the function but: (1) |
| the non-omitted arguments are a subset of the function arguments, |
| appearing in the same order; (2) there are no arguments to the |
| method that are not arguments to the function; and (3) the omitted |
| formal arguments do not appear as explicit classes in the |
| signature. A future extension hopes to test also that the |
| omitted arguments are not assumed by being used as locally assigned |
| names or function names in the body of the method. |
| } |
| |
| \item{\code{defaultDumpName}:}{ |
| the default name to be used for dumping a method. |
| } |
| |
| |
| \item{\code{doPrimitiveMethod}:}{ |
| do a primitive call to builtin function \code{name} the definition |
| and call provided, and carried out in the environment \code{ev}. |
| |
| A call to \code{doPrimitiveMethod} is used when the actual method |
| is a .Primitive. (Because primitives don't behave correctly as |
| ordinary functions, not having either formal arguments nor a |
| function body). |
| } |
| |
| } |
| } |
| \seealso{\code{\link{setGeneric}}, \code{\link{setClass}}, |
| \code{\link{showMethods}}. |
| } |
| \examples{ |
| getGroup("exp") |
| getGroup("==", recursive = TRUE) |
| |
| getGroupMembers("Arith") |
| getGroupMembers("Math") |
| getGroupMembers("Ops") # -> its sub groups |
| } |
| \keyword{internal} |