R: Collect dynamic dots in a list

list2 {rlang} | R Documentation

## Collect dynamic dots in a list

### Description

`list2(...)` is equivalent to `list(...)` with a few additional features, collectively called dynamic dots. While `list2()` hard-code these features, `dots_list()` is a lower-level version that offers more control.

### Usage

    list2(...)

    dots_list(
      ...,
      .named = FALSE,
      .ignore_empty = c("trailing", "none", "all"),
      .preserve_empty = FALSE,
      .homonyms = c("keep", "first", "last", "error"),
      .check_assign = FALSE
    )

### Arguments

`...` | Arguments to collect in a list. These dots are dynamic.
`.named` | If `TRUE`, unnamed inputs are automatically named with `as_label()`. This is equivalent to applying `exprs_auto_name()` on the result. If `FALSE`, unnamed elements are left as is and, if fully unnamed, the list is given minimal names (a vector of `""`). If `NULL`, fully unnamed results are left with `NULL` names.
`.ignore_empty` | Whether to ignore empty arguments. Can be one of `"trailing"`, `"none"`, `"all"`. If `"trailing"`, only the last argument is ignored if it is empty.
`.preserve_empty` | Whether to preserve the empty arguments that were not ignored. If `TRUE`, empty arguments are stored with `missing_arg()` values. If `FALSE` (the default) an error is thrown when an empty argument is detected.
`.homonyms` | How to treat arguments with the same name. The default, `"keep"`, preserves these arguments. Set `.homonyms` to `"first"` to only keep the first occurrences, to `"last"` to keep the last occurrences, and to `"error"` to raise an informative error and indicate what arguments have duplicated names.
`.check_assign` | Whether to check for `<-` calls. When `TRUE` a warning recommends users to use `=` if they meant to match a function parameter or wrap the `<-` call in curly braces otherwise. This ensures assignments are explicit.

### Value

A list containing the `...` inputs.

### Examples

    # Let's create a function that takes a variable number of arguments:
    numeric <- function(...) {
      dots <- list2(...)
      num <- as.numeric(dots)
      set_names(num, names(dots))
    }
    numeric(1, 2, 3)

    # The main difference with list(...) is that list2(...) enables
    # the `!!!` syntax to splice lists:
    x <- list(2, 3)
    numeric(1, !!! x, 4)

    # As well as unquoting of names:
    nm <- "yup!"
    numeric(!!nm := 1)

    # One useful application of splicing is to work around exact and
    # partial matching of arguments. Let's create a function taking
    # named arguments and dots:
    fn <- function(data, ...) {
      list2(...)
    }

    # You normally cannot pass an argument named `data` through the dots
    # as it will match `fn`'s `data` argument. The splicing syntax
    # provides a workaround:
    fn("wrong!", data = letters)  # exact matching of `data`
    fn("wrong!", dat = letters)   # partial matching of `data`
    fn(some_data, !!!list(data = letters))  # no matching

    # Empty arguments trigger an error by default:
    try(fn(, ))

    # You can choose to preserve empty arguments instead:
    list3 <- function(...) dots_list(..., .preserve_empty = TRUE)

    # Note how the last empty argument is still ignored because
    # `.ignore_empty` defaults to "trailing":
    list3(, )

    # The list with preserved empty arguments is equivalent to:
    list(missing_arg())

    # Arguments with duplicated names are kept by default:
    list2(a = 1, a = 2, b = 3, b = 4, 5, 6)

    # Use the `.homonyms` argument to keep only the first of these:
    dots_list(a = 1, a = 2, b = 3, b = 4, 5, 6, .homonyms = "first")

    # Or the last:
    dots_list(a = 1, a = 2, b = 3, b = 4, 5, 6, .homonyms = "last")

    # Or raise an informative error:
    try(dots_list(a = 1, a = 2, b = 3, b = 4, 5, 6, .homonyms = "error"))

    # dots_list() can be configured to warn when a `<-` call is
    # detected:
    my_list <- function(...) dots_list(..., .check_assign = TRUE)
    my_list(a <- 1)

    # There is no warning if the assignment is wrapped in braces.
    # This requires users to be explicit about their intent:
    my_list({ a <- 1 })

[Package rlang version 1.0.2 Index]