Practical Example

In the following examples we will obtain the value from the key ‘favouriteColor’ from the file ‘dogPack.settings.R’.

Initialise Settings File System

Assuming you copied or moved the required files as described before, open the RStudio project file in the folder ’“~/desktop/dogPack”, build and install the package.

# done here for the sake of creating the vignette-output
to <- path.expand("~/desktop")
ptp <- paste0(to, "/dogPack")
devtools::document(ptp, roclets = c('rd', 'collate', 'namespace'), quiet = TRUE)
#> ℹ Loading dogPack
devtools::install(ptp, quiet = TRUE)

Define Location of settings.R File

To define the location of the user-defined settings.R file, use the uniset setup function uniset_setup():

library(dogPack)
dogPack_test_targetPackageParams() # gives a printout of the target package parameters
#> List of 4
#>  $ pkgUniset_UserPackageName         : chr "dogPack"
#>  $ pkgUniset_RenvironSettingsHomeName: chr "dogPack_SH"
#>  $ pkgUniset_SettingsObjectName      : chr "settings"
#>  $ pkgUniset_SuffixForTemplate       : chr "_TEMPLATE"
#> NULL
dogPack_demo_setup(where=to) # will place the settings-home folder on the desktop
#> The folder `dogPack_SH` as settings-home directory has been created in 
#> `/Users/bernhard/desktop`
#> The file 'dogPack_settings.R' has been copied into 
#> '/Users/bernhard/desktop/dogPack_SH'
#> The variable 'dogPack_SH' already existed in the .Renviron file 
#> '/Users/bernhard/.Renviron'
#> 
#> The value of 'dogPack_SH' was correctly set to 
#> '/Users/bernhard/desktop/dogPack_SH'.
#> 
#> Setup successful

dogPack_demo_setup contains the uniset function uniset_setup().

This has to be done only once by the user of the target package. You probably have to restart R now for the changes in the environment variable in your .Renviron file to become effective.

Getting Values

By now everything should be ready and set up. You can look at the settings via

stn <- dogPack_demo_updateSettings()
#> dogPack settings updated
str(stn)
#> List of 25
#>  $ gen_autoUpdateSettings: logi TRUE
#>  $ var1                  : chr "foo"
#>  $ var2                  : logi TRUE
#>  $ var3                  : num 5
#>  $ name                  : chr "Henry"
#>  $ anyName               : chr "anyValue"
#>  $ key1                  : chr "bar"
#>  $ key2                  : num 12345
#>  $ key3                  : chr "theo"
#>  $ xxx                   : logi FALSE
#>  $ abc5                  : logi TRUE
#>  $ favouriteColor        : chr "blue"
#>  $ leastFavColor         : chr "darkred"
#>  $ abc7                  : logi TRUE
#>  $ abc8                  : logi FALSE
#>  $ name_a                : chr "you get the picture"
#>  $ name_b                : logi TRUE
#>  $ name_c                : num 1e+06
#>  $ petterson             : chr "old"
#>  $ findus                : chr "cat"
#>  $ mouse                 : chr "grey"
#>  $ obey                  : logi TRUE
#>  $ consume               : logi TRUE
#>  $ strength              : num 5000
#>  $ last                  : num 0

Use the function getstn defined in package ‘dogPack’ to directly obtain the settings list – see the example code in dogPack_demo_autoUpS and dogPack_demo_tellFavouriteColor in the example folder copied previously.

getstn was customized by package uniset at the time of creating the three required files and is located in the file ‘uniset_functions.R’ in ‘dogPack/R’.

dogPack_demo_tellFavouriteColor()
#> [1] "blue"
# contains the function 'getstn'

Now open the file ‘dogPack_settings.R’ in the folder ‘dogPack_SH’ that was created during setup, and change the value of the key ‘favouriteColor’ to “orange”. After that, call

dogPack_demo_tellFavouriteColor() # should be "orange" now
#> "orange"

Every time one of the functions uniset_updateSettings(), uniset_autoUpS() or uniset_getstn() is called from within the target package, the key = value pairs from the user-defined settings.R file are sourced and returned. However, these functions differ in if they update the keys in the user defined settings.R file or not.
The location of the user-defined settings.R file can be defined via uniset_setup() as shown above.

---

Adding / deleting keys

If you are the developer of package dogPack, at some time after you published dogPack you might want to add keys to or delete from the settings file.

Adding Keys

Do that now: Add e.g. a new ‘key=value,’ pair (do not forget the comma ‘,’) anywhere in the settings-file in the folder ‘inst’ of dogPack, and re-install dogPack. Or, as an alternative shortcut for this demonstration, go to root of the installed dogPack package at

path.package("dogPack")

and there simply modify the file ‘dogPack_settings.R’ (add a key called “someNewKey”).

Now the user of dogPack calls a function that includes the auto-update function uniset::uniset_autoUpS():

dogPack_demo_No_autoUpS()
#> My favourite color is: orange
#> # user defined settings.R file is NOT modified
dogPack_demo_autoUpS()
#>
#> The following 1 key was added to the settings-file 'dogPack_settings.R' in 
#> '/Users/bernhard/desktop/dogPack_SH':
#>  someNewKey
#> 
#> My favourite color is: orange

The user of dogPack will then have the new key added to the local file ‘dogPack_settings.R’ in the folder ‘dogPack_SH’ in the settings-home directory.

Deleting Keys

The same is true for deleting keys: again, open the file ‘dogPack_settings.R’ in the root of path.package("dogPack") and delete the previously added key. Now the user of dogPack calls again a function that includes the auto-update function uniset::uniset_autoUpS():

dogPack_demo_No_autoUpS()
#> My favourite color is: orange
#> # user defined settings.R file is NOT modified
dogPack_demo_autoUpS()
#> 
#> The following 1 key was deleted from the settings-file 'dogPack_settings.R' in 
#> '/Users/bernhard/desktop/dogPack_SH':
#>  someNewKey
#>  
#> My favourite color is: orange

The surplus key was deleted from the local file ‘dogPack_settings.R’.

Practically, it makes sense to include the auto-update in every function that the user of the target package can call, and to not include it in all the other functions.

You might want to read the code in the practical examples in the previously copied file dogPack/R/dogPackFunc.R, as they fully illustrate the usage of the functions exposed by uniset in the target package.

Enjoy !