load persistent global preference settings that can be accessed across modules, pipelines, and R sessions.
Usage
global_preferences(
name,
...,
.initial_prefs = list(),
.overwrite = FALSE,
.verbose = FALSE
)
use_global_preferences(name, ...)Arguments
- name
preference name, must contain only letters, digits, underscore, and hyphen, will be coerced to lower case (case-insensitive)
- ..., .initial_prefs
key-value pairs of initial preference values
- .overwrite
whether to overwrite the initial preference values if they exist.
- .verbose
whether to verbose the preferences to be saved; default is false; turn on for debug use
Value
A persistent map, see rds_map
Details
The preferences should not affect how pipeline is working, hence usually stores minor variables such as graphic options. Changing preferences will not invalidate pipeline cache.
Developers should maintain and check the preferences at their own risks. For example, the preferences may not be available. In case of broken files, please use try-catch clause when trying to access the items.
To avoid performance hit, please do not save functions, environments, only
save atomic items within 1 MB. Though not implemented at this moment,
this restriction will be rigidly enforced in the future.
Examples
if( interactive() ) {
# high-level method
get_my_preference <- use_global_preferences(
name = "my_list",
item1 = "A"
)
get_my_preference("item1", "missing")
get_my_preference("item2", "missing")
# Low-level implementation
preference <- global_preferences(
name = "my_list",
item1 = "A"
)
# get items wrapped in tryCatch
get_my_preference <- function(name, default = NULL) {
tryCatch({
preference$get(name, missing_default = default)
}, error = function(e) {
default
})
}
get_my_preference("item1", "missing")
get_my_preference("item2", "missing")
}