options (version 0.3.0)

opt: Inspecting Option Values

Description

Inspecting Option Values

Usage

opt(x, default, env = parent.frame(), ...)
opt_set(x, value, env = parent.frame(), ...)
opt(x, ...) <- value
opt_source(x, env = parent.frame())
opts(xs = NULL, env = parent.frame())
opt_set_local(
  x,
  value,
  env = parent.frame(),
  ...,
  add = TRUE,
  after = FALSE,
  scope = parent.frame()
)
opts_list(
  ...,
  env = parent.frame(),
  check_names = c("asis", "warn", "error"),
  opts = list(...)
)

Value

For opt() and opts(); the result of the option (or a list of results), either the value from a global option, the result of processing the environment variable or the default value, depending on which of the alternative sources are defined.

For modifying functions (opt_set and opt<-: the value of the option prior to modification

For opt_source; the source that is used for a specific option, one of "option", "envvar" or "default".

Arguments

x, xs

An option name, vector of option names, or a named list of new option values

default

A default value if the option is not set

env

An environment, namespace or package name to pull options from

...

See specific functions to see behavior.

value

A new value to update the associated global option

add, after, scope

Passed to on.exit, with alternative defaults. scope is passed to the on.exit envir parameter to disambiguate it from env.

check_names

(experimental) A behavior used when checking option names against specified options. Expects one of "asis", "warn" or "stop".

opts

A list of values, for use in functions that accept ... arguments. In rare cases where your argument names conflict with other named arguments to these functions, you can specify them directly using this parameter.

Functions

• opt(): Retrieve an option. Additional ... arguments passed to an optional option_fn. See option_spec() for details.

• opt_set(): Set an option's value. Additional ... arguments passed to get_option_spec().

• opt(x, ...) <- value: An alias for opt_set()

• opt_source(): Determine source of option value. Primarily used for diagnosing options behaviors.

• opts(): Retrieve multiple options. When no names are provided, return a list containing all options from a given environment. Accepts a character vector of option names or a named list of new values to modify global option values.

• opt_set_local(): Set an option only in the local frame. Additional ... arguments passed to on.exit().

• opts_list(): Produce a named list of namespaced option values, for use with options() and withr. Additional ... arguments used to provide named option values.

Examples

define_options("Whether execution should emit console output", quiet = FALSE)
opt("quiet")

define_options("Whether execution should emit console output", quiet = FALSE)
opt_source("quiet")

Sys.setenv(R_GLOBALENV_QUIET = TRUE)
opt_source("quiet")

options(globalenv.quiet = FALSE)
opt_source("quiet")

define_options("Quietly", quiet = TRUE, "Verbosity", verbose = FALSE)

# retrieve multiple options
opts(c("quiet", "verbose"))

# update multiple options, returns unmodified values
opts(list(quiet = 42, verbose = TRUE))

# next time we check their values we'll see the modified values
opts(c("quiet", "verbose"))

define_options("print quietly", quiet = TRUE)

print.example <- function(x, ...) if (!opt("quiet")) NextMethod()
example <- structure("Hello, World!", class = "example")
print(example)

# using base R options to manage temporary options
orig_opts <- options(opts_list(quiet = FALSE))
print(example)
options(orig_opts)

# using `withr` to manage temporary options
withr::with_options(opts_list(quiet = FALSE), print(example))