PBSmodelling (version 2.68.6)

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

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.

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.

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

# NOT RUN {
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 ))
})
# }