Configuring parser behavior

Since the INI format isn't standardized, Ini Parser version 2.0 introduces a simpler way to customize the way an INI file is parsed, and thus providing an easy way to handle all the different format variations.

Using an IniParserConfiguration object you can redefine how the parser will handle special items when parsing an ini file. For example you can redefine the character used as comment so instead of using the character ';' (default) you could set instead that lines starting with the '#' character are comments.

You can also define how the parser should treat errors (e.g. throw exceptions or just return a null value), or how liberal or conservative should it be when parsing files with "strange" formats.

When creating an instance of an IniDataParser you can pass a configuration object. The configuration object follows the . IIniParserConfiguration interface. If you don't provide an instance of an a default one will be used.

You can access and modify the configuration for the parser using the Configuration property in the IniDataParser instance. See the parse_ini_string_with_custom_configuration test for an example.

If you find yourself using a custom configuration in a lot of places, it will be better to create a custom configuration object with the behavior you need. Just create a derived class from BaseIniParserConfiguration and set your custom property's values in the constructor. This is the approach the DefaultIniParserConfiguration actually uses.

This is a list of the configuration options as defined in the IIniParserConfiguration interface specification:

type	Name	Description
bool	AllowCreateSectionsOnFly	If true, if you try to add a key to a non existing section, the section is automatically created on the fly instead of throwing an exception. Defaults to false.
bool	AllowDuplicateKeys	If duplicate keys are find in a section and this is false the parser will stop with an error. If it is true the value of the duplicate key will be the last value asigned to the key. Defaults to false.
bool	AllowDuplicateSections	If set to false and a duplicate section is found, the parser will stop with an error. If set to true, duplicated sections are allowed in the file, but only one SectionData element will be created in the IniData.Sections collection, effectively merging all the keys in the duplicated sections of the same name. Defaults to false.
bool	AllowKeysWithoutSection	Allows having keys in the file that don't belong to any section. i.e. allows defining keys before defining a section. If set to false and keys without a section are defined, the parser will stop with an error. Defaults to true.
string	AssigmentSpacer	Sets the string before and after KeyValuesAssignmentString. Defaults to the string ' '
Regex	CommentRegex	Regular expression used to match a comment string
char	CommentString	Sets the string that will define the beginning of a comment. A comment spans from the comment character to the end of the line. Defaults to "#"
char	KeyValueAssigmentString	Sets the string that separates an assigment of a value to a key. Defaults to "="
bool	OverrideDuplicateKeys	Only applies if AllowDuplicateKeys is true. If set to true when the parser finds a duplicate key, it overwrites the previous value, so the key will always contain the value of the last key readed in the file. If set to false the first readed value is preserved, so the key will always contain the value of the first key read in the file. Defaults to false.
char	SectionEndString	Sets the string that defines the end of a section name. Defaults to "]"
Regex	SectionRegex	Regular expression used to match a section string
char	SectionStartString	Sets the string that defines the start of a section name. Defaults to "["
bool	SkipInvalidLines	If set to true, when the parser finds an invalid line, it just skips it instead of throwing a ParseException or returning null when parsing (if exceptions are disabled because the property ThrowExceptionsOnError is set to false). Defaults to false
bool	ThrowExceptionsOnError	If true the parser will thrown an exception if an error is found. If false the parser will just stop execution and return a null value as result . Defaults to true.
string	NewLineStr	The string to use as NewLine. Used only when creating an ini string from an IniData structure, using an IIniDataFormatter This allows, for example, to create ini files with unix-like endline strings on windows. The default value is the correct new line character/string used for the system this library is executing on.

If you need a fine grainer customization for the parsing, you can create a derived class from IniDataParser and overwrite some methods. Please see the page Modifying Parser