% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/arg.r
\name{match.argv}
\alias{match.argv}
\title{Argument Verification}
\usage{
match.argv(arg, choices, match.fn = NULL)
}
\arguments{
\item{arg}{an \strong{R} object.}

\item{choices}{a list of candidate values to match
against that will be extracted with \code{[[}.}

\item{match.fn}{a function to use for matching the
argument against the choices. This function must
take two arguments: the first is the argument to be
matched, and the second is a candidate value
extracted from \code{choices} with \code{[[}. It must return
a single \code{TRUE} or \code{FALSE} value indicating whether
the argument matches the candidate value.

If \code{NULL}, the default matching function is used,
which checks for equality using\code{identical()} with
\code{ignore.environment = TRUE}.}
}
\value{
If \code{arg} is identical to \code{choices}, then the first
element of \code{arg} is returned. If \code{arg} is matched
against a candidate value in \code{choices}, then \code{arg}
is returned. If no match is found, an error is thrown.
}
\description{
\code{match.argv()} matches a given argument against a
list of candidate values as specified by \code{choices}.
}
\details{
If \code{arg} is the same as \code{choices}, then the first element
of \code{arg} is returned. This check is done using
\code{\link[=identical]{identical()}} with \code{ignore.environment = TRUE}, regardless
of the \code{match.fn} argument.

In the one-argument form \code{match.argv(arg)}, the \code{choices}
are obtained from a default setting for the formal argument
\code{arg} of the function from which \code{match.argv} was called.
}
\examples{
# default matching function is strict.
match.argv(1:10, list(c("a", "b"), list(1, 2), 1:10))
try(match.argv(1, list(c("a", "b"), list(1, 2), 1:10)))

# NULL can be given as a candidate.
match.argv(NULL, list(NULL, 1:10))

# default matching function is strict.
try(match.argv(NA, list(NA_real_, NA_integer_, NA_character_)))

# a custom matching function can be used.
match.argv("A", list("a", "b", "c"), match.fn = function(x, y) {
  is.character(x) && length(x) == 1L && tolower(x) == tolower(y)
})
}
\seealso{
\link{match.arg}, \link{match.call}, \link{match.fun}.
}
