Comments

The hash sign # denotes the beginning of a comment spanning to the end of the line.

# This is a comment that will be ignored

Notes:

Comments do not necessarily need to stand alone in a line, e.g. a comment may begin after a key-value pair in the same line.
The only exception where the hash sign # is not interpreted as a comment marker is after an @include statement; see sec_include for more details.

Properties

Properties (data) are declared as so-called 'key-value pairs'

key = value

where the first equals sign = is used as a delimiter to separate the key and value parts. Both the key and value strings are trimmed from leading and trailing whitespaces – and, in the case of the value part, also comments – but are except for that parsed verbatim.
Furthermore, the value part of the declaration may be split across multiple consecutive lines by appending an ampersand symbol & as the last non-whitespace character in a line. In this case the parser will append the next (semantically) non-empty line and, if this line also ends with an ampersand, continue the line continuation process iteratively, e.g. the three lines

message = Hello &
          World&
          !

are equivalent to

message = Hello World!

Notes:

As mentioned before, the hash sign # is recognised as a comment identifier even in a key-value pair, e.g. the line
```
key = value # and a comment in the same line
```
is equivalent to
```
key = value
```
As an obvious consequence there is (currently) no way to declare a value which contains a hash sign #.
Although keys and values are parsed verbatim, the parser handles the key string in case-insensitive manner, e.g. the three declarations
```
key = value
KEY = value
Key = value
```
are all equivalent.
The value string of a declaration may be empty, e.g. the two lines
```
Foo =
Bar = # comment
```
are both legal declarations that will assign empty strings to the keys Foo and Bar.
If multiple declarations specify the same key and (possibly) different values, the parser will 'forget' any of these declarations except for the last one, e.g. the three declarations
```
key = This value
key = was defined
key = more than once
```
will be boiled down to
```
key = more than once
```
In the line continuation process the parser
- does not trim whitespaces between the value part the ampersand symbol & , e.g.
```
message = Hello   &
          World!
```
  is equivalent to
```
message = Hello   World!
```
- skips semantically empty lines, e.g. the four lines
```
message = Hello &

    # comment
    World!
```
  boil down to
```
message = Hello World!
```
- does not further analyse the line to be appended, e.g. the three lines
```
key = my &
    # value
date = 2012-12-21
```
  boil down to
```
key = my date = 2012-12-21
```
  which yields (as the value string is allowed to contain an equals sign) a syntatically correct declaration but does most probably not represent the author's intention.

Sections

Several key-value pairs can be grouped together in sections. A section is declared by a single line containing the section name enclosed in a [ ] bracket pair. Any key-value pair following a section declaration is placed inside that section until another section declaration appears, e.g.

[Section]
# a key-value pair within 'Section'
Hello = World!

[AnotherSection]
# a key-value pair within 'AnotherSection'
Foo = Bar

Furthermore, by using pairs of curly braces { } one can also nest sections:

[Section]
{
  Hello = World!      # a key-value pair within 'Section'

  [SubSection]
  Foo = Bar           # a key-value pair within 'Section.SubSection'

  [AnotherSubSection]
  {
    answer = 42       # a key-value pair within 'Section.AnotherSubSection'
  } # end of [AnotherSubSection]
} # end of [Section]

Notes:

The section name is trimmed of whitespaces by the parser, e.g. the two lines
```
[Section]
   [  Section    ]
```
are equivalent.
In analogy to the handling of keys, section names are handled in case-insensitive manner.
If multiple section declarations specify the same section name, their contents are merged, e.g.
```
[A]
foo = bar
[B]
key = value
[A]
Hello = World!
```
is merged into
```
[A]
foo = bar
Hello = World!
[B]
key = value
```
If no section nesting is required, the use of curly braces { } is optional and can even be mixed within one file, e.g.
```
[A]
{
  key = value
}
[B]
foo = bar
```
is syntactically legal.

If curly braces are used, then no key-value pair must be declared between the section marker and its opening curly brace or after the closing curly brace, e.g.

[A]
key = value       # error: key-value pair before '{' in next line
{
  foo = bar       # okay: inside curly braces
}
Hello = World!    # error: key-value pair after '}' in previous line

Each curly brace must stand alone (modulo comments) in a separate line, e.g. the commonly used "C" style
```
[A] {
  key = value
}
```
is illegal.

Examples

# This is a comment and the next line is a simple key-value pair in the root section
key = value

# The next two lines open a new section named 'MySection'
[MySection]
{
  # Two key-value pairs in 'MySection'
  date = 1985-05-08
  message = Hello World! # This is a comment after a key-value pair

  # A subsection named 'MySubSection' nested in 'MySection'
  [MySubSection]
  pi = 3.1415926535&   # pi is in 'MySection.MySubSection'
         8979323846&   # and pi has a lot of digits...
         2643383279... # ...which need several lines

  # The next line will close both 'MySubSection' and 'MySection'
}

Author: Peter Zajac

Table of Contents

Comments

Properties

Sections

Examples