[py-configparser-cvs] r39 - public_html
ehuelsmann at common-lisp.net
ehuelsmann at common-lisp.net
Tue Jun 10 20:46:09 UTC 2008
Author: ehuelsmann
Date: Tue Jun 10 16:46:08 2008
New Revision: 39
Added:
public_html/api-docs.shtml (contents, props changed)
Modified:
public_html/index.shtml
public_html/style.css (props changed)
Log:
Add API docs (with references from the project page) and a new style sheet.
Added: public_html/api-docs.shtml
==============================================================================
--- (empty file)
+++ public_html/api-docs.shtml Tue Jun 10 16:46:08 2008
@@ -0,0 +1,208 @@
+<?xml version="1.0"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+ <title>py-configparser API documentation</title>
+ <link rel="stylesheet" type="text/css" href="style.css"/>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"/>
+ <style type="text/css">
+dt.sym {
+ font-weight: normal;
+ background-color: #8ca;
+ border-bottom: 1px solid gray;
+ border-left: 1px solid #bbb;
+ padding-left: 1ex;
+}
+.function-name { font-weight: bold }
+.class-name { font-weight: bold }
+.slot-name { font-weight: bold }
+.var-name { font-weight: bold }
+dl.faq dt {
+ margin-top: 1em;
+ font-weight: bold;
+ font-size: larger;
+}
+pre {
+ background-color: #ace;
+ padding: 1ex;
+ border: 1px solid black;
+}
+ </style>
+</head>
+<body>
+
+<ul>
+<li><a href="#docs">API documentation</a></li>
+<li><a href="#faqs">How do I ... (FAQ)</a></li>
+</ul>
+
+<h1><a name="docs">py-configparser API documentation</a></h1>
+
+<p style="font-size:8px">$Id$ <br />
+ Work in progress.</p>
+
+<p>Please note that we're committed to supporting the same
+ interface as the ConfigParser module, <em>with exceptions</em>.
+ 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.</p>
+
+
+<h2>Functions for creation and manipulation of configurations</h2>
+
+<dl>
+<dt class="sym"><span class="function-name">make-config</span>
+ &key default sections option-name-transform-fn
+ section-name-transform-fn => config</dt>
+
+<dd>
+<p>Creates a config structure used as in-memory storage of the
+ configuration.</p>
+
+<p>The <em>default</em> and <em>sections</em> arguments should not be
+ used and may
+ be removed in newer releases. The <em>option-name-transform-fn</em> and <em>
+ section-name-transform-fn</em> 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.
+</p></dd>
+
+<dt class="sym">
+<span class="function-name">defaults</span> config => alist</dt>
+<dd><p>Returns a of dotted lists where the car is the key and the
+ cdr the associated value.
+ </p></dd>
+
+<dt class="sym">
+<span class="function-name">sections</span> config => list</dt>
+<dd><p>Returns a list of section names, excluding the default section.</p></dd>
+
+<dt class="sym">
+<span class="function-name">has-section-p</span> config section-name
+ => generalised boolean </dt>
+<dd><p>Returns NIL if the specified section is not contained in the
+ config object. A non-NIL value is returned otherwise. </p>
+
+ <p>The transformation functions are applied to the section name.</p></dd>
+
+<dt class="sym">
+<span class="function-name">add-section</span> config section-name</dt>
+<dd><p>Adds a new section to the config object.</p>
+
+ <p>If the section already exists, a "duplicate-section-error"
+ is raised.</p>
+ <p>The transformation functions are applied to the section name
+ before checking for duplicates.</p></dd>
+
+<dt class="sym">
+<span class="function-name">options</span> config section-name
+ => unspecified</dt>
+<dd><p>Returns the list of options which are defined for the specified
+ section.</p>
+ <p>The transformation functions are applied to section-name.</p></dd>
+
+<dt class="sym">
+<span class="function-name">has-option-p</span>
+ config section-name option-name => generalised boolean</dt>
+<dd><p>Returns NIL when the specified option does not exist within the
+ specified section of the config object. A non-NIL value is returned
+ otherwise.</p>
+
+ <p>The transformation functions are applied to section-name and
+ option-name.</p></dd>
+
+<dt class="sym">
+<span class="function-name">get-option</span> config section-name
+ option-name &key expand defaults type => value</dt>
+<dd><p>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".
+ </p>
+
+ <p>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.</p>
+
+ <p>The transformation functions are applied to section-name and
+ option-name. </p></dd>
+
+<dt class="sym">
+<span class="function-name">set-option</span> config section-name
+ option-name value => unspecified</dt>
+<dd><p>Sets the value of the specified option in the specified section
+ of the config object.</p>
+
+ <p>If the section does not exist, a "no-section-error" is
+ raised. If the option does not exist, it's created.</p></dd>
+
+<dt class="sym">
+<span class="function-name">items</span> config section-name
+ &key expand defaults => alist</dt>
+<dd><p>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.</p>
+
+ <p>The transformation functions are applied to the section name.</p>
+
+ <p>To disable expansion of the values, you need to specify NIL for
+ "expand".</p></dd>
+
+<dt class="sym">
+<span class="function-name">remove-option</span> config section-name
+ option-name => unspecified</dt>
+<dd><p>Removes the specified option from the given section of the config
+ object.</p></dd>
+
+<dt class="sym">
+<span class="function-name">remove-section</span> config section-name
+ => unspecified</dt>
+<dd><p>Removes the specified section from the config object.</p>
+ <p>If the default section ("DEFAULT") is specified,
+ an error is raised, because it can't be removed.</p></dd>
+
+<dt class="sym">
+<span class="function-name">read-files</span> config filenames => list</dt>
+<dd><p>Reads the files in the filenames list, incrementally adding and
+ overwriting values in the config object.</p>
+
+ <p>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.</p></dd>
+
+<dt class="sym">
+<span class="function-name">read-stream</span> config stream
+ &key stream-name => config</dt>
+<dd><p>Returns the config object with the sections and options read from
+ the stream overwriting any pre-existing values.</p>
+ <p>All characters on the stream are read. If an error occurs,
+ processing stops and the error is raised.</p></dd>
+
+</dl>
+
+<h2>Classes</h2>
+
+<p><em>none</em></p>
+
+<h2>Variables / constants</h2>
+
+<p><em>none</em></p>
+
+<h2>Conditions</h2>
+
+<p>To be documented</p>
+
+<h1><a name="faqs">How do I ...</a></h1>
+
+<p>To be written</p>
+
+
+<div style="float:left;font-size:x-small;font-weight:bold">
+Back to <a href="http://common-lisp.net/">Common-lisp.net</a>.
+</div>
+ <div class="check" style="float:right">
+ <a href="http://validator.w3.org/check/referer">Valid XHTML 1.0 Strict</a>
+ </div>
+</body>
+</html>
Modified: public_html/index.shtml
==============================================================================
--- public_html/index.shtml (original)
+++ public_html/index.shtml Tue Jun 10 16:46:08 2008
@@ -36,6 +36,19 @@
<p>You can reach the developer(s) at the development list:
<b><a href="http://common-lisp.net/cgi-bin/mailman/listinfo/py-configparser-devel">py-configparser-devel at common-lisp.net</a></b></p>
+ <h2>API description</h2>
+
+ <p>There's a separate page <a href="api-docs.shtml">describing the
+ package public API</a>.
+
+ <h2>Source code online</h2>
+
+ <p>The sources for releases may be downloaded (see below); the
+ <a
+ href="http://common-lisp.net/websvn/listing.php?repname=py-configparser"
+ >current (active) development may be browsed online</a>
+ through the WebSVN service.</p>
+
<h1>Examples:</h1>
<pre style="border: 1px solid black; background-color: #ccf">
More information about the Py-configparser-cvs
mailing list