defining_options {options}

Defining Options

Description

Define options which can be used throughout your package.

Usage

define_option(option, ...)

define_options(...)

Arguments

option

An option name to use

...

Additional arguments passed to option_spec()

Details

At their simplest, defining options lets you refer to a global option using a shorthand option name throughout your package, with the added benefit of looking for configurations in global options and environment variables.

Value

the package options environment

Functions

• define_option(): Define an option. Unlike define_options(), this function allows detailed customization of all option behaviors. Accepts either an option_spec() object, or an option named followed by arguments to provide to option_spec().

• define_options(): Define multiple options. This function provides a shorthand syntax for succinctly defining many options. Arguments are defined in groups, each starting with an unnamed description argument. For more details see Section Non-Standard Evaluation.

Non-Standard Evaluation

define_options() accepts arguments in a non-standard way, as groups of arguments which each are used to specify an option (See options_spec()). Groups of arguments must start with an unnamed argument, which provides the description for the argument, followed immediately by a named argument providing the name of option and default value, followed by any additional arguments to provie to options_spec().

The environment in which options are defined is always assumed to be the parent environment. If you'd prefer to specify options in a different environment, this is best done using define_option() or ⁠with(<env>, define_options(...))⁠.

Although define_options() provides all the functionality of define_option() in a succinct shorthand, it is only recommended in cases where the overwhelming majority of your options leverage default behaviors. It is encouraged to use define_option() if you repeatedly need more involved definitions to minimize non-standard evaluation bugs.

Examples

define_options(
  "Whether execution should emit console output",
  quiet = FALSE,
  "Whether to use detailed console output (showcasing additional
  configuration parameters)",
  verbose = TRUE,
  envvar_fn = envvar_is_true()
)

define_option(
  "deprecations",
  desc = "Whether deprecation warnings should be suppressed automatically",
  default = FALSE,
  option_name = "MypackageDeprecations",
  envvar_name = "MYPACKAGE_ENVVARS_DEPRECATIONS"
)