Skip to contents

Create a specified list stabilizer function

Source: R/specify_lst.R
specify_lst.Rd

specify_lst() creates a function that will call stabilize_lst() with the provided arguments. specify_list() is a synonym of specify_lst().

Usage

specify_lst(
  ...,
  .named = NULL,
  .unnamed = NULL,
  .unique = FALSE,
  .allow_null = TRUE,
  .allow_zero_length = TRUE,
  .min_size = NULL,
  .max_size = NULL,
  .required = ...names()
)

specify_list(
  ...,
  .named = NULL,
  .unnamed = NULL,
  .unique = FALSE,
  .allow_null = TRUE,
  .allow_zero_length = TRUE,
  .min_size = NULL,
  .max_size = NULL,
  .required = ...names()
)

Arguments

...

Named stabilizer functions, such as stabilize_* functions (stabilize_chr(), etc) or functions produced by specify_*() functions (specify_chr(), etc). Each name corresponds to an element in .x, and the function is used to validate that element when present. Whether the element is required (its absence is an error) is controlled by .required.

.named

Controls how named elements of .x that are not explicitly listed in ... are handled. One of:

  • NULL or FALSE (default): any extra named elements cause an error.

  • TRUE: extra named elements are allowed, unchecked.

  • A single stabilizer function, such as a stabilize_* function (stabilize_chr(), etc) or a function produced by a specify_*() function (specify_chr(), etc), used to validate every extra named element.

.unnamed

Controls how unnamed elements of .x are handled. One of:

  • NULL or FALSE (default): any unnamed elements cause an error.

  • TRUE: unnamed elements are allowed, unchecked.

  • A single stabilizer function, such as a stabilize_* function (stabilize_chr(), etc) or a function produced by a specify_*() function (specify_chr(), etc), used to validate every unnamed element.

.unique

(logical(1)) Should all elements in .x be distinct? If TRUE, duplicated elements are rejected.

.allow_null

(logical(1)) Is NULL an acceptable value?

.allow_zero_length

(logical(1)) Are zero-length vectors acceptable?

.min_size

(integer(1)) The minimum size of the object. Object size will be tested using vctrs::vec_size().

.max_size

(integer(1)) The maximum size of the object. Object size will be tested using vctrs::vec_size().

.required

(character) Names (from ...) of elements that must be present in .x. Defaults to all names in ..., so every named spec is required unless you opt it out. Named specs not listed here are optional: if absent, no error is raised; if present, they're validated normally. Pass NULL or character() to make every named spec optional. A zero-length .x (such as list()) skips this check when .allow_zero_length = TRUE.

Value

A function of class "stbl_specified_fn" that calls stabilize_lst() with the provided arguments. The generated function will also accept ... for additional named element specifications to pass to stabilize_lst(). You can copy/paste the body of the resulting function if you want to provide additional context or functionality.

See also

Other list functions: assert_present(), stabilize_lst(), to(), to_lst()

Other specification functions: specify_all_of(), specify_any_of(), specify_chr(), specify_date(), specify_dbl(), specify_df(), specify_dttm(), specify_dur(), specify_each(), specify_fct(), specify_int(), specify_lgl(), specify_one_of(), specify_time()

Examples

stabilize_config <- specify_lst(
  name = specify_chr_scalar(allow_na = FALSE),
  version = stabilize_int_scalar,
  debug = specify_lgl_scalar(allow_na = FALSE),
  .unnamed = stabilize_chr_scalar
)
stabilize_config(list(name = "myapp", version = 1L, debug = FALSE, "extra"))
#> $name
#> [1] "myapp"
#> 
#> $version
#> [1] 1
#> 
#> $debug
#> [1] FALSE
#> 
#> [[4]]
#> [1] "extra"
#> 
try(
  stabilize_config(
    list(name = "myapp", version = 1L, debug = FALSE, c("a", "b"))
  )
)
#> Error in eval(expr, envir) : 
#>   `list(name = "myapp", version = 1L, debug = FALSE, c("a", "b"))[[4]]`
#> must be a single <character>.
#> ✖ `list(name = "myapp", version = 1L, debug = FALSE, c("a", "b"))[[4]]` has 2
#>   values.

# Mark some elements as optional via .required
stabilize_settings <- specify_lst(
  name = specify_chr_scalar(),
  nickname = specify_chr_scalar(),
  .required = "name"
)
stabilize_settings(list(name = "Alice"))
#> $name
#> [1] "Alice"
#>