R GenericFunctions 管理通用函数的工具

说明

此处记录的函数管理与通用函数关联的方法集合，并提供有关通用函数本身的信息。

用法

isGeneric(f, where, fdef, getName = FALSE)
isGroup(f, where, fdef)
removeGeneric(f, where)

dumpMethod(f, signature, file, where, def)
findFunction(f, generic = TRUE, where = topenv(parent.frame()))
dumpMethods(f, file, signature, methods, where)
signature(...)

removeMethods(f, where = topenv(parent.frame()), all = missing(where))

setReplaceMethod(f, ..., where = topenv(parent.frame()))

getGenerics(where, searchForm = FALSE)

参数

f	命名函数的字符串。
where	从中搜索对象的环境、名称空间或搜索列表位置。默认情况下，从调用函数的顶级环境开始，通常是全局环境(即使用搜索列表)或调用所在包的命名空间。间接调用任何这些函数时提供此参数非常重要。对于包命名空间，此类调用中的默认值可能是错误的。
signature	相关方法的类签名。签名是命名或未命名的字符串向量。如果命名，则名称必须是通用函数的形式参数名称。签名与通用函数的签名槽中指定的参数相匹配(请参阅 setMethod 文档的详细信息部分)。 dumpMethods 的 signature 参数被忽略(它在以前的实现中内部使用)。
file	转储方法定义的文件或连接。
def	定义方法的函数对象；如果省略，则为与签名对应的当前方法定义。
...	用于生成签名的命名或未命名参数。
generic	在测试或查找函数时，是否应该包括通用函数。提供为 FALSE 以仅获取非泛型函数。
fdef	可选，通用函数定义。 通常在 isGeneric 调用中省略
getName	如果 TRUE ，isGeneric 返回泛型的名称。默认情况下，它返回 TRUE 。
methods	包含要转储的方法的方法对象。默认情况下，为此泛型定义的方法(可以选择在指定的 where 位置)。
all	在 removeMethods 中，逻辑指示是否应删除所有(默认)或仅找到的第一个方法。
searchForm	在 getGenerics 中，如果 TRUE ，则返回结果的 package 槽采用 search() 使用的形式，否则为简单包名称(例如 "package:base" 与 "base" )。

函数概要

isGeneric：

是否有一个名为 f 的函数，如果有，它是一个泛型函数吗？

getName 参数允许函数从函数定义中查找名称。如果是TRUE，则返回泛型的名称；如果不是泛型函数定义，则返回FALSE。

原语函数的 isGeneric 和 getGeneric 的行为略有不同。这些函数并不作为正式函数对象存在(出于效率和历史原因)，无论是否为它们定义了方法。对 isGeneric 的调用会告诉您是否已为此原始函数定义了方法、当前搜索列表中的任何位置或指定位置 where 。相反，对 getGeneric 的调用将返回该函数的泛型，即使当前尚未为其定义任何方法。

removeGeneric、removeMethods：

删除该名称的通用函数的所有方法。另外，removeGeneric 删除了函数本身； removeMethods 恢复非泛型函数，这是默认方法。如果没有默认方法，removeMethods 会留下一个没有方法的泛型函数。

standardGeneric：

从通用函数 f 的当前函数调用中调度一个方法。在相应通用函数体之外的任何地方调用 standardGeneric 都是错误的。

请注意，出于效率原因，standardGeneric 是 base 包中的原始函数，但在此处自然地记录了它。

dumpMethod：

转储此通用函数和签名的方法。

findFunction：

返回搜索列表上的位置列表或当前顶级环境，其中存在 name 的函数对象。返回的值始终是一个列表，使用第一个元素来访问函数的第一个可见版本。请参阅示例。

注意：使用它而不是 find 和 mode="function" ，后者没有那么有意义，并且由于使用正则表达式而存在一些微妙的错误。此外，当通过调用 library 附加包时，findFunction 在包的代码中可以正常工作。

dumpMethods：

转储该泛型的所有方法。

signature：

返回要与泛型函数的参数匹配的类的命名列表。

getGenerics：

返回具有在 where 上定义的方法的通用函数的名称；该参数可以是环境或搜索列表的索引。默认情况下，使用整个搜索列表。

方法定义与包限定符一起存储；例如，函数 "initialize" 的方法可能引用不同包上同名的两个不同函数。方法列表对象对应的包名包含在返回对象的槽package中。返回名称的形式可以是普通名称(例如 "base" )，也可以根据 searchForm 的值采用搜索列表中使用的形式("package:base" )

细节

isGeneric：

如果提供了fdef参数，则将其作为泛型的定义，并测试它是否真的是泛型，并以f作为泛型的名称。 (此参数在 S-Plus 中不可用。)

removeGeneric：

如果提供了where，则只需删除搜索列表中该元素上的版本即可；否则，删除遇到的第一个版本。

standardGeneric：

通用函数通常应该调用 standardGeneric 作为其整个函数体。然而，他们也可以进行任何其他计算。

通常的 setGeneric (直接或通过调用 setMethod )创建一个调用 standardGeneric 的函数。

dumpMethod：

生成的源文件将重新创建该方法。

findFunction：

如果 generic 是 FALSE ，则忽略泛型函数。

dumpMethods：

如果提供signature，则仅转储与此初始签名匹配的方法。 (S-Plus 中没有此函数：如果您想要兼容性，请不要使用它。)

signature：

使用 signature 的优点是可以检查您所指的参数，以及方法规范中更清晰的文档。此外，signature 检查每个元素是否是单个字符串。

removeMethods：

如果 f 是泛型函数，则返回 TRUE，否则返回 FALSE(静默)。

如果有默认方法，该函数将被重新分配为具有此定义的简单函数。否则，通用函数仍然存在，但没有任何方法(因此对它的任何调用都会生成错误)。无论哪种情况，对 setMethod 的以下调用都将始终重新建立与以前相同的通用函数。

例子

require(stats) # for lm

## get the function "myFun" -- throw an error if 0 or > 1 versions visible:
findFuncStrict <- function(fName) {
  allF <- findFunction(fName)
  if(length(allF) == 0)
    stop("No versions of ",fName," visible")
  else if(length(allF) > 1)
    stop(fName," is ambiguous: ", length(allF), " versions")
  else
    get(fName, allF[[1]])
}

try(findFuncStrict("myFun"))# Error: no version
lm <- function(x) x+1
try(findFuncStrict("lm"))#    Error: 2 versions
findFuncStrict("findFuncStrict")# just 1 version
rm(lm)



## method dumping ------------------------------------

setClass("A", slots = c(a="numeric"))
setMethod("plot", "A", function(x,y,...){ cat("A meth\n") })
dumpMethod("plot","A", file="")
## Not run: 
setMethod("plot", "A",
function (x, y, ...)
{
    cat("AAAAA\n")
}
)

## End(Not run)
tmp <- tempfile()
dumpMethod("plot","A", file=tmp)
## now remove, and see if we can parse the dump
stopifnot(removeMethod("plot", "A"))
source(tmp)
stopifnot(is(getMethod("plot", "A"), "MethodDefinition"))

## same with dumpMethods() :
setClass("B", contains="A")
setMethod("plot", "B", function(x,y,...){ cat("B ...\n") })
dumpMethods("plot", file=tmp)
stopifnot(removeMethod("plot", "A"),
          removeMethod("plot", "B"))
source(tmp)
stopifnot(is(getMethod("plot", "A"), "MethodDefinition"),
          is(getMethod("plot", "B"), "MethodDefinition"))

参考

Chambers, John M. (2016) Extending R, Chapman & Hall. (Chapters 9 and 10.)

也可以看看

getMethod(也适用于selectMethod)、setGeneric、setClass、showMethods