This shows you the differences between two versions of the page.
— |
xini [2011/04/04 22:00] (current) jochen created |
||
---|---|---|---|
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> |