IniFileNet 0.8.0

IniFileNet

A .NET Library for reading and writing ini files.

Usage

Note that because this package is currently not at 1.0 yet, this may change. Below is some example code.

The IniStreamReader class lets you read individual sections, keys and values, and comments. This is ideal when you want fine control and handling over the parts of the ini file. The IniStreamSectionReader wraps that class and groups keys and values up into sections for you. This is useful when you want to handle individual sections manually, and is fairly concise. The IniDictionaryReader can read the entirety of a file into a Dictionary, keyed by strings. The value is typically either string or List<string>, but can be made anything you want.

You can use instances of IIniValueAcceptor to accept values with specific keys from a section, which helps parsing destination types and validating that everything loads correctly.

Example ini File 1

[GUI]
scaling factor = 1
subtitles = true
colour topic enable = true

[Map]
allow zooming = true
global = true

IniDictionaryReader Usage

using (IniStreamReader iniIn = new IniStreamReader(new StreamReader(new FileStream(args[0], FileMode.Open, FileAccess.Read), Encoding.UTF8), DefaultIniTextEscaper.Default, new IniReaderOptions(ignoreComments: true, trimKeys: true, trimValues: true)))
{
	// You can pass in your own dictionary. Or use the parameterless constructor, which makes a dictionary for you
	IniDictionaryReader<string> reader = new();

	// Load with the delegate that only allows unique keys. The full keys are like: Section.Key
	reader.Load(iniIn, IniDictionaryReader.StringSingle).ThrowIfError();

	Dictionary<string, string> dict = reader.Dictionary;

	// This single dictionary for an entire ini stream tends to work better if everything is uniquely addressed.
	// For our example this works great, but ini files with repeating similar sections may be better served by the below examples.

	// We trimmed our values and keys using the options
	string scalingFactor = dict["GUI.scaling factor"];
	string subtitles = dict["GUI.subtitles"];
	string colourTopicEnable = dict["GUI.colour topic enable"];
	string allowZooming = dict["Map.allow zooming"];
	string global = dict["Map.global"];
}

Example ini File 2

[Section1]
Url=https://example.com
OutputTemplate=Hello there {{Person}}, how are you?
Attempts=5
Ask=true
Regex=PersonName:(.+)
LastSeen=2005-07-12T12:41:00Z

[Section2]
Url=https://example.com
OutputTemplate=Hello there {{Person}}, how are you?
Attempts=5
Ask=true
Regex=PersonName:(.+)
LastSeen=2005-07-12T12:41:00Z

[Section3]
Url=https://example.com
OutputTemplate=Hello there {{Person}}, how are you?
Attempts=5
Ask=true
Regex=PersonName:(.+)
LastSeen=2005-07-12T12:41:00Z

IniStreamSectionReader Usage

List<Target> targets = [];
using (IniStreamSectionReader iniIn = new(new IniStreamReader(new StreamReader(new FileStream(args[0], FileMode.Open, FileAccess.Read), Encoding.UTF8), DefaultIniTextEscaper.Default, new IniReaderOptions(ignoreComments: true))))
{
	// Coding like this emphasizes turning IniErrors into Exceptions and throwing them, which can be useful for concise code if an error in loading an ini file should mean the app crashes (or the Exception gets caught)
	while (iniIn.Error.Code == IniErrorCode.None)
	{
		// Reads a section and throws an exception on any error
		SectionAsDictionary section = iniIn.ReadNewSectionDictionary(DuplicateKeyBevahiour.Error).ValueOrException();

		// Ignore global properties
		if (section.Name == "") continue;

		Dictionary<string, string> keyValues = section.KeyValues;
		targets.Add(new Target
		(
			name: section.Name,
			url: keyValues["Url"],
			outputTemplate: keyValues["OutputTemplate"],
			ask: bool.Parse(keyValues["Ask"]),
			attempts: int.Parse(keyValues["Attempts"]),
			regex: new Regex(keyValues["Regex"]),
			lastSeen: DateTimeOffset.Parse(keyValues["LastSeen"])
		));
	}
	iniIn.Error.ThrowIfError();
}

IIniValueAcceptor Usage

List<Target> targets = [];
using (IniStreamSectionReader iniIn = new(new IniStreamReader(new StreamReader(new FileStream(args[0], FileMode.Open, FileAccess.Read), Encoding.UTF8), DefaultIniTextEscaper.Default, new IniReaderOptions(ignoreComments: true))))
{
	IniValueAcceptorDictionaryBuilder b = new(new Dictionary<string, IIniValueAcceptor>(StringComparer.OrdinalIgnoreCase));
	IniValueAcceptorOnlyLast url = b.OnlyLast("Url");
	IniValueAcceptorOnlyFirst outputTemplate = b.OnlyFirst("OutputTemplate");
	IniValueAcceptorSingle<int> attempts = b.Single("Attempts", IniParse.Int32);
	IniValueAcceptorSingle<bool> ask = b.Single("Ask", IniParse.Boolean);
	IniValueAcceptorOnlyLast<Regex?> regex = b.OnlyLast("Regex", (string value) =>
	{
		try
		{
			return new IniResult<Regex?>(new Regex(value), default);
		}
		catch (Exception ex)
		{
			return new IniResult<Regex?>(null, new IniError(IniErrorCode.ValueInvalid, string.Concat("Could not parse \"", value, "\" as Regex: ", ex.Message)));
		}
	});
	IniValueAcceptorOnlyLast<DateTimeOffset> lastSeen = b.OnlyLast("LastSeen", (string value) => DateTimeOffset.TryParse(value, out var r)
		? new IniResult<DateTimeOffset>(r, default)
		: new IniResult<DateTimeOffset>(default, new(IniErrorCode.ValueInvalid, string.Concat("Could not parse \"", value, "\" as DateTimeOffset"))));
	Dictionary<string, IIniValueAcceptor> acceptors = b.Acceptors;
	while (iniIn.NextSection())
	{
		ReadOnlyIniSection section = iniIn.Section;
		IniError err = section.AcceptAll(acceptors);
		// Can explicitly do it this way
		if (err.Code != default)
		{
			Console.WriteLine("Error reading ini file: " + err.Msg);
			throw err.ToException();
		}
		// Or just call this
		err.ThrowIfError();

		targets.Add(new Target
		(
			name: section.Name,
			url: url.ValueOrException(),
			outputTemplate: outputTemplate.ValueOrException(),
			attempts: attempts.Value,
			ask: ask.Value,
			regex: regex.Value,
			lastSeen: lastSeen.Value
		));
		IniUtil.ResetAll(acceptors.Values);
	}
	iniIn.Error.ThrowIfError();
}