BControl Settings Interface
From Bcontrol
Contents |
[edit] Overview
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');
[edit] 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
[edit] 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');
[edit] 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);
[edit] 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.
[edit] 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;
[edit] 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');
[edit] 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')
[edit] 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)
