PBSoptions-class: S4: Project Options Class

Description

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).

Arguments

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

Author

Alex Couture-Beil, Vancouver Island University, Nanaimo BC

Warning

Do not use the slots directly -- use the access functions instead.

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.

Examples

Run this code

if (FALSE) {
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 ))
})
}

Run the code above in your browser using DataCamp Workspace