configparse

Configuration file parsing, in the style of Python's ConfigParser.

Config files are divided into sections, which contain options. Section headers are in the form "[section name]". Options may be in either the form "key=value" or "key: value". A given line may only contain a single option or section header. Whitespace is stripped from the beginnings and ends of keys and values.

Options existing before any section headers are said to be in the global section. This is treated as a section named "General". It is entirely possible to use config files only containing options that are in the global section, and to write code which doesn't even seem to know about the ability to divide options into sections.

Lines beginning with '#' or ';' are treated as comments and ignored.

class ConfigParseError: object.Exception;
Thrown when configparse is unable to parse a file.

class ConfigConvertError: object.Exception;
Thrown when configparse is unable to coerce a value to a requested type.

class DuplicateSectionError: object.Exception;
Thrown when user adds already-existing section to parser.

class SectionNotFoundError: object.Exception;
Thrown when a section is not found.

class OptionNotFoundError: object.Exception;
Thrown when an option is not found.

const char[] GLOBAL_SECTION;
The name of the global section. This is currently "General".

char[] same_dir(char[] arg0, char[] filename);
Returns the path of a config file (filename) in the same directory as the executable (arg0).

char[][] config_files(char[] arg0, char[] name = null);
Returns a nice "default" list of config files. arg0 should be the first element of the args array passed to main(). The optional name parameter should be the name of the config file, minus any extension. It defaults to the executable's name, minus any directory or extension.

On Windows, the returned filenames are:

On all other platforms (e.g. Linux), the returned filenames are:

class ConfigParser;
The ConfigParser class represents a config file.

char[][] sections();
Returns a list of the sections in the parser, including the global section. ("General" by default.)

void add_section(char[] name);
Adds a section named name to the parser.

Throws:
DuplicateSectionError if the section already exists.

bool has_section(char[] name);
Requests if a section exists in the parser.

char[][] options(char[] section = "General");
Returns a list of options in the given section.

Throws:
SectionNotFoundError

char[][] values(char[] section = "General");
Returns a list of values in the given section.

Throws:
SectionNotFoundError

bool has_option(char[] section, char[] option = null);
Returns whether the given option exists in the given section. This method (and all of the others in this form) will set option to section, and section to the global section, when only one argument is provided. (In other words, providing only one argument will check for options in the global section.) This will silently return false if the section does not exist.

char[][] read(char[][] filenames...);
Reads a series of files into the parser, in the order provided. Files that don't exist will be silently skipped. Options specified in later files will override those specified in earlier files.

Returns:
A list of files read in.

Throws:
ConfigParseError if a file contains errors.

void read(Stream file, char[] filename = "");
Reads in any Stream as a config file.

Params:
char[] filename An optional argument for clarifying error output.

Throws:
ConfigParseError if the stream contains errors.

char[] opIndex(char[] section, char[] option = null);
Retrieves the value of an option in the given section. If only one argument is supplied, it is treated as an option in the global section.

Throws:
SectionNotFoundError if the section doesn't exist. OptionNotFoundError if the option doesn't exist.

alias get;
An alias of opIndex.

int getint(char[] section, char[] option = null);
Retrieves the value of an option in the given section in a manner identical to opIndex, and attempts to convert it to an integer.

Throws:
ConfigConvertError if the value cannot be converted.

real getreal(char[] section, char[] option = null);
Retrieves the value of an option in the given section in a manner identical to opIndex, and attempts to convert it to a real.

Throws:
ConfigConvertError if the value cannot be converted.

bool getbool(char[] section, char[] option = null);
Retrieves the value of an option in the given section in a manner identical to opIndex, and attempts to convert it to a boolean. The value is first converted to lower-case. The accepted values for true are "yes," "true," "on," and "1." The accepted values for false are "no," "false," "off," and "0."

Throws:
ConfigConvertError if the value cannot be converted.

void opIndexAssign(char[] value, char[] section, char[] option = null);
Stores value to option in section. If option is not supplied, section is treated like an option in the global section.

Throws:
SectionNotFoundError if section does not exist.

void opIndexAssign(int value, char[] section, char[] option = null);
Calls opIndexAssign after converting value to a string.

void opIndexAssign(real value, char[] section, char[] option = null);
Calls opIndexAssign after converting value to a string.

void opIndexAssign(bool value, char[] section, char[] option = null);
Calls opIndexAssign after converting value to a string.

void remove_option(char[] section, char[] option = null);
Removes the specified option in section. Silently does nothing if option does not exist.

Throws:
SectionNotFoundError if the section does not exist.

void remove_section(char[] section);
Removes section. Silently does nothing if section does not exist.

void write(Stream file);
Writes the config file to file. Note that ConfigParser does not preserve the ordering of options or sections, although it will always write the global section first.

void write(char[] filename);
Writes the config file to the file specified by filename. If the file already exists, it is erased and written over. If it does not exist, it is created.

Page generated by Ddoc.