IniFile Class Reference

Inheritance diagram for IniFile:

Collaboration diagram for IniFile:

Class Description

---

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 Types
enum	Status { OK, ERROR_OPENING_FILE, ERROR_WRITING_FILE }

Inner Classes
class	Entry
class	Section

Public Static Fields
static String	DefaultFileExtension = ".ini"

Public Fields
bool	AutoSave = false
String	DefaultCommentPrefix = "# "
AString	FileComments = new AString()
AString	FileName = new AString()
bool	FormatIncludeDelimInAttrAlignment = false
bool	FormatSpaceAfterDelim = true
bool	FormatSpaceBeforeDelim = false
Status	LastStatus = Status.OK
List< int >	LinesWithReadErrors = new List<int>()
Public Fields inherited from InMemoryPlugin
List< Section >	Sections = new List<Section>()
Public Fields inherited from ConfigurationPlugin
XTernalizer	StringConverter

Public Methods
	IniFile (String filePathAndName=null)
IniFile.Status	ReadFile ()
override void	Reset ()
override bool	Store (Variable variable)
IniFile.Status	WriteFile ()
Public Methods inherited from InMemoryPlugin
	InMemoryPlugin ()
override bool	Load (Variable variable, bool searchOnly=false)
Section	SearchOrCreateSection (Object name, AString comments)
Section	SearchSection (Object name)
override bool	Store (Variable variable)
Public Methods inherited from ConfigurationPlugin
virtual bool	Store (Variable variable, Object externalizedValue)

Protected Fields
AString	commentChars = new AString( "#;/" )
Protected Fields inherited from ConfigurationPlugin
XTernalizer	defaultStringConverter = new XTernalizer()

Protected Static Methods
static int	getAssignmentPos (AString value, String alignmentSeparator)

Protected Methods
override InMemoryPlugin.Section	createSection (Object name)
bool	startsWithCommentSymbol (Substring subs)
void	writeComments (TextWriter os, AString comments, Tokenizer tknzr)
Protected Methods inherited from ConfigurationPlugin
	ConfigurationPlugin ()

Member Enumeration Documentation

Status

enum Status

strong

---

Status codes

Enumerator
OK	All went well
ERROR_OPENING_FILE	File not found when reading. This is not necessarily an error.
ERROR_WRITING_FILE	An error occurred writing the file .

Constructor & Destructor Documentation

IniFile()

IniFile ( String  filePathAndName = null )

inline

---

Constructs an instance of this class and reads the file. If no file name is given, the file name set to the process name with extension ".ini" while the file path is retrieved using Environment.GetFolderPath( Environment.SpecialFolder.ApplicationData ).

If the given file name filePathAndName starts with '*', no file is read and field AutoSave is set to false.

Parameters

filePathAndName

The name (and path) of the file to read and write. Provide "*" to suppress reading a file. Defaults to null.

Member Function Documentation

createSection()

override InMemoryPlugin.Section createSection ( Object  name )

inlineprotectedvirtual

---

Overrides base classes method to create a section of our type.

Parameters

name	The name of the section.

Returns

An object of type IniFile.Section.

Reimplemented from InMemoryPlugin.

getAssignmentPos()

static int getAssignmentPos ( AString  value, String  alignmentSeparator  )

inlinestaticprotected

---

Helper method for formatting attributes

Parameters

value	The value to check
alignmentSeparator	The string defining the separator.

Returns

Returns the position of the first '=' or ':' character

ReadFile()

IniFile.Status ReadFile ( )

inline

---

Clears all configuration data and reads the file. It might happen that lines are ignored or otherwise marked as faulty. All numbers of such lines get collected in field LinesWithReadErrors.

Returns

Returns the Status of the operation.

Reset()

override void Reset ( )

inlinevirtual

---

Clears all configuration data.

Reimplemented from InMemoryPlugin.

startsWithCommentSymbol()

bool startsWithCommentSymbol ( Substring  subs )

inlineprotected

---

Helper method used when reading file.

Parameters

subs	A sub-string.

Returns

true if provided substring starts with comment character.

Store()

override bool Store ( Variable  variable )

inlinevirtual

---

Creates or replaces existing variable in our storage. If AutoSave is set, the file is written

Parameters

variable

The variable to retrieve.

Returns

true if the variable was written, false if not. The latter might only happen if the variable given was illegal, e.g. empty name.

Reimplemented from ConfigurationPlugin.

writeComments()

void writeComments ( TextWriter  os, AString  comments, Tokenizer  tknzr  )

inlineprotected

---

Writes a list of comments to the file. Comment lines are started with '#'.

Parameters

os	The output stream to write to.
comments	The comment lines for the section.
tknzr	A temporary tokenizer needed internally.

WriteFile()

IniFile.Status WriteFile ( )

inline

---

Write all configuration data into the file.

Returns

Returns the Status of the operation.

Member Data Documentation

AutoSave

bool AutoSave = false

If this is set to true, any variable change will lead to writing the file immediately by invoking WriteFile. Defaults to false

commentChars

AString commentChars = new AString( "#;/" )

protected

Characters that start a comment

DefaultCommentPrefix

String DefaultCommentPrefix = "# "

The prefix that is used for comment lines of sections or variables that have been added 'in code' (variables that have not been read from the file). Comments that were read from the file preserve their prefix. If comments including one of the valid prefixes are added to a variable or section 'in code', such prefix is preserved.

DefaultFileExtension

String DefaultFileExtension = ".ini"

static

The standard file extension used for ALib configuration files. Defaults to ".ini"

FileComments

AString FileComments = new AString()

The file header which will be written out as a comment lines with "# " prefixes

FileName

AString FileName = new AString()

The file name. This might include a path or not. Should be set properly before the file is read.

FormatIncludeDelimInAttrAlignment

bool FormatIncludeDelimInAttrAlignment = false

Denotes whether the spaces that are inserted when aligning attributes are located before or behind the delimiter.

FormatSpaceAfterDelim

bool FormatSpaceAfterDelim = true

Denotes if a space should be written after a delimiter. (Applies only to single line mode of writing attributes.)

FormatSpaceBeforeDelim

bool FormatSpaceBeforeDelim = false

Denotes if a space should be written before a delimiter.

LastStatus

Status LastStatus = Status.OK

The status.

LinesWithReadErrors

List<int> LinesWithReadErrors = new List<int>()

Is cleared and filled with faulty line numbers when reading the file. (E.g. when a line is no section and no comment but still has no equal sign ('=').

---

The documentation for this class was generated from the following file:

• IniFile.cs