R: Extract dots with splicing semantics

dots_list {rlang} | R Documentation

## Extract dots with splicing semantics

### Description

These functions evaluate all arguments contained in `...` and return them as a list. They both splice their arguments if they qualify for splicing. See `ll()` for information about splicing and below for the kind of arguments that qualify for splicing.

### Usage

    dots_list(..., .ignore_empty = c("trailing", "none", "all"))

    dots_splice(..., .ignore_empty = c("trailing", "none", "all"))

### Arguments

`...` | Arguments with explicit (`dots_list()`) or list (`dots_splice()`) splicing semantics. The contents of spliced arguments are embedded in the returned list.
`.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.

### Details

`dots_list()` has explicit splicing semantics: it splices lists that are explicitly marked for splicing with the `splice()` adjective. `dots_splice()` on the other hand has list splicing semantics: in addition to lists marked explicitly for splicing, bare lists are spliced as well.

### Value

A list of arguments. This list is always named: unnamed arguments are named with the empty string `""`.

### See Also

`exprs()` for extracting dots without evaluation.

### Examples

    # Compared to simply using list(...) to capture dots, dots_list()
    # splices explicitly:
    x <- list(1, 2)
    dots_list(!!! x, 3)

    # Unlike dots_splice(), it doesn't splice bare lists:
    dots_list(x, 3)

    # Splicing is also helpful to workaround exact and partial matching
    # of arguments. Let's create a function taking named arguments and
    # dots:
    fn <- function(data, ...) {
      dots_list(...)
    }

    # 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(some_data, !!! list(data = letters))

    # dots_splice() splices lists marked with splice() as well as bare
    # lists:
    x <- list(1, 2)
    dots_splice(!!! x, 3)
    dots_splice(x, 3)

[Package rlang version 0.1.6 Index]