Rose Configuration Format§
A configuration in Rose is normally represented by a directory with the following:
- a configuration file in a modified INI format.
- (optionally) files containing data that cannot easily be represented by the INI format.
We have added the following conventions into the Rose configuration format:
The file name is normally called
rose*.conf, e.g.rose.conf,rose-app.conf,rose-meta.conf, etc.Only a hash
#in the beginning of a line starts a comment. Empty lines and lines with only white spaces are ignored. There is no support for trailing comments. Comments are normally ignored when a configuration file is loaded. However, some comments are loaded if the following conditions are met:- Comment lines at the beginning of a configuration file up to but not including the 1st blank line or the 1st setting are comment lines associated with the file. They will re-appear at the top of the file when it is re-dumped.
- Comment lines between a blank line and the next setting, and the comment lines between the previous setting and the next setting are comments associated with the next setting. The comment lines associated with a setting will re-appear before the setting when the file is re-dumped.
Only the equal sign
=is used to delimit a key-value pair - because the colon:may be used in keys of namelist declarations.A key-value pair declaration does not have to live under a section declaration. Such a declaration lives directly under the root level.
Key-value pair declarations following a line with only
[]are placed directly under the root level.Declarations are case sensitive. When dealing with case-insensitive inputs such as Fortran logicals or numbers in scientific notation, lowercase values should be used.
When writing namelist inputs, keys should be lowercase.
Declarations start at column 1. Continuations start at column >1.
- Each line is stripped of leading and trailing spaces.
- A newline
\ncharacter is prefixed to each continuation line. - If a continuation line has a leading equal sign
=character, it is stripped from the line. This is useful for retaining leading white spaces in a continuation line.
A single exclamation
!or a double exclamation!!in front of a section (i.e.[!SECTION]) or key=value pair (i.e.!key=value) denotes an ignored setting.- E.g. It will be ignored in run time but may be used by other Rose utilities.
- A single exclamation denotes a user-ignored setting.
- A double exclamation denotes a program-ignored setting. E.g. rose config-edit may use a double exclamation to switch off a setting according to the setting metadata.
The open square bracket (
[) and close square bracket (]) characters cannot be used within a section declaration. E.g.[[hello],[hello]],[hello [world] and beyond]should all be errors on parsing.If a section is declared twice in a file, the later section will append settings to the earlier one. If the same key in the same section is declared twice, the later value will override the earlier one. This logic applies to the state of a setting as well.
Once the file is parsed, declaration ordering is insignificant.
Note
Do not assume order of environment variables.
Values of settings accept syntax such as
$NAMEor${NAME}for environment variable substitution.
E.g.
# This is line 1 of the comment for this file.
# This is line 2 of the comment for this file.
# This comment will be ignored.
# This is a comment for section-1.
[section-1]
# This is a comment for key-1.
key-1=value 1
# This comment will be ignored.
# This is line 1 of the comment for key-2.
# This is line 2 of the comment for key-2.
key-2=value 2 line 1
value 2 line 2
# This is a comment for key-3.
key-3=value 3 line 1
= value 3 line 2 has leading indentation.
=
= value 3 line 3 is blank. This is line 4.
# section-2 is user-ignored.
[!section-2]
key-4=value 4
# ...
[section-3]
# key-5 is program ignored.
!!key-5=value 5
Note
In this document, the shorthand SECTION=KEY=VALUE is used to represent a
KEY=VALUE pair in a [SECTION] of an INI format file.