Refer to ZMap/doc/config.txt for some discussion of the previous code which was distributed amongst the zmapConfig/ and zmapUtils/ and zmapFeature/ directories, including some not very obvious files (eg zmapStyleUtils.c), and also included the previous version of code which was not used.
For this version all the config handling code will reside in zmapConf and documentation regarding use will be updated and put on the developer web site.
Here's a summary of what and how:
1) Reading Files
The user may specify a config file by a command line argument but if not a default file ~/.ZMap/ZMap will be used. ZMap may also refer to system and application specific config files if installed (/etc/ZMap and $ZMAP_HOME/ZMap). If so then the data in the system and application files will take precedence
The ZMap file may contain stanzas and keys as defined by the GLib GKeyFile module. Multiple instances of a stanze will be combined and if multiple instances of a key exist thent last one will take precedence.
Any number of extra config files may be refered to by keys and any nuumber of these may be loaded on request by the application - by default only the main config file will be processed.by ZMap's main thread.
In cases where multiple instances if a single stanza type are required (eg for multiple data sources) then either a list of stanzas will be specified by a key, or the stanza names will be prefixed by the stanza type (eg [source:wublastx]). ZMap will get a list of all stanzas and process each appropriately.
A name key will be added to all stanzas if not present.
2) Writing files (and editing)
Currently only the [Blixem] stanza needs to be updated by ZMap, but if so the entire ZMap config file will be written. Note that this applies to the 'user config' only, not the system or application files (if present).
There are modules in the code that edit a memory copy of config data. Although the use the config module they are not part of it and if included in config code will be moved elsewhere. (Not relevant)
3) Stanzas and Keys
Here it is assumed that the reader is familar with the existing scheme and some modifications are proposed:
In the [source] type stanzas options are available to define featuresets and styles. Coincidentally at present these are identical and style names could be defaulted to be the same as the featureset name - this makes sense as when a source provides featuresets data it would be expected to supply styles as part of this.
Styles may be defined in a config file which can be specified in [ZMap] with the key styles-file=filename, and only one will be allowed.
Individual source stanzas will not have a styles-file key.
Styles may be defined in a source stanza as at present - it is inteneded that DAS servers will be able to request styles in future - but sources are not required to process this. ACEDB servers have styles defined by thier featuresets and do not use styles config. File and Pipe servers do not use styles config as they assume that featuresets are displayed using a style of the same name, wever they will honour the list of styles if given.
Options to specify ambiguous stanzas have been removed eg [sources], [source] etc.
Sources must be listed in [ZMap] sources=one ; two ;.... and the individual sources defined in a stanza each.
In terms of policy [source] is no longer allowed ... but the code is still there, one [source] stanza will still work.
4) Application interface
Each module that uses configuration data will read in the config file(s) and create its own copy of config data each time that it initialises - for example creating a new window will result in up to date setting beings used for that window. Or the main thread may create new data sources when a new ZMap is created (any existing ZMap will continue unchanged).
Application code can choose to read in extra files (specified by a config key or hard-coded), and this function will be provided by the zmapConfig module. Regardless of how many files are read for any given config data object all files and stanzas will be merged into a single interface.
The files themselves are read into a blank GKeyFile data structure and stanza names and key values accessed by querying this GLib interface. Each stanza has an associated data structure defined by ZMap which is initialised by the config code and key data overlayed onto this.
After reading in config file and creating these data structures the GKeyFile date may be freed.
Key and stanza names/ strings are defined in a single file: include/ZMap/zmapConfigStrings.h. The file ZMapConfigLoader .c has all the code for constructing stanzas. It was intended to scatter stanza specific data to modules that used it but this preoved impractical due to the need for several different modules to access the same stanzas.
All the config handling code is now in zmapConfig/ and there are 15 source files the use it (grep for ConfigIni.h to find them).
5) User guide
(This needs to be updated)
6) Other features
NB: Styles data - styles can refer to parent styles to an unlimited depth, but this feature is limited to styles defined in a single file. A child inherits all the parent's data and the overlays its own. Multiple definitions of a style result in the original one being used.
-- not checked --
7) Technical details
-- Source files, config data structures and related functions --
zmapConfigDir.c finding the config files, internal only,
well nearly: used by AppWindow, Logging, and View (for iffed-out code)
zmapConfigFile.c reading and writing files, internal only
zmapConfigKey.c get and set values, internal only
zmapConfigIni.c the main external interface, read files, find stanzas, get key values
zmapConfigLoader.c part 2 of the external interface
initialise stanza structures. Read groups of stanzas (sources and styles).
headers:
include/ZMap/zmapConfigIni.h what application modules need most often
include/ZMap/zmapConfigStanzaStructs.h
include/ZMap/zmapConfigStrings.h
include/ZMap/zmapConfigDir.h
zmapConfig/zmapConfigDir_P.h private header for ConfigDir
zmapConfig/zmapConfigIni_P.h private header for ConfigIni
Internal to the zmapConfig module there is a ZMapConfigIni struct which is simply a list of GKeyFiles. Functions which deal with this are in the files zmapConfigFile.c and zmapConfigKey.cand are generally named -ConfigIniThing();
External (ie visible from outside) to the zmapConfig module there is a ZMapConfigIniContext struct which includes a ZMapConfigIni and a few other items. Pretty much all of the global functions in zmapConfig take an -IniContext structure, pass on the -Ini struct and ignore all the rest,
zmapConfigIni.c and zmapConfigLoader.c hold the external functions, External functions are called -IniContextThing()
zmapConfigDir.c was intended as internal but turn out to have some functions called from startup code.
