\HeaderA{match.call}{Argument Matching}{match.call}
\keyword{programming}{match.call}
\begin{Description}\relax
\code{match.call} returns a call in which all of the specified arguments are
specified by their full names.
\end{Description}
\begin{Usage}
\begin{verbatim}
match.call(definition = NULL, call = sys.call(sys.parent()),
           expand.dots = TRUE)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{definition}] a function, by default the function from which
\code{match.call} is called.  See details.
\item[\code{call}] an unevaluated call to the function specified by
\code{definition}, as generated by \code{\LinkA{call}{call}}.
\item[\code{expand.dots}] logical. Should arguments matching \code{...}
in the call be included or left as a \code{...} argument?
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\sQuote{function} on this help page means an interpreted function
(also known as a \sQuote{closure}):  \code{match.call} does not support
primitive functions (where argument matching is normally
positional).

\code{match.call} is most commonly used in two circumstances:
\Itemize{
\item To record the call for later re-use: for example most
model-fitting functions record the call as element \code{call} of
the list they return.  Here the default \code{expand.dots = TRUE}
is appropriate.

\item To pass most of the call to another function, often
\code{model.frame}.  Here the common idiom is that
\code{expand.dots = FALSE} is used, and the \code{...} elememt
of the matched call is removed.  An alternative is to
explicitly select the arguments to be passed on, as is done in
\code{lm}.
}

Calling \code{match.call} outside a function without specifying
\code{definition} is an error.
\end{Details}
\begin{Value}
An object of class \code{call}.
\end{Value}
\begin{References}\relax
Chambers, J. M. (1998)
\emph{Programming with Data. A Guide to the S Language}.
Springer.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{sys.call}{sys.call}()} is similar, but does \emph{not} expand the
argument names;
\code{\LinkA{call}{call}}, \code{\LinkA{pmatch}{pmatch}}, \code{\LinkA{match.arg}{match.arg}},
\code{\LinkA{match.fun}{match.fun}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
match.call(get, call("get", "abc", i = FALSE, p = 3))
## -> get(x = "abc", pos = 3, inherits = FALSE)
fun <- function(x, lower = 0, upper = 1) {
  structure((x - lower) / (upper - lower), CALL = match.call())
}
fun(4 * atan(1), u = pi)
\end{ExampleCode}
\end{Examples}

