R: Argument Matching

match_arg {filesstrings} | R Documentation

## Argument Matching

### Description

Match `arg` against a series of candidate `choices` where `NULL` means take the first one. `arg` matches an element of `choices` if `arg` is a prefix of that element.

### Usage

    match_arg(arg, choices, index = FALSE, several_ok = FALSE,
      ignore_case = FALSE)

### Arguments

`arg` | A character vector (of length one unless `several_ok = TRUE`).
`choices` | A character vector of candidate values.
`index` | Return the index of the match rather than the match itself? Default no.
`several_ok` | Allow `arg` to have length greater than one to match several arguments at once? Default no.
`ignore_case` | Ignore case while matching. Default no. If this is `TRUE`, the returned value is the matched element of `choices` (with its original casing).

### Details

`ERROR`s are thrown when a match is not made and where the match is ambiguous. However, sometimes ambiguities are inevitable. Consider the case where `choices = c("ab", "abc")`, then there's no way to choose `"ab"` because `"ab"` is a prefix for `"ab"` and `"abc"`. If this is the case, you need to provide a full match, i.e. using `arg = "ab"` will get you `"ab"` without an error, however `arg = "a"` will throw an ambiguity error.

This function inspired by `RSAGA::match.arg.ext()`. Its behaviour is almost identical (the difference is that `RSAGA::match.arg.ext(..., ignore.case = TRUE)` guarantees that the function returns strings in all lower case, but that is not so with `filesstrings::match_arg(..., ignore_case = TRUE)`) but `RSAGA` is a heavy package to depend upon so `filesstrings::match_arg()` might be handy for package developers.

### Examples

    choices <- c("Apples", "Pears", "Bananas", "Oranges")
    match_arg(NULL, choices)
    match_arg("A", choices)
    match_arg("B", choices, index = TRUE)
    match_arg(c("a", "b"), choices, several_ok = TRUE, ignore_case = TRUE)
    match_arg(c("b", "a"), choices, ignore_case = TRUE, index = TRUE,
              several_ok = TRUE)

[Package filesstrings version 2.5.0 Index]