1. The Config File
Writing your config file is easy. It’s like a java.util.Properties file except it must be Unicode (ISO-10646) encoding, not ISO-8859 or some such. Nowadays there are plenty of tools to transcode text files, notably
- uconv on Linux/Unix computers,
- various IDEs,
- native2ascii in the JDK tool suite may be useful in some cases.
The config file may optionally start with a Unicode byte-order-mark (BOM) and this is required for automatic switching between UTF-8, UTF-16 and UTF-32. If the BOM is absent, UTF-8 is assumed. Plain 7-bit ASCII is a subset of UTF-8 so will also work.
Define values using key/value pairs, with comments introduced by a leading ‘#’.
# simple string
a = something
b = else
happiness.enabled = true
tau = 6.2832 # 2 x Pi
The value can use double quotes, which retains the enclosed whitespace that would otherwise be trimmed.
q = " quoted strings are allowed to include the # character and also tabs \t etc "
A few special characters are supported: \t becomes a tab (0x09); \n becomes a newline (0x0A); \r becomes a carriage return (0x0D).
Keys can contain any character except the delimiter (which is usually=). Surrounding whitespace is removed. So:
can keys contain spaces? = true
is a valid way to define a key can keys contain spaces? with the value true.
Long lines
Using a trailing backslash at the end of a line, continuation lines allow long values. The resulting value includes all the newlines that were preceded by a backslash, but not the backslashes themselves.
Long lines can be with or without double-quotes according to need. This example has them so includes a space at the start of both lines, not just the second line.
redeeming = " I'll so offend, to make offence a skill;\
Redeeming time when men think least I will."
You may prefer that the leading whitespace is elided - this is achieved using vertical bar characters, which are not themselves part of the value.
henryIV = So shaken as we are, so wan with care,\
|Find we a time for frighted peace to pant,\
|And breathe short-winded accents of new broils\
|To be commenced in strands afar remote.
If you need to include a vertical bar at the start of a line, simply double-up. The first | is removed during parsing but the second is part of the value.
redeeming = I'll so offend, to make offence a skill;\
|| Redeeming time when men think least I will.
Interpolation
Using a pair of braces, strings are interpolated with values defined earlier. In the next example, {a}, {b} and {c} refer to the keys a, b, and c. If a key is not found, the Java properties are consulted, so {os.name} is expanded accordingly. Failing that, the environment variables are consulted, so {HOME} is expanded accordingly. If no expansion is possible, the string is left un-interpolated, so {undefined} remains unchanged. Backslashes prevent interpolation.
extended = contains {a}, {b} and {c} and then {os.name} with {HOME} but not {undefined}
not.extended = does not expand \{a\} or \{b\}
Note: unlike shell scripts, no dollar sign is needed - just the curly braces.
Keys can also contain interpolation.
fat.{a} = Falstaff
fatty = {fat.something}
Interpolation doesn’t look-ahead to as-yet undefined values.
unresolved = cannot access {triangle} because it comes later
Lists
Lists are supported. Here is a list of three integers.
triangle = 3, 4, 5
Here is a list of seven strings.
rainbow = red, orange, yellow, green, blue, violet, indigo
Here is a list of three strings including spaces, represented in two equivalent ways.
likes1 = warm sun, cool beer, rippling lake
likes2 = "warm sun", "cool beer", "rippling lake"
Here is a list of three quoted strings including spaces, escaped quotes and commas.
actors = "\"Harry\", Daniel Radcliffe", "\"Ron\", Rupert Grint", "\"Hermione\", Emma Watson"
The outer quotes are not optional because they enclose some of the commas. Of the five commas in this example, three are enclosed in quoted strings so are part of those strings; the other two mean the value can be split into the list of three strings. When a backslash precedes a double-quote character, the double-quote character becomes part of the value instead of being a delimiter.
Nested Sub-sections
Nested keys have a prefix that allows a subsection to be pulled out separately. This is described in more detail later on.
xx.a.z1 = alpha
xx.a.z2 = beta
xx.b.z3 = gamma
xx.b.z4 = delta
In this example, the common prefix “xx.” allows a subsection to be pulled out that consists only of these four entries.
‘INI’-file Sections
As a shorthand for nested sections, square-bracketed ini-file section headings can be used. Under the hood, the section names are prepended onto all the keys within their section, separated by a dot ‘.’. So the following configuration is exactly the same as the one shown just above.
[xx]
a.z1 = alpha
a.z2 = beta
b.z3 = gamma
b.z4 = delta
This example is, in effect, the same as the one earlier. It illustrates that you have a choice how you organise entries into groups. The heading containing the section name “xx” allows a subsection to be pulled out that consists only of these four entries.