Help pages

-- L -- load_config() list_config()

Load configuration

Description

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",
  strict = TRUE
)

list_config(filename, strict = TRUE)

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.
strict	If TRUE then configuration files can be specified using only a reduced subset of base R as well as a handful of other functions. See details for more information.

Details

If strict is TRUE (default), then configuration files can be specified using a reduced subset of base R. By default 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()

• modifyList()

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

If strict is FALSE then the entire base namespace, as well as cc and modifyList are made available.

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

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

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 = function(cnd) cat(conditionMessage(cnd))
)

#> Unable to load configuration file: could not find function "mean"
#> ℹ Only the following functions are available to use in rconfig files:
#> • <-, =, +, -, *, :
#> • as.Date
#> • array, matrix
#> • list, data.frame
#> • c, cc
#> • [, [[, $
#> • $<-, [<-
#> • Sys.Date, Sys.time
#> • seq, sequence, seq_len
#> • file.path
#> • 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)