\HeaderA{match.fun}{Function Verification for ``Function Variables''}{match.fun}
\keyword{programming}{match.fun}
\begin{Description}\relax
When called inside functions that take a function as argument, extract
the desired function object while avoiding undesired matching to
objects of other types.
\end{Description}
\begin{Usage}
\begin{verbatim}
match.fun(FUN, descend = TRUE)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{FUN}] item to match as function: a function, symbol or
character string.  See Details.
\item[\code{descend}] logical; control whether to search past non-function
objects.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\code{match.fun} is not intended to be used at the top level since it
will perform matching in the \emph{parent} of the caller.

If \code{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 \code{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 \code{substitute} twice), and if that fails, an error is
declared.

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

This is used in base functions such as \code{\LinkA{apply}{apply}},
\code{\LinkA{lapply}{lapply}}, \code{\LinkA{outer}{outer}}, and \code{\LinkA{sweep}{sweep}}.
\end{Details}
\begin{Value}
A function matching \code{FUN} or an error is generated.
\end{Value}
\begin{Section}{Bugs}
The \code{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 \code{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 namespaces
will help).
\end{Section}
\begin{Author}\relax
Peter Dalgaard and Robert Gentleman, based on an earlier version
by Jonathan Rougier.
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{match.arg}{match.arg}}, \code{\LinkA{get}{get}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
# 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
\end{ExampleCode}
\end{Examples}

