uniset: Dynamic Settings File

unisetR Documentation

Dynamic Settings File

Description

Any package (subsequently called 'target package') is enabled 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 placed into the target package.

Details

There are two ways to generate the files required for the target package to make use of 'uniset':

-) Export and move manually

Use uniset_getFiles, then move the 'xxx_settings.R' file ('xxx' for the name of the target package) into the 'inst' folder (create one if not already done) of the target package. Move the files 'uniset_globals.R' and 'uniset_functions.R' into the 'R' folder of the target package.

-) Write directly to target package

(Recommended) Use uniset_copyFilesToPackage to copy the required files directly into the target package.

Every variable defined in the xxx_settings.R file is accessible in the code of the target package.
The target package has to list 'uniset' as an 'import', and then uniset_updateSettings or uniset_autoUpS can be used to manually or automatically update the settings,i.e. to read in the key=value pairs stored in the xxx_settings.R file. For an introduction and more detailed information please see https://bpollner.github.io/uniset/.

Advantage

The most imminent advantage of the 'uniset' settings-file system over using any static file for permanently storing settings for any package is the fact that the key=value pairs in the xxx_settings.R file get updated (added / deleted) dynamically.
So the developer of a package can delete keys or introduce new ones, and the new key=value pairs will be automatically added to or deleted from the local xxx_settings.R file. Values changed by the user of the target package will be preserved.
So the author of the target package can add or delete keys from the xxx_settings.R file without worrying that this will cause any effort or troubles for the user of the target package.

Links

Please see https://bpollner.github.io/uniset/ for a practical example; bug reports can be made at https://github.com/bpollner/uniset/issues.

Maintainer

Bernhard Pollner bernhard.pollner@mac.com

Functions for preparing the target package

uniset_copyFilesToPackage, uniset_getFiles

Functions to be called from within the target package

uniset_autoUpS, uniset_updateSettings, uniset_test, uniset_getstn, and only once: uniset_setup.

Examples

As the functions to update the settings file and to (automatically) source this settings are intended to be called from within the (installed) target package, please go to https://bpollner.github.io/uniset/ for a walk-through and for a real-life demonstration and examples how to use these functions in the code of the target package.

Author(s)

Bernhard Pollner, Zoltan Kovacs


uniset documentation built on March 28, 2022, 1:05 a.m.