uniset

Package uniset provides an easily accessible, user-friendly text file as settings-file for your R-package.

Description

Package uniset enables any package (the ‘target package’) to provide its users an easily accessible, user-friendly and human readable text file where key=value pairs (used by functions defined in the target package) can be saved.

This settings file lives in a location defined by the user of the target package, and its user-defined values remain unchanged even when the author of the target package is introducing or deleting keys, or when the target package is updated or re-installed.

In order to enable the target package to make use of the functionality offered by package uniset, three files have to be exported by uniset and be placed into the target package.

Installation

Install release version from CRAN via

install.packages("uniset")

Or download from github:

install_github(repo="bpollner/uniset", ref="master")

---

Set up example

We assume that we want to enable a package called dogPack to use the dynamic settings file provided by uniset. In this example, dogPack is the target package, and we want it to live at ~/desktop. First copy the example folder dogPack to your desktop:

library(uniset)
to <- path.expand("~/desktop")
dsource <- paste0(path.package("uniset"), "/examples/dogPack")
file.copy(dsource, to, recursive = TRUE) 
#> [1] TRUE

Generate Files

There are two ways to set up a target package (in our example the package called dogPack) to make use of uniset:

A) Export and Move Files

The package name, the name of the setup-function and a location have to be specified, then a call to uniset_getFiles() creates a folder containing the three required files:

setupFunc <- "dogPack_demo_setup" # the name of the setup-function in our example
uniset_getFiles("dogPack", setupFunc, to)
#> Three files called 
#> 'uniset_globals.R'
#> 'dogPack_settings.R'
#> 'uniset_functions.R'
#> have been written to the folder 
#> '/Users/bernhard/desktop/UnisetFiles_R-pkg_'dogPack''
#> Please move these three files into their resp. target folders 
#> (see ?uniset, or have a look at the content of the three generated files)
#> 
#> Use the function
#> 'autoUpS()' or 'getstn()'
#> inside a function defined in the package 'dogPack' to get the list holding the key=value pairs.

Move files:

• ‘dogPack_settings.R’ into the ‘inst’ folder (create one if not already done) of dogPack.

• ‘uniset_globals’ and ‘uniset_functions.R’ into the ‘R’ folder of dogPack.

B) Write files directly to target package

A call to uniset_copyFilesToPackage() copies the three required files directly into the target package – called dogPack in our example.

path <- paste0(to, "/dogPack")
setupFunc <- "dogPack_demo_setup" # the name of the setup-function in our example
uniset_copyFilesToPackage(path, setupFunc)
#> A file called 'dogPack_settings.R' has been written into the 'inst' folder, 
#> two files called 'uniset_globals.R' and 'uniset_functions.R'
#> have been written into the 'R' folder of the package 'dogPack' at
#> '/Users/bernhard/desktop/dogPack'.
#> 
#> Use the function
#> 'autoUpS()' or 'getstn()'
#> inside a function defined in the package 'dogPack' to get the list holding the key=value pairs.

Please review the file ‘dogPackFunc.R’ in the folder ‘dogPack/R’ that was copied to path.expand("~/desktop") and look at the code of the practical examples that will be executed below.

Go on and read the extended description to deepen your understanding of how uniset works.