ConfigParser API

The ConfigParser module provides a parser for INI-like files. For more information (including usage examples), visit the ConfigParser Info page.

Classes

ConfigParser

This is the main class that you'll be interacting with. It contains methods for reading from files and accessing the various information stored in the provided file.

this(char[] delimiters = ['=', ':'], char[] commentPrefixes = ['#', ';'], bool strict = true)

The only constructor for a ConfigParser. The delimiters parameter defines which characters to use for separating a key and option pair. The commentPrefixes parameter defines which characters are to be treated as prefixes to comment in an otherwise empty line.

By setting strict to true (the default), the parser will not allow any duplicate sections or options when parsing an input. It'll raise DuplicateOptionException or DuplicateSectionException

sections()

Returns an array of strings containing all the present sections.

addSection(string section)

Adds the section section to the instance. If the section already exists, DuplicateSectionException is thrown.

hasSection(string section)

Check if the instance has the given section. Returns true if it is present, false otherwise.

options(string section)

Returns an array of string containing all the present options for a given section.

hasOption(string section, string option)

Check if a given section contains the specified option. Returns true if it's present, otherwise false.

read(string filename)

Attempt to read a file located at filename. If the filename doesn't exist then ErrnoException is thrown.

If the file can be read from, then this instance is populated with the options in filename.

read(ref File file, bool close = true)

Attempt to read a file which is already open. You can specify if you want the file to be closed upon completion of parsing by setting close.

get(string section, string option)

Retrieve the string value of an option from a specified section.

If the section isn't present, NoSectionException is thrown. If the option doesn't exist, then NoOptionException is thrown.

get(string section, string option, string fallback)

Retrieve the string value of an option from a specified section.

If neither the section or option exist, then the falback is returned.

getInt(string section, string option)

A convenience function which returns the integer value of the option found in section.

If the section isn't found, then NoSectionException is thrown. If the option doesn't exist, then NoOptionException is thrown.

If the value cannot be parsed as an integer, then ConvException or ConvOverflowException are thrown—depending on if the value would overflow an integer.

getInt(string section, string option, int fallback)

A convenience function which returns the integer value of the option found in section.

If there are any errors in retrieving the integer value (e.g. can't find the section, or the value isn't an integer) then fallback is returned.

getBool(string section, string option)

A convenience function which returns a boolean value for the option found in section.

Note that the accepted values for boolean options are: "1", "yes", "true", and "on", which cause this method to return true and "0", "no", "false", and "off", which cause it to return false.

If the section isn't found, then NoSectionException is thrown. If the option doesn't exist, then NoOptionException is thrown.

If the value cannot be parsed as a boolean as per the above list, then ConvException is thrown.

getBool(string section, string option, bool fallback)

A convenience function which returns a boolean value for the option found in section.

If there are any errors in retrieving the boolean value (e.g. can't find the section, or the value can't be converted to a boolean) then fallback is returned.

removeOption(string section, string option)

Remove the specified option from the chosen section. This will return true if the option existed and was removed, otherwise it'll return false.

If the section doesn't exist, then NoSectionException is thrown.

removeSection(string section)

Remove the specified section from the configuration. This will return true if the section existed and was removed, false otherwise.

set(string section, string option, string value)

Set the value of option to value in the chosen section.

If the section doesn't exist, then NoSectionException is thrown.

write(ref File file, bool spaceAroundDelimiters = true)

Write a representation of the configuration to the provided file, which must be open and in writing text mode. The representation can be parsed by future calls to read. If spaceAroundDelimiters is true, then delimiters between keys and values are surrounded by spaces.

Note: Comments from the original file are not preserved when writing the configuration back.

Exceptions

DuplicateOptionException

This exception is thrown if a strict parser encounters a option which is already present in the current section.

DuplicateSectionException

This exception is thrown if addSection() is called with the name of a section that is already present or in strict parsers when a section if found more than once in a single input file, string or dictionary.

NoOptionException

This exception is thrown if a specific option in a specified section does not exist in the configuration.

NoSectionException

This exception is thrown if a specified section does not exist in the configuration.