User Tools

Site Tools


xini
no way to compare when less than two revisions

Differences

This shows you the differences between two versions of the page.


xini [2011/04/04 20:00] (current) – created jochen
Line 1: Line 1:
 +====== xini (ini/configuration file handling class) ======
  
 +===== Motivation =====
 +Storing configuration settings in .MAT-files makes it sometimes more cumbersome to change those settings (particularly when trying to compare a prior set to the currently used one). In such cases, it can be helpful to store the settings in a text file.
 +
 +However, as Matlab does not have builtin support for storing multiple variables in structured textfiles, I decided to implement a class that would handle such files. The class has the following main features:
 +
 +  * reading/writing ini-files (see below for format description)
 +  * accessing "sections" and individual settings within the object
 +  * grandfathering settings (or sections) from another object
 +
 +===== Requirements =====
 +The [[any2ascii]] function must be properly working (e.g. if user-defined classes are used, it must be overloaded).
 +
 +===== Reference ('help xini') =====
 +<file>  xini (class)
 + 
 +  creates an object for ini-file handling
 + 
 +  Input: for meaningful object construction, give filename!
 + 
 +  ___ Constructor methods: ___
 +  ----------------------------
 + 
 +  xini          returns a handle to an xini object
 +        FORMAT: IniFileObject = xini(Filename [,convert]);
 +        FORMAT: NewObject = xini('convert' | 'new');
 +        FORMAT: FactoryObject = xini;
 + 
 +  ReleaseAllFiles       issue release for all open objects
 +  ReloadAllFiles        issue reload for all open objects
 +  ResetClass            resets the internal variable, useful for debugging
 +  SetIniString          create an IniFile object from an inistring
 + 
 +  ___ NOTES: ___
 +  --------------
 + 
 +   *)   with conversion active, xini uses any2ascii, another part
 +        of this toolbox to write non-character variables to disk;
 +        when not active, only valid one-line char arrays are allowed!
 + 
 +   **)  storage for the ini file settings is NOT part of the object, but
 +        is requested and maintained by the singleton object itself, thus
 +        only little memory is needed for argument handling, even with
 +        bigger ini file, plus multiple functions can share one ini file!</file>
 +
 +===== ini file format =====
 +Information in these ini files is stored as follows
 +
 +  * a free-text header of variable length can be stored (any text prior to the first occurrence of the ''['' character at the beginning of a line)
 +  * a free-text footer of variable length can be stored (any text following the line that reads ''[/EndOfXINI]'')
 +  * information is grouped into "sections" (internally represented by one struct per section) and, possibly, sub-sections (structs as the field of the section struct)
 +  * individual settings are stored as numbers, with support for cell arrays and logical values
 +
 +As an example, here is the ''Statistics'' section from the ''neuroelf.ini'' file in the ''_core/config'' sub-folder of NeuroElf (see [[NeuroElf installation#installation_folder_structure|folder structure]] of NeuroElf):
 +
 +<file>[Statistics]
 +ClusterTableAdd=[false]
 +ExtractOnSelect=[true]
 +InterpMethod=linear
 +JoinMaps=[true]
 +LocalMax=[true]
 +LocalMaxSrfNeigh=[4]
 +LookupCoord=peak
 +RobustVOICondAvg=[false]
 +ShowThreshBars=[true]
 +ThreshBarPos=[0.93,0.25,0.99,0.75]
 +Thresholds=[0.05,0.02,0.01,0.005,0.002,0.001,0.0005,0.0001,5e-05,1e-05,5e-06,1e-06]</file>
 +
 +As you can see, both text-based tokens (''InterpMethod'' and ''LookupCoord'' setting) as well as numeric (e.g. ''Thresholds'') and boolean (e.g. ''ShowThreshBars'') values can be stored.
 +
 +===== ini object access =====
 +To access the contents of an object, the filename is passed into the xini constructor:
 +
 +<code matlab xini_readfile.m>% read the neuroelf config file with support for numeric/complex values
 +neuroelf_ini = xini([neuroelf_path '/_core/config/neuroelf.ini'], 'convert');</code>
 +
 +Sections and settings can then be accessed with the overloaded [[@xini/subsref]] and [[xini/subsasgn]] functions:
 +<code matlab xini_getset.m>% add another threshold
 +neuroelf_ini.Statistics.Thresholds(end+1) = 0.1 * neuroelf_ini.Statistics.Thresholds(end);</code>
 +
 +And to write a file back to disk, the [[xini.Save]] method can be used:
 +<code matlab xini_save.m>% save the object back to disk
 +neuroelf_ini.Save;</code>
xini.txt · Last modified: 2011/04/04 20:00 by jochen