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). If no default value is specified (NULL), an error is thrown.

Usage

pkg_config_val(key, pkg, default = 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).

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`.