Skip to contents

Load configuration

Source: R/load_config.R
load_config.Rd

Load a user defined configuration from file. By default (i.e. when as_is = FALSE), load_config() requires inputs to be given as uniquely-named lists. It first parses the configuration file looking for a 'default' entry. With no additional arguments this will be returned as a list to the user. If the user specifies an additional list to consider (via the config argument) then this list is layered on top (using utils::modifyList()).

list_config() returns the names of (possible) configurations within the given file. It corresponds to names(load_config(filename, as_is = TRUE)).

Usage

load_config(filename, config, crates, ..., as_is = FALSE, default = "default")

list_config(filename)

Arguments

filename

Configuration file to read from.

config

If as_is = FALSE, name of entry in configuration file to layer on top of 'default'.

If as_is = TRUE then, if specified, this entry will be selected from the configuration and returned.

crates

A list of carrier::crate objects which are used to inject functions in to the environment where the configuration file will be evaluated.

...

Not currently used.

as_is

Should the configuration file be read in as is, without layering on top of the default config?

Defaults to FALSE.

default

The default configuration to use. Not used if as_is = FALSE.

Value

If as_is = FALSE (default), load_config() returns a list contain entries corresponding to the chosen config.

If as_is = TRUE and no config value specified, a list of all entries in the evaluated configuration file. If a config value is specified, this entry is pulled from the list and returned.

list_config() returns a character vector of (possible) configurations within the given file. It corresponds to names(load_config(filename, as_is = TRUE)).

Details

Configuration files can be specified using a reduced subset of base R. By default this is restricted to the following operators and functions:

We also enable a convenience function, cc, which automatically quotes input to save typing.

Users can also inject their own functions in to the evaluation environment by supplying a list of crates as an additional argument.

Examples

# load the example configuration
file <- system.file("config.R", package = "ronfig")
cat(readChar(file, file.info(file)$size))
#> # This is our default configuration which must be a named list
#> # All other changes are layered on top of this.
#> default <- list(
#>     date = as.Date("2025-09-02"),
#>     N = 1000,
#>     alpha = 0.3,
#>     gamma = 0.2,
#>     beta = 0.7,
#>     max_delay = 30,
#>     years = 2006:2025
#> )
#> 
#> # You may need to debug some results and wish to set one parameter to 0 and only
#> # look at a reduced number of years, e.g.
#> debug <- list(
#>     years = 2024:2025,
#>     alpha = 0
#> )
#> 
#> # Or you may wish to consider an extended range of years
#> forecast <- list(
#>     years = 2006:2030
#> )

# default configuration
str(load_config(file))
#> List of 7
#>  $ date     : Date[1:1], format: "2025-09-02"
#>  $ N        : num 1000
#>  $ alpha    : num 0.3
#>  $ gamma    : num 0.2
#>  $ beta     : num 0.7
#>  $ max_delay: num 30
#>  $ years    : int [1:20] 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 ...

# debug configuration
str(load_config(file, "debug"))
#> List of 7
#>  $ date     : Date[1:1], format: "2025-09-02"
#>  $ N        : num 1000
#>  $ alpha    : num 0
#>  $ gamma    : num 0.2
#>  $ beta     : num 0.7
#>  $ max_delay: num 30
#>  $ years    : int [1:2] 2024 2025

# forecast configuration
str(load_config(file, "forecast"))
#> List of 7
#>  $ date     : Date[1:1], format: "2025-09-02"
#>  $ N        : num 1000
#>  $ alpha    : num 0.3
#>  $ gamma    : num 0.2
#>  $ beta     : num 0.7
#>  $ max_delay: num 30
#>  $ years    : int [1:25] 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 ...

# Injecting crated function
f <- tempfile()
cat("default <- list(a=mean(1:10))", file = f)

# will fail as mean() not available
tryCatch(with(load_config(f), a), error = conditionMessage)
#> [1] "\033[1m\033[22mUnable to load configuration file: could not find function \"mean\"\n\033[36mℹ\033[39m Only the following functions are available to use in rconfig files:\n\033[36m•\033[39m <-, =, +, -, *, :\n\033[36m•\033[39m as.Date\n\033[36m•\033[39m array, matrix\n\033[36m•\033[39m list, data.frame\n\033[36m•\033[39m c, cc\n\033[36m•\033[39m [, [[, $\n\033[36m•\033[39m $<-, [<-\n\033[36m•\033[39m Sys.Date, Sys.time\n\033[36m•\033[39m seq, sequence, seq_len\n\033[36m•\033[39m file.path\n\033[36m•\033[39m modifyList"

# will work if we inject crated mean
crate <- carrier::crate(function(x) mean(x))
with(load_config(f, crates = list(mean = crate)), a)
#> [1] 5.5

unlink(f)