match.call               package:base               R Documentation

Argument Matching

Description:

     'match.call' returns a call in which all of the specified
     arguments are specified by their full names.

Usage:

     match.call(definition = NULL, call = sys.call(sys.parent()),
                expand.dots = TRUE)

Arguments:

definition: a function, by default the function from which 'match.call'
          is called.  See details.

    call: an unevaluated call to the function specified by
          'definition', as generated by 'call'.

expand.dots: logical. Should arguments matching '...' in the call be
          included or left as a '...' argument?

Details:

     'function' on this help page means an interpreted function (also
     known as a 'closure'):  'match.call' does not support primitive
     functions (where argument matching is normally positional).

     'match.call' is most commonly used in two circumstances:

        *  To record the call for later re-use: for example most
           model-fitting functions record the call as element 'call' of
           the list they return.  Here the default 'expand.dots = TRUE'
           is appropriate.

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

     Calling 'match.call' outside a function without specifying
     'definition' is an error.

Value:

     An object of class 'call'.

References:

     Chambers, J. M. (1998) _Programming with Data. A Guide to the S
     Language_. Springer.

See Also:

     'sys.call()' is similar, but does _not_ expand the argument names;
     'call', 'pmatch', 'match.arg', 'match.fun'.

Examples:

     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)

