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@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">