py-configparser API documentation

$Id$
Work in progress.

Please note that we're committed to supporting the same interface as the ConfigParser module, with exceptions. The exceptions are mostly related to maintenance of ordering of sections and options: whereas the Python module doesn't maintain the order encountered in the file, this implementation does.

Functions for creation and manipulation of configurations

make-config &key default sections option-name-transform-fn section-name-transform-fn => config

Creates a config structure used as in-memory storage of the configuration.

The default and sections arguments should not be used and may be removed in newer releases. The option-name-transform-fn and section-name-transform-fn arguments are to be functions used to normalise section and option names. The default value for the former is #'string-downcase, while the default for the latter is #'identity.

defaults config => alist

Returns a of dotted lists where the car is the key and the cdr the associated value.

sections config => list

Returns a list of section names, excluding the default section.

has-section-p config section-name => generalised boolean

Returns NIL if the specified section is not contained in the config object. A non-NIL value is returned otherwise.

The transformation functions are applied to the section name.

add-section config section-name

Adds a new section to the config object.

If the section already exists, a "duplicate-section-error" is raised.

The transformation functions are applied to the section name before checking for duplicates.

options config section-name => unspecified

Returns the list of options which are defined for the specified section.

The transformation functions are applied to section-name.

has-option-p config section-name option-name => generalised boolean

Returns NIL when the specified option does not exist within the specified section of the config object. A non-NIL value is returned otherwise.

The transformation functions are applied to section-name and option-name.

get-option config section-name option-name &key expand defaults type => value

Returns the value of the specified option with type "type", if specified. Values which contain interpolations are expanded by default, but this behaviour can be turned off by passing NIL for "expand".

Defaults may be provided for interpolated values by passing an alist for "defaults", where the car specifies the %()s argument name and the cdr specifies the value to be used in its place.

The transformation functions are applied to section-name and option-name.

set-option config section-name option-name value => unspecified

Sets the value of the specified option in the specified section of the config object.

If the section does not exist, a "no-section-error" is raised. If the option does not exist, it's created.

items config section-name &key expand defaults => alist

Returns an alist of items of the specified section of the given config object. By default, values are expanded, using "defaults" when given. The format of defaults is the same as for get-option.

The transformation functions are applied to the section name.

To disable expansion of the values, you need to specify NIL for "expand".

remove-option config section-name option-name => unspecified

Removes the specified option from the given section of the config object.

remove-section config section-name => unspecified

Removes the specified section from the config object.

If the default section ("DEFAULT") is specified, an error is raised, because it can't be removed.

read-files config filenames => list

Reads the files in the filenames list, incrementally adding and overwriting values in the config object.

Returns the list of files succesfully read. Note however that files can only be succesfully skipped by non-existance. If an error occurs while parsing one of the files, further reading will be aborted, raising the error instead.

read-stream config stream &key stream-name => config

Returns the config object with the sections and options read from the stream overwriting any pre-existing values.

All characters on the stream are read. If an error occurs, processing stops and the error is raised.

Classes

none

Variables / constants

none

Conditions

To be documented

How do I ...

To be written

Back to Common-lisp.net.
Valid XHTML 1.0 Strict