pkg_config_val: Get package configuration value

In salim-b/pal: Friendly Convenience/Utility Functions

Get package configuration value

Description

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 = utils::packageName(env = parent.frame()),
  default = NULL,
  require = NULL,
  env = parent.frame()
)

Arguments

key	Configuration key name. A character scalar.
pkg	Package name. A character scalar. Defaults to the name of the calling package.
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.

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

Value

An R object.

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

salim-b/pal documentation built on Feb. 28, 2025, 6:51 p.m.