Contents:
The “ini” file format is generally well-known: the file consists of sections, every section contains parameters. Section starts with a section header, which is basically a line surrounded with square brackets, like this:
[general]
Each parameter has a name and a value; the value is separated from the name with an equality sign, like this:
param1 = this is the value for the parameter named param1
Empty lines (that is, lines consisting exclusively of whitespace chars) are ignored, as well as comment lines; and here the “general” ini file format description unexpectedly ends, because what “comment line” strictly is, appears to be implementation-specific.
Fortunately enough, there's no “stardard” for ini files, so authors of
various programs implement slightly different notions of what ini file
actually is. Thalassa CMS uses a very small (actually, single-module)
library written by Andrey V. Stolyarov, named simply inifile
(see
http://www.croco.net/software/inifile),
and the particular format is defined by this library. The rest of this
page is devoted to details specific for this implementation.
First of all, section name can consist of one or two words.
Sections named with just one word, like [general] from the
example above, are kinda stand-alone, whilst sections with 2-word names
form so-called section groups; the group is defined by the first
word of the name. Hence, the following sections:
[foo bar] enabled = yes [foo bur] enabled = yes [foo bazz] enabled = no
form a section group named foo, and each of the three sections
has a parameter named enabled, with value yes for
the first two sections and no for the last one.
Another important implementation-specific feature is that a parameter name can contain a specifier, separated with a colon, like this:
email:sales = sales@example.com
Such specifiers define special cases of a generic parameter value; a parameter with the same primary name but with no specifier is taken as the default. For example, some (imaginary) company could have a list of contact emails like this:
email:sales = sales@example.com email:support = support@example.com email:legal = attorneys@example.com email:netadmin = noc@example.com email = info@example.com
— thus assigning four specific addresses and one default, for any other issues. Another (imaginary) organization could make the things simpler:
email:legal = Mrs.Sarah.Smith@example.org email = boss@example.org
If a particular program is written (or configured) so that it uses email
specifiers sales, support, legal,
netadmin and possibly others to decide what email address to
use in any given situation, then the program will use
sales@example.com as the sales department address for the
first company, but for the second one in the same situation it will use the
default boss@example.org.
In this variant of ini format, a parameter value may consist of several
lines of text, and there are two ways to achieve this. In both cases,
several lines immediately following the one where the parameter starts, are
explicitly made to be continuations of the parameter's value:
either by starting the additional line by an arbitrary amount of white
space (spaces and tabs), or by placing the “+” (plus) sign
at the leftmost position of the line, like this:
longparam = The value for this parameter is
effectively a text consisting of three
lines, with all leading whitespace stripped.
anotherlongone = With this parameter, its value is
+multiline as well, but it can contain whitespace
+at the start of some lines, like this:
+ this line starts with 3 spaces;
+ this one starts with 6 spaces;
+you've got the idea.
Inside the actual parameter value (which the program receives from the file parser) the lines are separated by the newline character, so the parameter's value becomes a real multiline text. As one could guess from the example, the whitespace variant doesn't allow to have any leading whitespace in lines of the text, as all the leading whitespace is stripped off. The “plus” variant solves this, but it might look less readable.
There's another thing to note here. For any parameter value, not only
multiline, the parser strips off all the spaces and tabs (but not newline!)
located right after the “=” sign, as well as all trailing
whitespace together with the newline character which terminates the value
(but only the terminating newline, not a one preceding it, if any). This
means that your multiline parameter will not contain a terminating newline
character. Sometimes such a newline is needed, specially in templates
that expand to a multiline fragment of your target (generated) file. This
problem is solved by adding an empty line with another “+”, like this:
realtext = For this parameter, the value +is a real multiline text, which is terminated +by a newline character, just like any correct +text. +
In the present version it is impossible to have the first line of a parameter value to start with whitespace, but this is subject to fix; it is possible future versions will strip off the first line of a value in case it is empty.
Most ini file interpreters consider a current section finished once they encounter a header for another section or the end of file. This is not the case for the parser used in Thalassa CMS.
Two or more sections with equal names, no matter how far from each other they
appear in the ini file (or even in different files, in case more than one
file is being loaded into the same parser — which happens when you
use several ini files for the thalassa program) are considered
to be parts of one section, just as if parameters from all them were
written in the first of them. For example, to write the following:
[person] name = John age = 37 [special] smoking_prohibited = yes [person] surname = Smith job = teacher
has exactly the same effect as if it was
[person] name = John age = 37 surname = Smith job = teacher [special] smoking_prohibited = yes
The parser considers a line to be a comment (and therefore ignores it) if,
and only if, the first non-whitespace character of the
line is either semicolon “;” or hash mark
“#”.
The parser also allows to place a comment on the line of a section header, like this:
[foo bar] ; here goes the comment
(or with a “#” instead of “;”).
On lines other than section headers, in case a “;” or
“#” is encountered after any non-space chars, they
have no special meaning.
BTW, a comment line may be placed within a multiline value, like this:
longpar = This is the first line of the value
this is the second line of the value
; this is a commentary line
this is the last (third) line of the value.
Thus, if you need a line of your value to start with “;” or
“#”, use the “plus” variant of additional strings:
longpar = This is the first line of the value +this is the second line of the value +; this is a no longer a comment, but the third line +this is the last (fourth) line of the value.
In the present version of the parser, if in a single section there are two
or more parameters with exactly equal names, their values are joined
together as a comma-separated list. This behaviour is likely to become
optional in future versions of the inifile library, and if
this happens, Thalassa CMS will disable it; but as of present, there's no
way to get rid of this despite it is of no use for the particular program.
For example, to write
[general] foo = bar foo = bur foo = bazz
has precisely the same effect as
[general] foo = bar, bur, bazz
This is also true for joined sections, so, for example,
[list first] enabled = true items = 5 [list first] enabled = true items = 10
turns into
[list first] enabled = true, true items = 5, 10
which will likely simply fail.
Thalassa CMS doesn't rely on this behaviour in any way, but it can lead to strangely-looking errors, and this is why its explanation is included here.