dot_args: Manage '...' arguments
In j-martineau/uj: Utilities by JAM

dot_args

R Documentation

Manage `...` arguments

Description

Enhanced of functions for managing ... arguments.

Usage

dot_args()

d_args()

dot_by_name(.name, .def, ...)

d_by_name(.name, .def, ...)

dots_by_name(.names, .defs, ...)

ds_by_name(.names, .defs, ...)

dot_names(..., .subs = NULL, .req = TRUE)

dnames(..., .subs = NULL, .req = TRUE)

dn(..., .subs = NULL, .req = TRUE)

named_dots(...)

name_ds(...)

anon_dots(...)

anon_ds(...)

named_dot(.n, ...)

named_d(.n, ...)

anon_dot(.n, ...)

anon_d(.n, ...)

flex_dot(.n, ..., .glue = FALSE, .def = "", .d = " ")

flex_d(.n, ..., .glue = FALSE, .def = "", .d = " ")

flex_dots(..., .glue = FALSE, .def = "", .d = " ")

flex_ds(..., .glue = FALSE, .def = "", .d = " ")

glue_dot(..., .n = 1, .def = "", .d = " ")

glue_d(..., .n = 1, .def = "", .d = " ")

glue_dots(..., .def = "", .d = " ")

glue_ds(..., .def = "", .d = " ")

glue_flex_dots(..., .def = "", .d = " ")

glue_flex_ds(..., .def = "", .d = " ")

gf_dots(..., .def = "", .d = " ")

gf_ds(..., .def = "", .d = " ")

gfds(..., .def = "", .d = " ")

glue_flex_dot(..., .n = 1, .def = "", .d = " ")

glue_flex_d(..., .n = 1, .def = "", .d = " ")

gf_dot(..., .n = 1, .def = "", .d = " ")

gfd(..., .n = 1, .def = "", .d = " ")

Arguments

`.name`	`NULL` or complete atomic scalar. `NULL` is replaced with `'NULL'` and `NA` is replaced with `'NA'`.
`.def`	A default object/value to return if a specified argument is not in `...`. For `glue_dots` and `glue_dot`, must be a complete character vec. For all others, may be, but does not need to be, a list.
`...`	An arbitrary number of arguments.
`.names`	`NULL` or an atomic vec (may include `NA` values). Is split along the delimiter `'\|'` to allow for compactness in submitting multiple .names `NULL` will match either an argument in `...` or element of `.defs` with the Name `'NULL'`. `NA` values will match an argument in `...` or an element of `.defs` with the Name `'NA'`.
`.defs`	A named vlist of default objects/values to return if the specified arguments are not in `...`. Elements of `.defs` must be uniquely nameD If `.defs` is a tibble, columns with matching names are returned.
`.subs`	`NULL` or complete character vec. If not `NULL`, it is split using pipes `'\|'` as a delimiter. If there are no pipes contained in `.names`, it remains unchangeD When this argument is not `NULL`, it is substituted for the names of `...` arguments; thus, after splitting, its length must equal the number of `...` arguments. For example, `.names = c('one', 'two', 'three\|four\|five')` indicates that there should be five `...` arguments and the vector `c('one', 'two', 'three', 'four', 'five')` is substituted for their names.
`.req`	`TRUE` or `FALSE` indicating whether names are required.
`.n`	A positive integer indicating which `...` arg to return.
`.glue`	`TRUE` or `FALSE` indicating whether to glue the result (collapse into a character scalar) using the delimiter `.d`.
`.d`	A complete character scalar for collapsing results to a character scalar.

Details

dot_names and dnames are enhancements of ...names that flexibly retrieves names of all ... args by substituting the corresponding value of .subs If a ... arg's name is missing or blank (""), the corresponding value of .names is substituted Throws an error in the following circumstances:

...length() == 0
length(.names) > 0 & length(.names) < ...length()
is.null(.names) & ..bl & any(...names() == "")
is.null(.names) & .req & !any(...names() != "")
is.null(.names) & .u & any(duplicated(...names()))

The remaining functions in this family are as follows:

`⁠dots_by_name, ds_by_name⁠`	Enhancement of `list(...)` that extracts one or more`...` args based on matching values supplied in `.names`. If a supplied Name matches the Name of a `...` arg, that arg is returned. Otherwise, the element of `.defs` with a matching Name is returned. `.names = NULL` and `.names = NA` are converted to `'NULL'` and `'NA'`. Reserved words should be backtick quoted.

`⁠dot_by_name, d_by_name⁠`	Get a single `...` arg by name.

`⁠named_dots, named_ds⁠`	Get a named list containing named `...` arg values.

`⁠named_dot, named_d⁠`	Get the `.n`-th named `...` arg.

`⁠anon_dots, anon_ds⁠`	Get an unnamed list containing unnamed (anonymous) `...` arg values.

`⁠anon_dot, anon_d⁠`	Get the `.n`-th unnamed (anonymous) `...` arg.

`⁠flex_dots, flex_ds⁠`	Retrieve a list of `...length()` elements where the `.n^{th}` element is the flexibly evaluated value of `...elt(.n)`, where flexible evaluation of `...` arg values means that a `...` arg takes on the unadjusted value if forcing evaluation does not generate an error. Otherwise, it takes as its value the string literal representing it in a function call. For example, `f(exactly, 5-2, words)` and `f("exactly", "3", "words")` give identical results in the following circumstances: The usage of `f` is defined as `f(...)`, `f` treats each `...` arg as a flexdot, and in the immediate environment that calls `f(...)` there are no defined objects with the names `exactly` and `words`.

`⁠flex_dot, flex_d⁠`	Get the `.n`-th `...` arg, flexibly evaluated.

`⁠dot_names, dnames, dn⁠`	Get all `...` arg names, substituting names if necessary.

`⁠glue_dots, g_dots, gdots, gds⁠`	Collapse `...` args to a character scalar by calling `paste0(av⁠(...), collapse = .d)⁠`.

`⁠glue_dot, gdot, gd⁠`	Get the `.n`-th `...` arg, glued.

`⁠glue_flex_dots, gf_dots, gfds⁠`	Combo functionality of `glue_dots` and `flex_dots` to glue flexibly evaluated `...` args into a character scalar.

`⁠glue_flex_dot, gf_dot, gfd⁠`	Get the `.n`-th `...` arg, flexibly evaluated and glued.

Value

An object

⁠dot_by_name, d_by_name⁠
⁠named_dot, named_d⁠
⁠anon_dot, anon_d⁠

A list

⁠dots_by_name, ds_by_name⁠
⁠named_dots, named_ds⁠
⁠anon_dots, anon_ds⁠

A character scalar

⁠glue_dots, glue_dot, gdot, gd⁠
⁠glue_flex_dots, gf_dots, gf_dot, gfdot, gfd⁠

A character vector (when .glue = FALSE)

⁠flex_dots, flex_ds⁠
⁠flex_dot, flex_d⁠

A character scalar (when .glue = TRUE)

⁠flex_dots, flex_ds⁠
⁠flex_dot, flex_d⁠

A character vector

⁠dot_names, dnames, dn⁠

Examples

egdot_args <- function(...) {
  nDots <- ...length()
  if (nDots > 1) {
    sub.names <- paste0(letters[1:nDots], LETTERS[1:nDots])
    defaults <- as.list(LETTERS[1:nDots])
    default <- "{missing}"
  } else {
    sub.names <- NULL
    defaults <- "{no Dot args}"
    default <- "{no Dot args}"
  }
  glue.flex.dots <- flex_dots(..., .glue = TRUE, .def = default, .d = "_")
  glue.flex.dot2 <- flex_dot(..., .n = 2, .glue = TRUE)
  subbed.names   <- failsafe(dot_names(..., .subs = sub.names))
  named.dots     <- failsafe(named_dots(...))
  anon.dots      <- failsafe(anon_dots(...))
  dot.names      <- failsafe(dot_names(...))
  flex.dots      <- flex_dots(..., .defs = default)
  flex.dot2      <- flex_dot(..., .n = 2)
  glue.dots      <- failsafe(glue_dots(..., .defs = default))
  gf.dots        <- gf_dots(..., .def = default)
  dots           <- failsafe(dots_by_name(sub.names, defaults, ...))
  dot1           <- failsafe(dot_by_name(sub.names[1], defaults[1], ...))

  list(glue.flex.dots = glue.flex.dots,
       glue.flex.dot2 = glue.flex.dot2,
       subbed.names   = subbed.names ,
       named.dots     = named.dots   ,
       anon.dots      = anon.dots    ,
       dot.names      = dot.names    ,
       flex.dots      = flex.dots    ,
       flex.dot2      = flex.dot2    ,
       glue.dots      = glue.dots    ,
       gf.dots        = gf.dots      ,
       dots           = dots         ,
       dot1           = dot1         )
}

egdot_args(     "a",  b ,      "c",  d ,      "e")
egdot_args(Aa = "a",  b , Cc = "c",  d , Ee = "e")
egdot_args(Aa = "a", "b", Cc = "c", "d", Ee = "e")
egdot_args(letters, digits = 0:9, data.frame(letters, 0:26))

j-martineau/uj documentation built on Sept. 14, 2024, 4:40 a.m.