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