Options in a configuration or ini-file
Option variables may be defined in configuration or ini-files, which are passed to the application. Typically, options are passed via ini-files, which are easier to handle than XML configuration files. More complex option hierarchies, however, could be handled better in an XML file.
Ini-files are much shorter and easier to handle as long as the option hierarchy depth is not greater than 2 (section/value). More complex option hierarchies may be defined in ini-files as well, but this requires knowledge about the extended ini-file syntax, which may appear a bit tricky. The XML schema is quite simple and very straight. It only consists of nested Option elements with attributes key and value.
Regardless on the way passing options to the application, option values can be accessed by means of option paths, which consist of a sequence of option names defining the option hierarchy.
Option or section names are limited to 40 characters. The nesting level for an option hierarchy is not limited. As low level options, sections may get a value. A reserved value is ignore. Setting a section option to ignore will ignore all options defined in the section and its subsections.
Within an ini-file, options are arranged in a two level hierarchy. The first level corresponds to the sections in an ini-file. The second level refers to option variables defined for this section. Some extensions for ini-file syntax also allow defining ini-files of any hierarchy depth. Each option in a hierarchical ini-file may get a value and/or any number of sub-options.
Typically, options are passed via ini-files, which are easier to handle than XML configuration files. A simple ini-file contains one or more sections introduced by
[section_name]
Sections and option variables have to start at the beginning of a line and must not exceed the line end. All text following the option name is considered as value up to the line end, i.e. comments cannot be placed in the same line as the value Section or option lines beginning with tabs or spaces will be ignored.
The section with the application (program) name as section name is considered as application section. Options in the application section are considered as default section options and may be accessed directly by option name (without preceding section name). Options at the beginning of an ini-file (before first section) are considered as top options, which may be referenced without section prefix. In contrast to XML configuration files, ini-files do not support values for sections. Instead, one may define hierarchical top level option variables, which may contain value and sub-options.
In order to refer to options in other than the application section, option names have to be preceded by the section name.
For defining deeper option hierarchies in an ini-file, one may define option paths within any section. One may also define inline sections or section references instead of using option paths.
The default structure for ODABA ini-files consists of a set of hierarchical options identified by name. Each option may get a value separated from the name by '=' and/or a number of sub-options introduces by a section break '['. Options containing sub-options are considered as sections at the same time. Within a section, any number of sub-options or sub-sections may be defined. The nesting level is not limited. Sections on any level have to terminated by a section terminator ']'. No spaces are allowed between option name and option value. All option names have to start at line beginning as well as section terminator.
In addition, the traditional ini-file structure is supported, which contains a number of top level sections and options. Each section starts with a case insensitive section name enclosed in '[' and ']'. The end of a section is the beginning of the next section or the end of file. One cannot assign values to traditionally defined sections, but within a traditional section, one also may define ODABA sub-sections as inline or reference sections.
; ODABA ini-file default structure
option_name=value[
sub1_name=value
sub2_name=value
sub_section=value[
...
]
]
; traditional structure
[myApplication]
USER=Miller : USER / myApplication.USER
Options.Documentation.Templates=~/myTemplates
: Options.Documentation.Templates
[OtherOptions]
Language=English : OtherOptions.Language
Extensions.Name=ext : OtherOptions.Extensions.Name
The simplest way of defining hierarchical options are option paths, were section names precede the option name. Within the application section, the option path must contain all section names including the top section. Option paths in other sections are automatically preceded by the section name (see example below).
; Option("Options.Documentation.Templates") in application section
[myApplication]
Options.Documentation.Templates=~/myTemplates
; Option("OtherOptions.Extensions.Name") in sub-section
[OtherOptions]
Extensions.Name=ext
Comment in options become part of the option value and are used here, for explanation only. Within ini-files, one has to write comments on separate lines.
There is no problem in an XML configuration file to create any number of nesting levels for options. In an ini-file, option paths might be used, but sometimes it is more comfortable using option references or inline sections, which allow defining a list of sub options for a given option.
Inline sections are defined as options followed by a sub-section. In addition to the sub-section options the option may also get a value.
OPTION=value[
...sub-values
]
The opening bracket has to be defined at the end of the option line. The closing bracket has to be defined on a separate line (otherwise it may become part of the sub-option value.
DATABASE=[
PATH=c:\sample\oracle\sample.dat
TYPE=ORACLE
DATABASE=Sample
USER=Test
PASSWORD=pw
]
Option references refer to another section on top level. Option references in ini-files allow referring to the same section several times.
OPTION=value[section_name]
...
[section_name]
... sub-values
For accessing the option the option name is used rather than the name of the reference section, i.e. in order to refer to the database type in the example below
Option("DATABASE.TYPE")
has to be checked.
DATABASE=[ORACLE-Sample]
; ...
[ORACLE-Sample]
PATH=c:\sample\oracle\sample.dat
TYPE=ORACLE
DATABASE=Sample
USER=Test
PASSWORD=pw
Typically, options are passed via ini-files, which are easier to handle than XML configuration files. For more complex option hierarchies, however, XML configuration files could be a better choice. Within an XML configuration file each XML element gets a value and any number of sub-elements. XML elements containing sub-elements are automatically considered as sections (or sub-sections).
Similar to ini-files, the application section defines option variables that need not to be prefixed by section name (but may be). In addtion, one may, however, define real top level option variables and assign values to sections.
It is no problem, to define any depth of option hierarchies in an XML configuration file.
In order to distinguish between XML configuration and ini-files, XML configuration files have to start with the "<?xml " tag. If not, the file is considered to be an ini-file. Below there is an example for an XML configuration file and the corresponding ini-file.
The XML file passed as configuration file must contain an OConfiguration element. Options are read only from elements below the OConfiguration element. OConfiguration elements are defined as top level element or at any lower element. The only condition is, that all OConfiguration elements have the same parent (as the first OConfiguration elements). OConfiguration elements with other parents will be ignored. Sub elements for OConfiguration elements are option elements, which may have subordinated option elements etc. Supported attributes for option elements are key and value. For OConfiguration elements only the name attribute is supported. Besides, OConfiguration and option elements may contain any number of unsupported attributes or elements.
Similar to ini-files, XML configuration files support inline sections (default), reference sections and option paths.
In order to reduce the number of hierarchy levels, one may also use option paths within an ini file. One should, however, not mix path options with option references or inline sections for the same section.
Comment in options become part of the option value and are used here, for explanation only. Within ini-files, one may write comments on separate lines.
In order to define inline sections within an XML configuration file, one may simply open a lower level Option element without terminating it immediately. Section options may get a value similar to any low level option.
In order to refer to options defined in other top level section options, the option value must contain the section name for the reference section as in the example below. The name of the reference section is part of the option value and must be enclosed in '[' and ']'. The section reference is not considered as part of the option value, i.e. in the example below, the value for the option OtherOptions is just accept. Section references have to refer to top level options, always.
The odaba::utils namespace provides anIniFile class supporting direct access to ini-files. The class provides a C++ interface as well as an OSI interface, but not yet a C# interface. The class supports read and write functions for configuration and ini-files.