BControl Settings Interface

Overview

update: In recent versions of MATLAB, "Settings" is reserved, so this function has been changed to bSettings

For instructions on how to begin configuring existing BControl code through the settings files as a user, see Startup Guide instead.

This page describes how to use the Settings Interface for global BControl settings within code (e.g. protocol code).

The global settings interface and its specs live in the file Modules/Settings.m. Through it you can load settings from a group of files into memory and retrieve individual settings or settings groups.

The simplest way to use the settings interface:

 setting = Settings('get','SETTINGGROUP','settingname');
 group   = Settings('get','SOMEGROUP','all'); % returns whole group in cell matrix (see get)

You can do that without doing anything else first, and you'll get back the setting value - as a double if it looks like a number (str2double), and as a string otherwise. If no settings have been loaded yet, the Default and Custom files are loaded on the fly (The call made is Settings('load').). Newstartup.m always loads Default and Custom.

Any files matching the Settings File Format can be loaded first. Settings defined in later files will overwrite settings of the same name previously loaded.

 Settings('load');  % loads Settings_Default.conf and then Settings_Custom.conf

 Settings('load','file1','file2','file3',<etc>);  %loads any number of specified files in order
 Settings('load','some_other_file');  %You can add more files at any time.

All calls to Settings will also return an error ID (0 if OK) and an error message ('' if OK).

 [setting errID errmsg] = Settings('get','DIOLINES','right1water');

Actions

The first argument to the Settings function is an action string (case-insensitive). This documentation was extracted from Modules/Settings.m on 2007.July.26.

         GET                 <-- useful          for normal users
         COMPARE             <-- useful          for normal users
         LOAD                <-- not necessary   for normal users
         NOTLOADED           <-- not necessary   for normal users
         GETALL              <-- not recommended for normal users
         CLEAR               <-- not recommended for normal users

get

       GET retrieves the initialized setting with the given name, or all
         settings in the group if setting name 'any' is given.

       If no setting exists with the given name, errID will be as
         shown below, and an informative error message should be
         provided.

       If no settings files have been loaded yet, Settings('load') is
         called first.

       ADDITIONAL ARGS:	2
            - Arg#1:             name of target setting's group
            - Arg#2:             name of target setting, or 'all' for
                                   all settings in the group (returns
                                   cell array of format:
                                      {s1name, s1value, s1groupname;
                                       s2name, s2value, s2groupname;
                                        ...}
       RETURNS:	[settingval errID errmsg]
            - settingval:        requested setting value, or cell array
                                   of settings if multiple settings are
                                   requested
            - errmsg:            '' if OK, error string otherwise
            - errID:             0  if setting was found,
                                 1  if setting was not found (and value
                                        returned should be ignored)
                                 3  if group was not found
                                 8  if settings were not loaded
                                      beforehand and attempt to load
                                      settings using Settings('load')
                                      failed
                                 -1 if programming error (errID not set)
                                        PLEASE CONTACT DEVELOPER.
       SAMPLE CALLS:
             [maindir errID errmsg] = Settings('get', 'MAIN', 'Main_Directory');
             cvs_username = Settings('get','CVS','CVS_Username');
             [DIOLines err msg] = Settings('get', 'DIOLINES', 'ALL');

compare

       COMPARE compares the setting with the given name to a specified
         value. If no setting exists with the given name, errID is as
         shown below, and an informative error message is provided.

         If no settings files have been loaded, Settings('load') is
           called first.

       ADDITIONAL ARGS:	3
            - Arg#1:             name of target setting's group
            - Arg#2:             name of target setting
            - Arg#3:             value to compare the setting to
                    
       RETURNS:              [settingval errID errmsg]
            - are_equal:         logical true if the loaded setting
                                   value matches the given value, false
                                   in all other cases
            - errmsg:            '' if OK, error string otherwise
            - errID:             0  if setting was found and is valid,
                                 1  if setting was not found (and value
                                        returned should be ignored)
                                 3  if group was not found
                                 8  if settings were not loaded
                                      beforehand and attempt to load
                                      settings using default filenames
                                      failed
                                 -1 if programming error (errID not set)
       SAMPLE CALL:
             [playsounds errID errmsg] = ...
                 Settings('compare', 'EMULATOR', 'softsound_play_sounds', 1);

load

       Load reads settings files into memory and reports success.

       Load can work TWO WAYS:
         0 ARGS. Loads the "Default" and "Custom" settings files.
         N ARGS. Loads specified settings files in order, first to last.


       ADDITIONAL ARGS:	0 OR any number of nonempty strings
            - Optional Arg#N:	filename of a settings file to load

       RETURNS:	[errID errmsg]
             - errmsg:           '' if OK, error string otherwise
             - errID:            0  if successful
                                 10 if bad arguments (e.g. fname '')
                                 1  if file was not found
                                 2  if file is not correctly formatted
                                      or could not be opened for reading
                                 -1 if programming error (errID not set)
                                        PLEASE CONTACT DEVELOPER.
       SAMPLE CALLS:
                 Settings('load');
                 [errID errmsg] = Settings('load');
                 [errID errmsg] = Settings('load','some_settings.conf');
                 [errID errmsg] = ...
                     Settings('load','set1.conf','set2.conf', ...
                 	'set3.conf', 'set4.conf');
    
       NOTES ON SPECIAL CASES:
       - ORDER:
         If a setting being loaded has the same name as one previously
           loaded, the previously loaded value is overwritten, so later
           files prevail.

notloaded

       NOTLOADED checks to see if any settings have been loaded into the
         SettingsObject.
       ADDITIONAL ARGS:      0
       RETURNS:              notloaded
            - notloaded:         0  if settings have been loaded into
                                      SettingsObject
                                 1  if no settings are loaded
            - errID:             always 0
            - errmsg:            always ''
       SAMPLE CALL:
             if Settings('notloaded'), error('Weird!'); end;

 
 
 

getall

       GETALL returns the settings data as internally represented:
             in a struct ('settings') with fields corresponding to
             settings groups with internal fields corresponding to
             individual settings, e.g.:
                 settings.GROUP.settingname      = 'blah value'
                 settings.OTHERGROUP.mrsetting   = '0'


         If no settings files have been loaded, Settings('load') is
           called first. See comments there.

       ADDITIONAL ARGS:      0
       RETURNS:              [setsstruct errID errmsg]
            - setsstruct:        a struct with format as above
            - errmsg:            '' if OK, error string otherwise
            - errID:             0  if no problems
                                 1  if error ??? (should not happen)
                                 8  if settings were not loaded
                                      beforehand and attempt to load
                                      settings using default filenames
                                      failed
                                 -1 if programming error (errID not set)
                                        PLEASE CONTACT DEVELOPER.
       SAMPLE CALLS:
             [settingsstruct errID errmsg] = Settings('getall');
             settingsstruct = Settings('getall');

clear

       CLEAR replaces the global settings object with a fresh one that
         has no settings loaded.
       ADDITIONAL ARGS:      0
       RETURNS:              [errID errmsg]
            - errID:         0   currently
            - errmsg:        ''  currently
       SAMPLE CALL:
             Settings('clear')

SettingsObject

The global settings interface employs a single global object of class SettingsObject, and you are also free to instantiate a separate SettingsObject for your own purposes. The underlying class contains most of the functionality of the interface above, but see documentation in Modules/@SettingsObject/ files. A summary may be added here later.

Quick examples:

 s = SettingsObject();
 s = LoadSettings(s,'Settings/Settings_blahblahblah.conf');
 setting = GetSettings(s, 'FAVORITES', 'food');

Note that these methods also return errID and errmsg, and that the Get (and test, etc.) methods (unlike Settings('get',...)) don't automatically load any settings if settings have not been loaded. (How could they know which files to use? :P)