Projects commonly involve various settings or options such as paths to C compilers or other third-party tools.
PBSmodelling provides a set of option management functions for managing user specific options. Options can be
modified through the provided set of functions on the command line, or through a custom GUI.
These options can be saved to disk for use in subsequent R sessions.
To use PBSmodelling's suite of option management functions, a PBSoptions object must be
created for each of your projects. Each PBSoptions object contains a distinct R environment where
option values are stored; this allows different projects to use overlapping option names without conflicts
(provided each project has its own PBSoptions class object).
Details
When a PBSoptions object is created with the new function, the initial.options list, if supplied, is stored
as initial user options in the object. The initialization routine then attempts to load user set options from the filename file. If such a file exists,
these values are stored in the PBSoptions object overwriting any initial values as specified by initial.options
Option values are not directly stored in the object, but rather in an environment stored in the instance slot.
Using an environment rather than slots for storing options allows us to pass option object by reference rather than value; that is,
we can save options in the object without the need of returning a new modified class object. It is therefore necessary that users
use the functions listed in the "see also" section to effectively manage user options.
Objects from the Class
Objects can be created by calls of the form new("PBSoptions",filename,initial.options=list(),gui.prefix="option").
filename:
default file name to use when saving and loading options to and from disk
initial.options:
a list with distinctly named initial options to use if no previously saved file exists
gui.prefix:
a prefix used to identify GUI variables which correspond to user options
Slots
instance:
The R environment used to store options. Please do not use this directly; use the functions listed under the "see also" section.
Methods
print
signature(x = "PBSoptions"): prints the list of options
Warning
Do not use the slots directly – use the access functions instead.
Author(s)
Alex Couture-Beil, Vancouver Island University, Nanaimo BC
See Also
getOptions for retrieving and modifying user options
getOptionsFileName for retrieving and modifying the default options file name
loadOptions for loading and saving options from and to disk
getOptionsPrefix for retrieving and modifying the GUI prefix (for custom GUI interfaces)
loadOptionsGUI for setting GUI values to reflect user options and vice-versa
Examples
local(envir=.PBSmodEnv,expr={
#initialize an option manager with a single logical option
.mypkg <- new( "PBSoptions", filename="my_pkg.txt",
initial.options=list( sillyhatday=FALSE ) )
#retrieving an option
silly <- getOptions( .mypkg, "sillyhatday" )
cat( "today is", ifelse( silly, "silly hat day!", "monday" ), "\n" )
#set an option
setOptions( .mypkg, sillyhatday = TRUE, photos = "/shares/silly_hat_photos" )
#create a GUI which works with options
createWin( c(
"check name=optionsillyhatday text="silly hat day"",
"entry name=optionphotos width=22 mode=character label="photos directory"",
"button func=doAction text=save action=saveOptionsGUI(.mypkg)" ), astext = TRUE )
#update GUI values based on values stored in .mypkg's options
loadOptionsGUI( .mypkg )
print(getOptions( .mypkg ))
})
Results
R version 3.3.1 (2016-06-21) -- "Bug in Your Hair"
Copyright (C) 2016 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu (64-bit)
R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under certain conditions.
Type 'license()' or 'licence()' for distribution details.
R is a collaborative project with many contributors.
Type 'contributors()' for more information and
'citation()' on how to cite R or R packages in publications.
Type 'demo()' for some demos, 'help()' for on-line help, or
'help.start()' for an HTML browser interface to help.
Type 'q()' to quit R.
> library(PBSmodelling)
Error in library(PBSmodelling) :
there is no package called 'PBSmodelling'
Execution halted