arsd.ini

INI configuration file support

This module provides a configurable INI parser with support for multiple “dialects” of the format.

Getting started

parseIniDocument – Parses a string of INI data and stores the result in a DOM-inspired IniDocument structure.
parseIniAA – Parses a string of INI data and stores the result in an associative array (named sections) of associative arrays (key/value pairs of the section).
parseIniMergedAA – Parses a string of INI data and stores the result in a flat associative array (with all sections merged).
stringifyIni – Serializes an IniDocument or an associative array to a string of data in INI format.

import arsd.ini;

IniDocument!string parseIniFile(string filePath) {
	import std.file : readText;
	return parseIniDocument(readText(filePath));
}

import arsd.ini;

void writeIniFile(string filePath, IniDocument!string document) {
	import std.file : write;
	return write(filePath, stringifyIni(document));
}

More...

Members

Enums

IniDialect enum IniDialect: Feature set to be understood by the parser.
IniTokenType enum IniTokenType: Type of a token (as output by the parser)
isCompatibleString eponymoustemplate isCompatibleString(T): Determines whether a type T is a string type compatible with this library.

Functions

makeIniFilteredParser IniFilteredParser!(dialect, string) makeIniFilteredParser(string rawIni): Convenience function to create a low-level filtered parser
makeIniParser IniParser!(dialect, string) makeIniParser(string rawIni): Convenience function to create a low-level parser
parseIniAA string[immutable(char)[]][immutable(char)[]] parseIniAA(string rawIni): Parses an INI string into an associate array.
parseIniDocument IniDocument!string parseIniDocument(string rawIni): Parses an INI string into a document ("DOM").
parseIniMergedAA string[immutable(char)[]] parseIniMergedAA(string rawIni): Parses an INI string into a section-less associate array. All sections are merged.
resolveIniEscapeSequence char resolveIniEscapeSequence(char c)
resolveIniEscapeSequences string resolveIniEscapeSequences(const(char)[] input): Resolves escape sequences and performs line folding.
stringifyIni void stringifyIni(StringKey key, StringValue value, OutputRange output)
string stringifyIni(StringKey key, StringValue value): Serializes a key + value pair to a string in INI format.
stringifyIni void stringifyIni(IniKeyValuePair!string kvp, OutputRange output)
string stringifyIni(IniKeyValuePair!string kvp): Serializes an IniKeyValuePair to a string in INI format.
stringifyIni void stringifyIni(IniSection!string section, OutputRange output)
string stringifyIni(IniSection!string section): Serializes an IniSection to a string in INI format.
stringifyIni void stringifyIni(IniDocument!string document, OutputRange output)
string stringifyIni(IniDocument!string document): Serializes an IniDocument to a string in INI format.
stringifyIni void stringifyIni(StringValue[StringKey] sectionItems, OutputRange output)
string stringifyIni(StringValue[StringKey] sectionItems): Serializes an AA to a string in INI format.
stringifyIni void stringifyIni(StringValue[StringKey][StringSection] document, OutputRange output)
string stringifyIni(StringValue[StringKey][StringSection] document): Serializes a nested AA to a string in INI format.

Structs

IniDocument struct IniDocument(string): DOM representation of an INI document
IniFilteredParser struct IniFilteredParser(IniDialect dialect = IniDialect.defaults, string = immutable(char)[]): Low-level INI parser with filtered output
IniKeyValuePair struct IniKeyValuePair(string): Data entry of an INI document
IniParser struct IniParser(IniDialect dialect = IniDialect.defaults, string = immutable(char)[]): Low-level INI parser
IniSection struct IniSection(string): Section of an INI document
IniToken struct IniToken(string): Token of INI data (as output by the parser)

Detailed Description

On destructiveness and GC usage

Depending on the dialect and string type, IniParser can operate in one of these three modes:

Non-destructive with no heap alloc (incl. @nogc)
Non-destructive (uses the GC)
Destructive with no heap alloc (incl. @nogc)

a) If a given dialect requests no mutation of the input data (i.e. no escape sequences, no concaternation of substrings etc.) and is therefore possible to implement with slicing operations only, the parser will be non-destructive and not do any heap allocations. Such a parser is verifiably @nogc, too.

b) In cases where a dialect requires data-mutating operations, there are two ways for a parser to implement them:

b.0) Either perform those mutations on the input data itself and alter the contents of that buffer. Because of the destructive nature of this operation, it can be performed only once safely. (Such an implementation could optionally fix up the modified data to become valid and parsable again. Though doing so would come with a performance overhead.)

b.1) Or allocate a new buffer for the result of the operation. This also has the advantage that it works with immutable and const input data. For convenience reasons the GC is used to perform such allocations.

Use IniParser.isDestructive to check for the operating mode.

The construct a non-destructive parser despite a mutable input data, specify const(char)[] as the value of the string template parameter.

char[] mutableInput = [ /* … */ ];
auto parser = makeIniParser!(dialect, const(char)[])(mutableInput);
assert(parser.isDestructive == false);

Examples

// INI example data (e.g. from an `autorun.inf` file)
static immutable string rawIniData =
	"[autorun]\n"
	~ "open=setup.exe\n"
	~ "icon=setup.exe,0\n";

// Parse the document into an associative array:
string[string][string] data = parseIniAA(rawIniData);

string open = data["autorun"]["open"];
string icon = data["autorun"]["icon"];

assert(open == "setup.exe");
assert(icon == "setup.exe,0");

// INI example data (e.g. from an `autorun.inf` file)
static immutable string rawIniData =
	"[autorun]\n"
	~ "open=setup.exe\n"
	~ "icon=setup.exe,0\n";

// Parse the document into a flat associative array.
// (Sections would get merged, but there is only one section in the
// example anyway.)
string[string] data = parseIniMergedAA(rawIniData);

string open = data["open"];
string icon = data["icon"];

assert(open == "setup.exe");
assert(icon == "setup.exe,0");

// INI example data (e.g. from an `autorun.inf` file):
static immutable string rawIniData =
	"[autorun]\n"
	~ "open=setup.exe\n"
	~ "icon=setup.exe,0\n";

// Parse the document.
IniDocument!string document = parseIniDocument(rawIniData);

// Let’s search for the value of an entry `icon` in the `autorun` section.
static string searchAutorunIcon(IniDocument!string document) {
	// Iterate over all sections.
	foreach (IniSection!string section; document.sections) {

		// Search for the `[autorun]` section.
		if (section.name == "autorun") {

			// Iterate over all items in the section.
			foreach (IniKeyValuePair!string item; section.items) {

				// Search for the `icon` entry.
				if (item.key == "icon") {
					// Found!
					return item.value;
				}
			}
		}
	}

	// Not found!
	return null;
}

// Call our search function.
string icon = searchAutorunIcon(document);

// Finally, verify the result.
assert(icon == "setup.exe,0");