An initialization or ini file is a configuration file tpically found on
Microsoft's Windows operating system and contains data for Windows based
applications.
Although popularized by Windows, ini files can be used on any system or
platform due to the fact that they are merely text files that can easily be
parsed and modified by both humans and computers.
A typcial ini file could look something like:
[section1]
; this is a comment!
var1 = foo
var2 = bar
[section2]
var1 = doo
The format of ini files is fairly straight forward and is comosed of three
components:
- Sections: Ini files are split into sections, each section
starting with a section declaration. A section declaration starts with a '['
and ends with a ']'. Sections occur on one line only.
- Parameters: Items in a section are known as parameters.
Parameters have a typical
key = value format.
- Comments: Lines starting with a ';' are assumed to be comments.
There are various implementations of the ini file format by various vendors
which has caused a number of differences to appear. As far as possible this
configuration tries to be lenient and support most of the differences.
Some of the differences supported are as follows:
- Comments: The '#' character is also accepted as a comment
signifier.
- Key value separtor: The ':' character is also accepted in place
of '=' to separate keys and values in parameters, for example
var1 : foo .
- Duplicate sections: Typically duplicate sections are not allowed ,
this configuration does however support it. In the event of a duplicate
section, the two section's values are merged.
- Duplicate parameters: Typically duplicate parameters are only
allowed if they are in two different sections, thus they are local to
sections; this configuration simply merges duplicates; if a section has a
duplicate parameter the values are then added to the key as a list.
Global parameters are also allowed; any parameters declared before a section
is declared are added to a global section. It is important to note that this
global section does not have a name.
In all instances, a parameter's key is prepended with its section name and a
'.' (period). Thus a parameter named "var1" in "section1" will have the key
section1.var1 in this configuration. Thus, a section's
parameters can easily be retrieved using the subset method
using the section name as the prefix.
Implementation Details:
Consider the following ini file:
default = ok
[section1]
var1 = foo
var2 = doodle
[section2]
; a comment
var1 = baz
var2 = shoodle
bad =
= worse
[section3]
# another comment
var1 : foo
var2 : bar
var5 : test1
[section3]
var3 = foo
var4 = bar
var5 = test2
This ini file will be parsed without error. Note:
- The parameter named "default" is added to the global section, it's value
is accessed simply using
getProperty("default") .
- Section 1's parameters can be accessed using
getProperty("section1.var1") .
- The parameter named "bad" simply adds the parameter with an empty value.
- The empty key with value "= worse" is added using an empty key. This key
is still added to section 2 and the value can be accessed using
getProperty("section2.") , notice the period '.' following the
section name.
- Section three uses both '=' and ':' to separate keys and values.
- Section 3 has a duplicate key named "var5". The value for this key is
[test1, test2], and is represented as a List.
The set of sections in this configuration can be retrieved using the
getSections method.
author: trevor.miller version: $Id: INIConfiguration.java 492216 2007-01-03 16:51:24Z oheger $ since: 1.4 |