% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/match_arg.R
\name{match_arg}
\alias{match_arg}
\title{Argument Verification}
\usage{
match_arg(
  x,
  choices,
  several.ok = FALSE,
  ignore.case = TRUE,
  .context = NULL,
  .arg = rlang::caller_arg(x),
  .call
)
}
\arguments{
\item{x}{a string (or character vector if \code{several.ok = TRUE}) to match against \code{choices}. If \code{NULL}, the first element of \code{choices} is returned.}

\item{choices}{a character vector of valid values.}

\item{several.ok}{\code{logical}; if \code{TRUE}, \code{x} may contain more than one element. Defaults to \code{FALSE}.}

\item{ignore.case}{\code{logical}; if \code{FALSE}, the matching is case sensitive, and if \code{TRUE} (the default), case is ignored.}

\item{.context}{an optional character string providing context for error messages (e.g., a function or object name). Prepended to the error message when supplied before being evaluated by \pkg{cli}.}

\item{.arg}{the name of the argument supplied to \code{x} to appear in error messages. The default is to extract the argument's name using \code{\link[rlang:caller_arg]{rlang::caller_arg()}}. Ignored if \code{.msg} is supplied.}

\item{.call}{the execution environment of a currently running function, e.g. \code{.call = rlang::current_env()}. The corresponding function call is retrieved and mentioned in error messages as the source of the error. Passed to \code{\link[=err]{err()}}. Set to \code{NULL} to omit call information. The default is to search along the call stack for the first user-facing function in another package, if any.}
}
\value{
A character string (or vector, if \code{several.ok = TRUE}) of the matched element(s) from \code{choices}. If there is no match, an error is thrown. When \code{several.ok = TRUE}, no error is thrown if there is at least one match.
}
\description{
An alternative to \code{\link[=match.arg]{match.arg()}} with improved
error messages via \pkg{cli}. Returns the first choice if \code{x} is \code{NULL},
and supports partial matching.
}
\details{
Partial matching is supported via \code{\link[=pmatch]{pmatch()}}. If no match is found, an error is thrown listing the valid \code{choices}.

Checks are run on \code{x} prior to matching: first, \code{\link[=arg_supplied]{arg_supplied()}} is used to check whether \code{x} was supplied; then \code{\link[=arg_string]{arg_string()}} (if \code{several.ok = TRUE}) or \code{\link[=arg_character]{arg_character()}} (if \code{several.ok = FALSE}) is used to check whether \code{x} is a valid string or character vector, respectively.

When \code{ignore.case = TRUE} (the default), an initial case-sensitive match is run, and if any values in \code{x} are unmatched, a second, case-insensitive match is run. When \code{ignore.case = FALSE}, only the first match is run. This ensures that exact matches (on both content and case) are prioritized before case-insensitive matches.
}
\examples{
f <- function(z = NULL) {
  match_arg(z, c("None", "Exact", "Partial"),
            ignore.case = TRUE)
}

try(f())            # "None" (first choice returned)
try(f("partial"))   # "Partial"
try(f("p"))         # "Partial" (partial match)
try(f(c("e", "p"))) # Error: several.ok = FALSE

# several.ok = TRUE
g <- function(z = NULL) {
  match_arg(z, c("None", "Exact", "Partial"),
            several.ok = TRUE)
}

try(g("exact"))               # Error: case not ignored
try(g("Exact"))               # "Exact"
try(g(c("Exact", "Partial"))) # "Exact", "Partial"
try(g(c("Exact", "Wrong")))   # "Exact"
try(g(c("Wrong1", "Wrong2"))) # Error: no match

h <- function(z = NULL) {
  match_arg(z, c("None", "Exact", "Partial"),
            .context = "in {.fun h},")
}

try(h("Wrong")) # Error with context
}
\seealso{
\itemize{
\item \code{\link[=match.arg]{match.arg()}} for the base \R version
\item \code{\link[=pmatch]{pmatch()}} for the function implementing partial string matching
\item \code{\link[=arg_element]{arg_element()}} for a version without type checking and that doesn't support partial matching
\item \code{\link[rlang:arg_match]{rlang::arg_match()}} for a similar \pkg{rlang} function that doesn't support partial matching.
}
}
