module ConfigParser:System for parsing configuration filessig
..end
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
.
For the programmer, this module provides:
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.
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 (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 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.
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.
exception DuplicateSectionError
ConfigParser.rawConfigParser.add_section
when the section already existsexception InvalidBool of string
class rawConfigParser :object
..end
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