potions (version 0.2.0)

brew: Set up potions for easy data retrieval

Description

Function to place a list into options(), or to update previously-stored data.

Usage

brew(
  ...,
  file,
  .slot,
  .pkg,
  method = c("modify", "merge", "overwrite", "leaves")
)
brew_package(..., file, .pkg, method)
brew_interactive(..., file, .slot, method)

Value

This function never returns an object; it is called for its' side- effect of caching data using options().

Arguments

...

One or named arguments giving attributes to be stored; or alternatively a list containing the same.

file

string: optional file containing data to be stored via options(). Valid formats are .yml or .json.

.slot

string: optional name to mandate where data is stored. Defaults to a random string generated by stringi::stri_rand_strings().

.pkg

string: package name that potions is being used within. Typically only used during onLoad(), after which later calls do not require this argument to be set.

method

string: How should new data be written to options()? See details for specifics.

Details

The default method is to use brew without setting either .pkg or .slot (but not both), and letting potions determine which slot to use. If greater control is needed, you can use brew_package() or brew_interactive(). Note that if neither .slot or .pkg are set, potions defaults to .slot , unless .pkg information has previously been supplied (and .slot information has not). This might be undesirable in a package development situation.

If both ... and file arguments are empty, this function sets up an empty potions object in options("potions-pkg"); See potions-class for more information on this data type. If ... and file arguments are provided, they will be amalgamated using purrr::list_modify(). If there are identical names in both lists, those in ... are chosen.

If the user repeatedly calls brew(), later list entries overwrite early entries. Whole lists are not overwritten unless all top-level entry names match, or method is set to "overwrite", which is a shortcut to using drain() before brew(). The default behaviour is method = "modify", which uses purrr::list_modify() to do the joining. Similarly "merge" uses purrr::list_merge(). method = "leaves" only overwrites terminal nodes, leaving the structure of the list otherwise unaffected. For non-nested lists, this behaviour is identical to "modify", but for nested lists it can be a useful shortcut.

Examples

# basic usage is to pass arguments using `=`
brew(x = 1)

# lists are also permitted
list(x = 2) |> brew()

# as are passing lists as objects
my_list <- list(x = 3)
my_list |> brew()

# or within a function
my_fun <- function(){list(x = 1, y = 2)}
my_fun() |> brew()

# optional clean-up
drain()