Module ConfigParser


module ConfigParser: sig .. end
System for parsing configuration files


Introduction

Many programs need configuration files. These configuration files are typically used to configure certain runtime behaviors that need to be saved across sessions. Various different configuration file formats exist.

The ConfigParser module attempts to define a standard format that is easy for the user to edit, easy for the programmer to work with, yet remains powerful and flexible.

If you are impatient, the primary reference for the API can be found in ConfigParser.rawConfigParser.

Features

For the programmer, this module provides:

For the user, this module provides:

History

This module is based on Python's ConfigParser module. While the API of these two modules remains similar, and the aim is to preserve all useful features of Python's module, there are some differences in implementation details. This module is a complete clean re-implementation in OCaml, not an OCaml translation of a Python program, and as such has certain features that were not easily accomplished in Python -- and lacks certain features that are not easily accomplished in OCaml.

Configuration File Format

The basic configuration file format resembles that of an old-style Windows .INI file. Here are two samples:


debug = yes
inputfile = /etc/passwd
names = Peter, Paul, Mary, George, Abrahaham, John, Bill, Gerald, Richard,
        Franklin, Woodrow
color = red 

This defines a file without any explicit section, so all items will occur within the default section DEFAULT. The debug option can be read as a boolean or a string. The remaining items can be read as a string only. The names entry spans two lines -- any line starting with whitespace, and containing something other than whitespace or comments, is taken as a continuation of the previous line.

Here's another example:


# Default options
[DEFAULT]
hostname: localhost 

# Options for the first file
[file1]
location: /usr/local
user: Fred
uid: 1000
optionaltext: Hello, this  entire string is included 

[file2]
location: /opt
user: Fred
uid: 1001 

This file defines three sections. The DEFAULT section specifies an entry hostname. If you attempt to read the hostname option in any section, and that section doesn't define hostname, you will get the value from DEFAULT instead. This is a nice time-saver. You can also note that you can use colons instead of the = character to separate option names from option entries.

Whitespace

Whitespace (spaces, tabs, etc) is automatically stripped from the beginning and end of all strings. Thus, users can insert whitespace before/after the colon or equal sign if they like, and it will be automatically stripped.

Blank lines or lines consisting solely of whitespace are ignored.

Comments

Comments are introduced with the pound sign # or the semicolon ;. They cause the parser to ignore everything from that character to the end of the line.

Comments may not occur within the definitions of options; that is, you may not place a comment in the middle of a line such as user: Fred. That is because the parser considers the comment characters part of the string; otherwise, you'd be unable to use those characters in your strings. You can, however, "comment out" options by putting the comment character at the start of the line.

Case-sensitivity

By default, section names are case-sensitive but option names are not. The latter can be adjusted by subclassing the parser class and overriding optionxform.

Exceptions


exception DuplicateSectionError
Raised when you attempt to call ConfigParser.rawConfigParser.add_section when the section already exists
exception InvalidBool of string
Raised when you attempt to parse a boolean that is not valid

Classes


class rawConfigParser : object .. end
Primary interface class for configuarion files.

Interpolation

The configParser class extends ConfigParser.rawConfigParser. It adds interpolation. As an example, consider the following file:


 arch = i386
 project = test
 filename = test_%(arch)s.c
 dir = /usr/src/%(filename)s 
 percent = 5\% 

You could then expect the following results:


get "DEFAULT" "filename" -> "test_i386.c"
get "DEFAULT" "dir" -> "/usr/src/test_i386.c"
get "DEFAULT" "percent" -> "5%" 

class configParser : object .. end