Skip to contents

Defining Options

Source: R/define_option.R
defining_options.Rd

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()

Value

the package options environment

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.

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()
)
#> 
#> quiet = FALSE
#> 
#>   Whether execution should emit console output
#> 
#>   option  : globalenv.quiet
#>   envvar  : R_GLOBALENV_QUIET (evaluated if possible, raw string otherwise)
#>  *default : FALSE
#> 
#> verbose = TRUE
#> 
#>   Whether to use detailed console output (showcasing additional
#>   configuration parameters)
#> 
#>   option  : globalenv.verbose
#>   envvar  : R_GLOBALENV_VERBOSE (TRUE if one of 'TRUE', '1', FALSE otherwise)
#>  *default : TRUE
#> 

define_option(
  "deprecations",
  desc = "Whether deprecation warnings should be suppressed automatically",
  default = FALSE,
  option_name = "MypackageDeprecations",
  envvar_name = "MYPACKAGE_ENVVARS_DEPRECATIONS"
)
#> 
#> quiet = FALSE
#> 
#>   Whether execution should emit console output
#> 
#>   option  : globalenv.quiet
#>   envvar  : R_GLOBALENV_QUIET (evaluated if possible, raw string otherwise)
#>  *default : FALSE
#> 
#> verbose = TRUE
#> 
#>   Whether to use detailed console output (showcasing additional
#>   configuration parameters)
#> 
#>   option  : globalenv.verbose
#>   envvar  : R_GLOBALENV_VERBOSE (TRUE if one of 'TRUE', '1', FALSE otherwise)
#>  *default : TRUE
#> 
#> deprecations = FALSE
#> 
#>   Whether deprecation warnings should be suppressed automatically
#> 
#>   option  : MypackageDeprecations
#>   envvar  : MYPACKAGE_ENVVARS_DEPRECATIONS (evaluated if possible, raw string otherwise)
#>  *default : FALSE
#>