XXX establishes a common way to store and retrieve values across runs of an R package. This makes it easy to configure a package once for a user and continue to use the same settings afterwards.
A typical use case (inside a package), might look like:
s <- settings("my_settings.rdata")
s$set("a", 1)
s$get("a")
# [1] 1
# New R session
s <- settings("my_settings.rdata")
s$get("a")
# [1] 1
You can also specify an application name, which allows XXX to also look in look in environmental variables (env vars) and R options. Note that settings stored in an env var will always be returned as a string (length 1 character vector).
# These would usually be done outside of R by the user
options(myapp_b = 2)
Sys.setenv("MYAPP_C" = 3)
s <- settings("my_settings.rdata", "myapp")
s$get("b")
# [1] "2"
s$get("c")
# [1] "3"
s$set("b", 1)
s$get("b")
# [1] 2
# Warning message: Setting b found in multiple
# locations: opts, store. Using setting found in opts
XXX offers three on-disk backing stores
-
dcf
, the debian control format, like the packageDESCRIPTION
file, which may only store character vectors of length one -
json
, which may only store atomic vectors and lists of atomic vectors. -
rds
, which may store anything
XXX also offers the transient backing store which does not persist across sessions and may store anything.
If you want to implement another backing store using a different file type, it's fairly straightforward. You just need to implement a reference class with save
, load
, and check_type
functions. See the source code for more details.
Each backing store implements three methods:
-
$set(name, value)
-
$get(name, default)
-
$has_key(name)
As well as looking in the defined backing store, XXX will also look in environmental variables and package options. This is provides a standard way of using these locations across packages, and will hopefully make it easier for users.
To look in these locations, you must also provide an appname
for the backing store. This ensures that each package can have it's own option namespace without worrying about conflicting with values stored by other packages. If the application is called App
and setting is Name
, then XXX will look for the option app_name
(all lower case), and the env var APP_NAME
(all upper case, although this only matters on linux).
If a value is found in multiple locations, XXX will produce a warning, and pick one based in order of environmental variable, global option and setting value. This order may change based on user feedback.