root/misc/configparse.d

/*
Copyright (c) 2007 Kirk McDonald

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
*/
/++
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.
+/
module configparse;

version (Tango) {
    // Although I've placed these Tango imports here, Tango support is
    // incomplete.
    import tango.io.FileSystem : FileSystem;
    import tango.io.FilePath : FilePath;
    import tango.io.FileProxy : FileProxy;
    import tango.text.Util : locatePrior, split;
    import tango.stdc.stdlib : getenv, strlen;
    version (Windows) {
        const char[] SystemPathSeperator = ";";
    } else {
        const char[] SystemPathSeperator = ":";
    }
} else {
    import std.stream : Stream, BufferedFile, FileMode;
    import std.string : find, strip, toString, tolower, split;
    import std.file : exists;
    import std.conv : toInt, toReal, ConvError;
    import std.path : getBaseName, getDirName, join, pathsep;
    import std.c.stdlib : getenv;
    import std.c.string : strlen;
}

/// Thrown when configparse is unable to parse a file.
class ConfigParseError : Exception {
    this(char[] msg) { super(msg); }
}
/// Thrown when configparse is unable to coerce a value to a requested type.
class ConfigConvertError : Exception {
    this(char[] msg) { super(msg); }
}
/// Thrown when user adds already-existing section to parser.
class DuplicateSectionError : Exception {
    this(char[] msg) { super(msg); }
}
/// Thrown when a section is not found.
class SectionNotFoundError : Exception {
    this(char[] msg) { super(msg); }
}
/// Thrown when an option is not found.
class OptionNotFoundError : Exception {
    this(char[] msg) { super(msg); }
}

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

/*
A brief note about arg0:

The first element of the args array differs based on operating system and which
library (Phobos or Tango) is in use. In most cases, arg0 is the precise string
used to start the program. In Phobos on Windows, arg0 is always the complete
path to the EXE.
*/

// Returns the name of the executable, minus directories.
version (Tango) {
    char[] get_program_name(char[] path) {
        version(Windows) {
            char delimiter = '\\';
        } else {
            char delimiter = '/';
        }
        uint idx = locatePrior(path, delimiter);
        if (idx == path.length) return path;
        return path[idx+1 .. $];
    }
} else {
    char[] get_program_name(char[] path) {
        version(Windows) {
            // (Unicode note: ".exe" only contains 4 code units, so this slice
            // should Just Work.) (Although it remains to be seen how robust
            // this code actually is.)
            assert(path[$-4 .. $] == ".exe");
            path = path[0 .. $-4];
        }
        return getBaseName(path);
    }
}
char[] env(char* var) {
    char* s = getenv(var);
    return s[0 .. strlen(s)];
}
/++
Returns the path of a config file (filename) in the same directory as the
executable (arg0).
+/
char[] same_dir(char[] arg0, char[] filename) {
    version (Tango) {
        scope binary = new FilePath(arg0);
        scope file = new FilePath(filename);
        char[] dir = binary.getPath();
        scope bin_name = new FilePath(binary.getFullName());
        if (dir == "") {
            char[][] paths = split(env("PATH"), SystemPathSeparator);
            foreach (path; paths) {
                if ((new FileProxy(bin_name.join(path))).isExisting())
                    return file.join(path).toUtf8();
            }
            return "";
        } else {
            return file.join(dir);
        }
    } else {
        version (Windows) {
            return join(getDirName(arg0), filename);
        } else {
            char[] dir = getDirName(arg0);
            if (dir == "") {
                char[][] paths = split(env("PATH"), pathsep);
                foreach (path; paths) {
                    if (exists(join(path, getBaseName(arg0))))
                        return join(path, filename);
                }
                return "";
            } else {
                return join(dir, filename);
            }
        }
    }
}
/++
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:
$(UL
    $(LI name.ini alongside the .exe)
    $(LI %HOMEDRIVE%%HOMEPATH%\name.ini)
    $(LI .\name.ini)
)

On all other platforms (e.g. Linux), the returned filenames are:
$(UL
    $(LI /etc/name.conf)
    $(LI name.ini alongside the binary)
    $(LI ~/.namerc)
    $(LI ./name.conf)
)
+/
char[][] config_files(char[] arg0, char[] name=null) {
    if (name is null) name = get_program_name(arg0);
    version (Windows) {
        name ~= ".ini";
        return [
            same_dir(arg0, name),
            env("HOMEDRIVE")~env("HOMEPATH")~"\\"~name,
            name
        ];
    } else {
        return [
            "/etc/"~name~".conf",
            same_dir(arg0, name~".ini"),
            "~/."~name~"rc",
            name~".conf"
        ];
    }
}

/++
The ConfigParser class represents a config file.
+/
class ConfigParser {
    char[][char[]][char[]] config;
    this() {
        config[GLOBAL_SECTION] = null;
    }

    /++
    Returns a list of the _sections in the parser, including the global
    section. ("General" by default.)
    +/
    char[][] sections() {
        return this.config.keys;
    }
    /++
    Adds a section named name to the parser.
    
    Throws: DuplicateSectionError if the section already exists.
    +/
    void add_section(char[] name) {
        auto section = name in config;
        if (section is null) {
            this.config[name] = null;
        } else {
            throw new DuplicateSectionError("Section '"~name~"' already exists.");
        }
    }
    /// Requests if a section exists in the parser.
    bool has_section(char[] name) {
        return (name in config) !is null;
    }
    private void no_section(char[] section) {
        throw new SectionNotFoundError("Configuration section '"~section~"' not found.");
    }
    private void no_option(char[] section, char[] option) {
        throw new OptionNotFoundError("Configuration option '"~option~"' in section '"~section~"' not found.");
    }
    /++
    Returns a list of _options in the given section.

    Throws: SectionNotFoundError
    +/
    char[][] options(char[] section=GLOBAL_SECTION) {
        auto s = section in config;
        if (s is null) no_section(section);
        return s.keys;
    }
    /++
    Returns a list of _values in the given section.

    Throws: SectionNotFoundError
    +/
    char[][] values(char[] section=GLOBAL_SECTION) {
        auto s = section in config;
        if (s is null) no_section(section);
        return s.values;
    }
    /++
    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.
    +/
    bool has_option(char[] section, char[] option=null) {
        if (option is null) {
            option = section;
            section = GLOBAL_SECTION;
        }
        auto s = section in config;
        if (s is null) return false;
        auto o = option in (*s);
        if (o is null) return false;
        else return true;
    }
    /++
    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.
    +/
    char[][] read(char[][] filenames...) {
        char[][] files_read;
        foreach (filename; filenames) {
            if (!exists(filename)) continue;
            files_read ~= filename;
            Stream s = new BufferedFile(filename);
            this.read(s, filename);
            delete s;
        }
        return files_read;
    }
    /++
    Reads in any Stream as a config _file.

    Params:
        filename = An optional argument for clarifying error output.
    Throws: ConfigParseError if the stream contains errors.
    +/
    void read(Stream file, char[] filename="") {
        if (filename.length != 0) filename ~= " ";
        char[] section = GLOBAL_SECTION;
        char[] key, value;
        auto s = section in config;
        if (s is null) config[section] = null;
        foreach (ulong line_no, char[] line; file) {
            line = strip(line);
            if (line.length == 0 || line[0] == '#' || line[0] == ';') continue;
            else if (line[0] == '[' && line[$-1] == ']') {
                section = line[1 .. $-1].dup;
                s = section in config;
                if (s is null) {
                    config[section] = null;
                    s = section in config;
                }
            } else {
                int assign = find(line, '=');
                if (assign == -1) assign = find(line, ':');
                if (assign == -1) throw new ConfigParseError("Error in config file "~filename~"on line "~.toString(line_no)~".");
                key = line[0 .. assign];
                value = line[assign+1 .. $];
                key = strip(key).dup;
                value = strip(value).dup;
                (*s)[key] = value;
            }
        }
    }
    /++
    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.
    +/
    char[] opIndex(char[] section, char[] option=null) {
        if (option is null) {
            option = section;
            section = GLOBAL_SECTION;
        }
        auto s = section in config;
        if (s is null) no_section(section);
        auto o = option in (*s);
        if (o is null) no_option(section, option);
        return *o;
    }
    /// An alias of opIndex.
    alias opIndex get;
    /++
    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.
    +/
    int getint(char[] section, char[] option=null) {
        char[] o = this[section, option];
        try {
            return toInt(o);
        } catch(ConvError e) {
            throw new ConfigConvertError("Could not convert '"~o~"' to an integer in option "~section~"."~option~".");
        }
    }
    /++
    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.
    +/
    real getreal(char[] section, char[] option=null) {
        char[] o = this[section, option];
        try {
            return toReal(o);
        } catch(ConvError e) {
            throw new ConfigConvertError("Could not convert '"~o~"' to a real in option "~section~"."~option~".");
        }
    }
    /++
    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.
    +/
    bool getbool(char[] section, char[] option=null) {
        char[] o = tolower(this[section, option]);
        switch (o) {
            case "yes", "true", "on", "1":
                return true;
            case "no", "false", "off", "0":
                return false;
            default:
                throw new ConfigConvertError("Could not convert '"~o~"' to a boolean in option "~section~"."~option~".");
        }
    }
    /++
    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(char[] value, char[] section, char[] option=null) {
        if (option is null) {
            option = section;
            section = GLOBAL_SECTION;
        }
        auto s = section in config;
        if (s is null) no_section(section);
        (*s)[option] = value;
    }
    /++
    Calls opIndexAssign after converting value to a string.
    +/
    void opIndexAssign(int value, char[] section, char[] option=null) {
        this.opIndexAssign(.toString(value), section, option);
    }
    /++
    Calls opIndexAssign after converting value to a string.
    +/
    void opIndexAssign(real value, char[] section, char[] option=null) {
        this.opIndexAssign(.toString(value), section, option);
    }
    /++
    Calls opIndexAssign after converting value to a string.
    +/
    void opIndexAssign(bool value, char[] section, char[] option=null) {
        this.opIndexAssign(.toString(value), section, option);
    }
    /++
    Removes the specified option in section. Silently does nothing if option
    does not exist.

    Throws: SectionNotFoundError if the section does not exist.
    +/
    void remove_option(char[] section, char[] option=null) {
        if (option is null) {
            option = section;
            section = GLOBAL_SECTION;
        }
        auto s = section in config;
        if (s is null) no_section(section);
        (*s).remove(option);
    }
    /++
    Removes section. Silently does nothing if section does not exist.
    +/
    void remove_section(char[] section) {
        this.config.remove(section);
    }
    /++
    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(Stream file) {
        auto global = config[GLOBAL_SECTION];
        bool printed_globals = false;
        foreach (k, v; global) {
            file.writeLine(k ~ " = " ~ v);
            printed_globals = true;
        }
        foreach (name, section; this.config) {
            if (name == GLOBAL_SECTION) continue;
            if (printed_globals) file.writeLine("");
            printed_globals = true;
            file.writeLine("["~name~"]");
            foreach (k, v; section) {
                file.writeLine(k ~ " = " ~ v);
            }
        }
        file.flush();
    }
    /++
    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.
    +/
    void write(char[] filename) {
        Stream s = new BufferedFile(filename, FileMode.OutNew);
        this.write(s);
        s.close();
        delete s;
    }
}