Load configuration — load

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

Usage

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

Arguments

filename

Configuration file to read from.

config

Name of entry in configuration file to layer on top of 'default'.

Not used if as_is = TRUE.

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.

Value

If as_is = FALSE (default) a list contain entries corresponding to the chosen config. If as_is = TRUE, a list of all entries in the evaluated configuration file.

Details

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

<-, =, +, -, *, :,
$, [, [[,
$<-, [<-, [[<-,
c(),
as.Date(),
array(), matrix(),
list(), data.frame(),
Sys.Date(), Sys.time().
seq(), sequence(), and seq_len().
file.path()

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"

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