Check required values for options

Individual session check function that inspects the options. Session checkers can produce errors, warnings, or messages if requested.

Usage

check_required_options(
  action = "warn",
  required_options = NULL,
  action_on_pass = "none"
)

Arguments

action

Behavior to take if the status is not clean. Possible values are "error", "warn", "message", and "none". The default is action = "warn".

required_options

A named list of required options. If any of these options are missing or have different values to the required values, an action is triggered. The default is required_options = NULL, which means there is nothing to compare against, so the check always passes.

action_on_pass

Behavior to take if the status is clean. Possible values are "message" and "none". The default is action_on_pass = "none".

Value

Invisibly returns an object of class sessioncheck_status.

See also

check_attached_packages(), check_loaded_namespaces(), check_globalenv_objects(), check_attached_environments(), check_sessiontime(), check_required_locale(), check_required_sysenv(), check_working_directory()

Examples

check_required_options(action = "message", required_options = list(scipen = 0L, max.print = 50L))
#> ✖ Unexpected options:
#>     max.print: expected 50, got 99999

# a required option that is present, but has a different value: reports
# the expected and actual values
old <- options(scipen = 0L)
check_required_options(action = "message", required_options = list(scipen = 100L))
#> ✖ Unexpected options:
#>     scipen: expected 100, got 0
options(old)

# a required option that is not set at all: reported as missing, rather
# than lumped in with the mismatched-value case above
check_required_options(
  action = "message",
  required_options = list(a_totally_unset_option = TRUE)
)
#> ✖ Unexpected options:
#>     a_totally_unset_option: missing (expected TRUE)

# a long vector value is summarized rather than printed in full
old <- options(scipen = 0L)
check_required_options(action = "message", required_options = list(scipen = 1:5000))
#> ✖ Unexpected options:
#>     scipen: expected c(1, 2, 3, 4, 5, ... [5000 total]), got 0
options(old)

# non-atomic values (e.g. lists) are described by role -- "user-supplied"
# vs. "a different" -- rather than by content, since two unequal lists
# would otherwise both print as the uninformative "<list>"
old <- options(sessioncheck_example = list(a = 1))
check_required_options(
  action = "message",
  required_options = list(sessioncheck_example = list(b = 2))
)
#> ✖ Unexpected options:
#>     sessioncheck_example: expected user-supplied <list>, got a different <list>
options(old)

# a required option matching its current value: `action` only controls
# what happens when a problem *is* found, so use
# `action_on_pass = "message"` to confirm the clean result instead
check_required_options(
  action = "none",
  required_options = list(digits = getOption("digits")),
  action_on_pass = "message"
)
#> ✔ No unexpected options detected