SharpINI 1.0.0

SharpINI - A simple INI Reader/Writer for C#

SharpINI is a simple .NET Standard 2.0 compatible library to parse and write INI strings.

INIs are somehow a problematic format, since there is no global standard like for JSON or XML. There are so many implementations that parse the files using different rules. This library tries to provide an interface with parsing options to parse some of the INI files out there without creating too much complexity.

Flexibility

This library allows the following things to be defined while parsing:

• Space chars
• Line breaks (limited)
• Comment chars (only at the beginning of a line)
• Behaviour when there are multiple sections with the same name
• Behaviour when there are multiple keys in a section with the same name
• Behaviour when there are strings outside of a section (when no section has been started)
• Removing spaces before and after value

General parsing rules

These rules are hard and cannot be changed using parsing options

• Any space at the start of a line is removed
• Any space between the key of a key-value-pair and the = is removed
• Section titles must not contain closing brackets (]) in their name
• Any line must be a section title, a key-value pair, an empty line (filled with space) or a comment line

Reading

SharpINI parses the string into the following format:

• Each Section is represented as Dictionary<string, string>
• The INI file is represented as Dictionary<string, Dictionary<string, string>>

Basic reading

using SharpINI;

var myINIString = @"[MySection]
Key1=val1
Key2=val2

[MySection2]
Key1=val3
Key2=val4";

var parsed = INIReader.ReadINI(myINIString);
/*parsed:
[
	[MySection,
		[Key1, val1]
		[Key2, val2]
	],
	[MySection2,
		[Key1, val3]
		[Key2, val4]
	]
]
*/

var key = parsed["MySection"]["Key1"]; // => "val1"

Reading with options

using SharpINI;

var myINIString = @"[MySection]
Key1=val1
Key2=val2

[MySection]
Key1=val3
Key3=val4";


var options = new ParseOptions(multiSectionMode: MultiSectionMode.MERGE,
                               multiKeyMode: MultiKeyMode.OVERRIDE);

var parsed = INIReader.ReadINI(myINIString, options);
/*parsed:
[
	[MySection,
		[Key1, val3]
		[Key2, val2]
		[Key3, val4]
	]
]
*/

Parse options

Writing

When writing INI files, SharpINI accepts the same object type like it produces while reading: Dictionary<string, Dictionary<string, string>>

Basic writing

using SharpINI;

var iniString = INIWriter.WriteINI(parsed);
/*iniString: @"[MySection]
Key1 = val1
Key2 = val2

[MySection2]
Key1 = val3
Key2 = val4"
*/

As you see, there are now spaces before and after the =. You can define such render/write options using RenderOptions which are passed to WriteINI.

Writing with options

using SharpINI;

var options = new RenderOptions(spaceAfterKey: false,
                                spaceBeforeValue: false,
                                linesBetweenSections: 0);

var iniString = INIWriter.WriteINI(parsed, options);
/*iniString: @"[MySection]
Key1=val1
Key2=val2
[MySection2]
Key1=val3
Key2=val4"
*/

RenderOptions

Convert parse options to render options

You can generate a RenderOptions object from your ParseOptions by calling the method parseOptions.ToRenderOptions(). This will convert your parse options to render options.

Following values are converted:

• lineBreak (first line break string)
• space (first space char)
• spaceAfterKey, based on trimSpaceBeforeValue
• spaceBeforeValue, based on trimSpaceBeforeValue
• initialSelectionName

Using internal methods

Beside ReadINI, INIReader contains methods like ReadSectionTitle and ReadKeyValue. These methods are used internally. If you want to use these methods for whatever reason, you have to tell SharpINI to perform additional checks in these methods, as by default they omit checks done by the SharpINI-caller method. To announce the usage of these methods, compile the library with the SHARE_INTERNAL_METHODS flag (obviously not possible when using the precompiled NuGet package).

To be more performant, the reading is done by simply moving a cursor over the string, so that a new substring does not have to be created for each element. This string-shifting is done by the internal class StringView. This class is also only shown if you activate the compiliation flag SHARE_INTERNAL_METHODS. So for using the internal methods, you have to create a StringView instance.

License

SharpINI is licensed under the MIT License