Specialization of class InMemoryPlugin, which reads and writes a simple configuration file consisting of sections containing key/value pairs.
This class is provided for the case that no other configuration mechanism is available. In general, application specific configuration mechanisms already exist in other libraries used. Those should be adopted by creating a lean interface plug-in for ALib.
Some remarks on the functionality and supported format:
- Comments
- Comment lines at the beginning of the file are associated with the file and are written back. Such comment block is stopped with a single blank line.
- Lines that start (apart from whitespace) with either a double slash
"//", a sharp sign '#' or a semicolon ';' are comment lines.
- Comment lines that are added to variables in the software are using the symbol defined in filed defaultCommentPrefix, which defaults to
'#'. If this is changed in the file, such changes are preserved.
- Comment lines before sections and variables are associated with the respective objects and are not overwritten by comments set in the code. However, variables without comments which are overwritten in code including comments, get such comment appended.
- Comments can not reside in the same line together with section names or variables.
- Commented variables receive a blank line before the comment.
- Commented Sections receive two blank lines before the comment. One if they are not commented.
- Sections:
- Sections names are enclosed by brackets
'[' and ']'.
- Section names can be repeated. In this case the corresponding section is continued. When the file is written, the sections are merged. Otherwise the order of sections and the variables within the section is kept intact on writing.
- Variables
- Variable names and their values are separated by an equal sign
'='.
- New variables inserted are formatted according to other variables found. E.g. the equal sign of all variables within a section are aligned on the same column.
- Formats of variables added or changed by the user are kept intact, as long as the software does not store a value.
- Continued Lines:
- Variables definition are being continued (values are concatenated) if the line ends with a backslash
'\'.
- Comment lines in-between continued lines are recognized as such. To continue a variable after a 'continued' comment line, the comment line needs to end with a backslash
'\'.
- Variables with multiple values created (or modified) in the software, are written in continued lines, with each line showing one value, ending with the variables' delimiter character and a trailing
'\'.
- Comment lines within Variables defined in multiple lines are removed when a variable is written back.
- Escaping values
- Spaces
' ' and tabulators '\t' are ignored at the start and end of each line and before and after the equal sign '='.
- Consequently, whitespaces at the start or end of a value either need to be escaped using
'\ ' or the whole value has to be surrounded by double quotes ".
- Values added or modified by the software that contain spaces at the start or end are surrounded by double quotes (instead of escaping them)
- Double quotes in values are always escaped when writing values and have to be escaped when editing the file.
- Values may consist of a list of double quoted values. Whitespaces between such values are ignored. Consequently, long strings may be enclosed in double quotes and continued in the next line when the line ends with a backslash
'\'.
- Almost any character can be escaped. E.g
"\a" is read as 'a'.
- On writing only non-printable characters and double quotation marks are escaped.
- Other remarks
- Sequences of blank lines are reduced to one blank line, when writing the file.
- Erroneous lines are ignored and not written back. Line numbers with erroneous lines are collected in field linesWithReadErrors.
Public Fields inherited from InMemoryPlugin
1.8.16