Thalassa CMS logo

Thalassa CMS

Ini file basics



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:


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, and the particular format is defined by this library. The rest of this page is devoted to details specific for this implementation.

Section groups

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.

Parameters with specifiers

Another important implementation-specific feature is that a parameter name can contain a specifier, separated with a colon, like this:

  email:sales =

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 =
  email:support =
  email:legal =
  email:netadmin =
  email =

— thus assigning four specific addresses and one default, for any other issues. Another (imaginary) organization could make the things simpler:

  email:legal =
  email =

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 as the sales department address for the first company, but for the second one in the same situation it will use the default

Multiline values

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

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.

Joining sections

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:

  name = John
  age = 37

  smoking_prohibited = yes

  surname = Smith
  job = teacher

has exactly the same effect as if it was

  name = John
  age = 37
  surname = Smith
  job = teacher

  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.

Joined parameter values

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


  foo = bar
  foo = bur
  foo = bazz

has precisely the same effect as


  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.

© Andrey V. Stolyarov, 2023, 2024