Syntax Description
Configuration files are plain text files that consist of a number of sections, each containing zero or more options:
# Comment ...
[section.1]
[section.2]
name.1 = value
name.2: multi-line
value
Ignored Matter
Empty lines and lines that start with a ‘#’ in the first column are ignored (except in multi-line-values, see below).
Sections
A section starts with a section header. The section header must be the first line in the configuration file, except for empty lines or comments.
The section header starts with a left bracket ‘[’ in the first column. Everything between the opening bracket and the first right bracket ‘]’ in the line is the section name. Any text between that right bracket and the end of the line is ignored. The following are valid section headers:
[section] [ section name with spaces ] [another.section] With some ignored text after the name
For future compatibility, we strongly recommend not writing anything after the closing bracket of the section name. If you want to document a section, write a comment before or after the section header. We also recommend not using spaces in section names, because all spaces are significant, including spaces immediately after the opening bracket and before the closing bracket.
Recommended:
# Documentation for section.1
[section.1]
[section.2]
# Documentation for section.2
Not recommended:
[section] Documentation
[ name with confusing leading and trailing spaces; can you count them? ]
Section names are case-insensitive and case-preserving. This means that, for example, you cannot have two different sections named [Section] and [section]; these are both treated as the same section. This becomes important when a section is reopened (see below).
For compatibility with external tooling, we recommend not relying on case-insensitive section names. For example, Python's configparser treats section names as case-sensitive by default.
The [DEFAULT] Section
The [DEFAULT] section is special: it can be used to define default values for options and is also used for value expansion (see below).
Default values are used when an option is expected to be in a given section but is not defined there. In that case, any option with the same name defined in the [DEFAULT] section is used instead. For example, given the following configuration file:
[DEFAULT] i = √(2, −1) e = √(%(i)s × %(π)s, −1) [rational-approximation] π = 3.1415926535897932384626433832795028841971693993751 ["educational"] π = 3
the value of “e” in section [rational-approximation] will be a quite satisfactory “2.7182818284590…”, but the value from the ["educational"] section will be a sad “2.849653908…” which one might as well round up to the definition of “π” in that section. (That's all assuming that the config parser implemented the function “√(base, argument)”.)
Reopening Sections
A section is implicitly closed when another section header is encountered. However, the section may be reopened by repeating its section header, and new options can be defined or existing options can be redefined. In the following example, [section] ends up containing a single option called “name” whose value is “updated value”.
[section] name = value [another.section] [Section] name = updated value
For compatibility with external tooling, we recommend you do not reopen sections. For example, the ConfigParser module in Python 2 allows that, but configparser in Python 3 does not (by default).
Options
An option is a mapping between a name and a value. Options cannot appear outside of a section. Options in different sections are considered separate even if they have the same name.
There are two valid ways to define an option:
name = value name: value
The option name must start in the first column of the line and stops at the separator (‘=’ or ‘:’). This means that:
- the name cannot start with ‘
[’ or ‘#’, those characters start a section header or a comment; - the name may not contain the separators ‘
=’ or ‘:’.
Spaces around the separator are optional and are ignored.
Option names, like section names, are case-insensitive and case preserving; and like section names, option names may contain spaces. But the warnings against relying on case-insensitivity and the use of spaces apply to option names as well.
The options's value is all the text from the separator character until the end of the line. Leading and trailing spaces around the option value are removed, but spaces within the value are preserved.
Multi-Line Values
An option's value may be broken into several lines. Continuation lines must start with at least one space. Trailing spaces in the previous line, the newline character and the leading spaces in the continuation line are removed and replaced with a single space. In the example at the top of this page, the value of the option “name.2” is “multi-line value”, note the single space where the value was continued in the next line.
Comments and empty lines may not appear in multi-line values.
Value Types
At the syntactic level, option values are strings of characters. But certain settings in the configuration files treat them as either logical (Boolean) values or lists.
Boolean Values
Any of the following strings are recognised as truth values (case does not matter):
| “True” value | “False” value |
|---|---|
true | false |
yes | no |
on | off |
1 | 0 |
Lists
When a value is a list, the list elements are separated by commas ‘,’. Spaces around each element are trimmed and successive commas are merged. That means you can't have a list element that is an empty string. The list in the following example contains three elements, “one”, “two” and “three”.
[section]
list = one, two , ,,
three
Obviously, list elements cannot contain commas.
Note: Some options with list-like values use a different separator (q.v., [auto-props]). Always refer to the specific documentation before you modify any settings.
Value Expansion
Option values may be expanded within another value by enclosing the option's name in parentheses, preceded by a percent sign ‘%’ and followed by an ‘s’:
name.2 = %(name.1)s
The value of the option “name.2” is expanded to the value of “name.1”. Value expansion follows these rules:
- Expansion is performed recursively: e.g., “
name.3” may refer to “name.2” which refers to “name.1”, and all the references will be followed. The referenced option name is first searched for in the same section, and if it is not found there, then in the special
[DEFAULT]section. There is no way to refer to options that are defined in a different section.If the referenced option name is not found, the whole “
%(name)s” placeholder is left unchanged in the value.
Formal Definition
The following is a formal definition of the configuration file syntax, in BNF:
References
- Syntax description in the Subversion source code
- Python's configparser module documentation
- Related issues:
-
SVN-4784
-
Getting issue details...
STATUS
-
SVN-4784
-
Getting issue details...
STATUS