Get package configuration value

Retrieves a package configuration value in a canonical way. The following configuration sources are consulted in descending order and the first hit is returned:

1. The R option <pkg>.<key>.

2. The environment variable R_<PKG>_<KEY>.

3. The ad-hoc default value specified via this function's default argument (NULL means unspecified).

4. The configuration's global default value as specified in the package's configuration metadata (column default_value or default_value_dynamic of <pkg>::pkg_config; NULL means unspecified).

Depending on require, an error is thrown if none of the above sources contain a value.

Usage

pkg_config_val(key, pkg, default = NULL, require = NULL, env = parent.frame())

Arguments

key

Configuration key name. A character scalar.

pkg

Package name. A character scalar.

default

Default value to fall back to if neither the R option <pkg>.<key> nor the environment variable R_<PKG>_<KEY> is set. If NULL, the default value for key in <pkg>::pkg_config will be used (if defined).

require

Whether or not to require that the configuration value is set. If TRUE and no configuration value is set, an error is thrown with instructions on how to provide a value. If NULL, the require value for key in <pkg>::pkg_config will be used (defaults to TRUE).

env

Environment to evaluate default_value_dynamic in, if necessary.

Value

An R object.

Details

This function is intended to be used by package authors who want to expose their package configuration options in a canonical way (as outlined above). For pkg_config_val() to properly work, the configuration metadata must be available in the package's namespace as object pkg_config, which must be a dataframe or tibble with at minimum the columns key (of type character holding the configuration key names) and default_value (of type list holding static default configuration values) or default_value_dynamic (of type character holding R code expressions that evaluate to default configuration values dynamically at access time).

See also

xfun::env_option() for a compatible (albeit less powerful) approach to R option and environment variable coherence.

Other package configuration functions: augment_pkg_config(), has_pkg_config_val(), pkg_config_val_default(), print_pkg_config()

Examples

try(
  pal::pkg_config_val(key = "gen_pkgdown_ref",
                      pkg = "pkgpurl")
)
#> Error in pal::pkg_config_val(key = "gen_pkgdown_ref", pkg = "pkgpurl") : 
#>   Please set the pkgpurl package configuration option gen_pkgdown_ref by either setting the R option pkgpurl.gen_pkgdown_ref or the environment variable
#> `R_PKGPURL_GEN_PKGDOWN_REF`.