<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Falcon Feathers - The Standard Modules Reference.</title>
<link href="faldoc.css" rel="stylesheet" type="text/css"/>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
</head>
<body class="faldoc_body">
<div class="navitop">
<div class="tabs">
<ul>
<li><a href="./index.html"><span>Main</span></a></li>
<li><a href="./modules.html"><span>Modules</span></a></li>
<li><a href="./pages.html"><span>Related pages</span></a></li>
<li><a href="./groups.html"><span>Groups</span></a></li>
<li><a href="./classes.html"><span>Classes</span></a></li>
<li><a href="./objects.html"><span>Objects</span></a></li>
<li><a href="./functions.html"><span>All functions</span></a></li>
<li><a href="./enum.html"><span>Enumerations</span></a></li>
</ul>
</div>
</div>
<hr/>
<h1 class="faldoc_title">Module Configuration Parser </h1>
<p class="faldoc_brief">Advanced configuration file parser (with sections and key categorization support). </p>
<p class="faldoc_text"><p class="faldoc_text">The ConfParser module is meant as a simple but powerful interface to .INI like configuration files, with some extra features that allows to bring a bit forward the traditional configuration file model and to circumvent some arbitrary limitation that makes using human readable configuration files a bit difficult in some complex configuration contexts. </p>
<p class="faldoc_text">ConfParser module also maintains comments and tries respect the layout of the original INI file, so that it stays familiar for the user after a modify that has been caused by the Falcon module. </p>
<a name="confparser_ini_fformat"><h2 class="faldoc_section">Ini file format </h2></a>
<p class="faldoc_text">The ConfParser module parses INI files in the following format: </p>
<pre class="faldoc_code">
; Comment lines
; Comment lines...
Key = value
category.key = value
[section_name]
Key = value
category.key = value
Comments may be started either with ";" or "#" characters, and the colon ":" may be used instead of "=". So the above file may be rewritten in the more UNIX style:
# Comment lines
# Comment lines...
Key: value
category.key: value
[section_name]
Key: value
category.key: value
</pre>
<p class="faldoc_text">Values may be enclosed in quotes; in this case, Falcon escape sequences are correctly parsed. As comments starting with ";" or "#" may be placed also after a value, if a value itself contains one of those characters it should be enclosed by quotes, or part of the value will be considered a comment. </p>
<p class="faldoc_text">For example: </p>
<pre class="faldoc_code">
Key: "A complex value containing\nescapes # and comment" ; real comment
</pre>
<a name="confparser_multiple_values"><h3 class="faldoc_subsection">Multiple values </h3></a>
<p class="faldoc_text">Although it would be possible to put arbitrary lists into strings to save them on configuration files, and expand them in the program when reading them back, it is possible to store array of values in configuration files by declaring multiple times the same key. </p>
<p class="faldoc_text">For example: </p>
<pre class="faldoc_code">
Key = value1
Key = value2
Key = value3
</pre>
<p class="faldoc_text">This will result in the three values to be returned in an array when the value of "Key" is asked. </p>
<a name="confparser_key_cat"><h3 class="faldoc_subsection">Key categories </h3></a>
<p class="faldoc_text">Keys can be categorized; tree-like or even recursive key groups can be represented with dots separating the key hierarchy elements. In example, the configuration of a complex program can be saved like that: </p>
<pre class="faldoc_code">
...
UserPref.files.MaxSize = 100
UserPref.files.DefaultDir = "/home/$user"
...
...
UserPref.cache.MaxSize = 250
UserPref.cache.path = "/var/cache/prog.cache"
...
</pre>
<p class="faldoc_text">This lessen the need for traditional ini file "sections". Support for sections is provided both for backward compatibility with a well known file structure and because it still can be useful where it is known that one hierarchical level is enough for the configuration needs of an application. </p>
<p class="faldoc_text">Sections are portion of ini files separated by the rest of it by an header in square brackets; the keys that are defined from the beginning of file to the first section heading, if present, are considered to belong to the "main" section. The main section can't be directly addressed, as it has not a name. All the methods accessing or manipulating keys have an extra optional parameter that can address a specific section by it's name. If the parameter is not specified, or if the parameter has nil value, then the methods will operate on the main section. </p>
</p>
<h2 class="faldoc_title">Classes</h2>
<table class="faldoc_list">
<tr><td class="faldoc_funcname"><a href="./class_ConfParser.html">ConfParser</a></td><td class="faldoc_funcbrief">Interface to configuration files. </td></tr>
</table>
<hr/>
<div class="navibottom">
<center>
<a href="./index.html">Main</a> - <a href="./modules.html">Modules</a> - <a href="./pages.html">Related pages</a> - <a href="./groups.html">Groups</a> - <a href="./classes.html">Classes</a> - <a href="./objects.html">Objects</a> - <a href="./functions.html">All functions</a> - <a href="./enum.html">Enumerations</a>
</center>
</div>
</div>
<div class="faldoc_signature">Made with <a href="http://www.falconpl.org">faldoc 2.2.0</div>
</body>
</html>
