match.fun                package:base                R Documentation

Function Verification for "Function Variables"

Description:

     When called inside functions that take a function as argument,
     extract the desired function object while avoiding undesired
     matching to objects of other types.

Usage:

     match.fun(FUN, descend = TRUE)

Arguments:

     FUN: item to match as function: a function, symbol or character
          string.  See 'Details'.

 descend: logical; control whether to search past non-function objects.

Details:

     'match.fun' is not intended to be used at the top level since it
     will perform matching in the _parent_ of the caller.

     If 'FUN' is a function, it is returned.  If it is a symbol (for
     example, enclosed in backquotes) or a character vector of length
     one, it will be looked up using 'get' in the environment of the
     parent of the caller.  If it is of any other mode, it is attempted
     first to get the argument to the caller as a symbol (using
     'substitute' twice), and if that fails, an error is declared.

     If 'descend = TRUE', 'match.fun' will look past non-function
     objects with the given name; otherwise if 'FUN' points to a
     non-function object then an error is generated.

     This is used in base functions such as 'apply', 'lapply', 'outer',
     and 'sweep'.

Value:

     A function matching 'FUN' or an error is generated.

Bugs:

     The 'descend' argument is a bit of misnomer and probably not
     actually needed by anything.  It may go away in the future.

     It is impossible to fully foolproof this.  If one 'attach'es a
     list or data frame containing a length-one character vector with
     the same name as a function, it may be used (although name spaces
     will help).

Author(s):

     Peter Dalgaard and Robert Gentleman, based on an earlier version
     by Jonathan Rougier.

See Also:

     'match.arg', 'get'

Examples:

     # Same as get("*"):
     match.fun("*")
     # Overwrite outer with a vector
     outer <- 1:5
     ## Not run: 
     match.fun(outer, descend = FALSE) #-> Error:  not a function
     ## End(Not run)
     match.fun(outer) # finds it anyway
     is.function(match.fun("outer")) # as well

