/usr/share/doc/libbobcat2-dev/man/configfile.3.html

<html><head>
<title>FBB::ConfigFileile</title>
<link rev="made" href="mailto:Frank B. Brokken: f.b.brokken@rug.nl">
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr>
<h1>FBB::ConfigFileile</h1>
<h2>libbobcat1-dev_2.20.01-x.tar.gz</h2>
<h2>2005-2011</h2>

<html><head>
<link rev="made" href="mailto:Frank B. Brokken: f.b.brokken@rug.nl">
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr>
<h1></h1>

<html><head>
<title>FBB::ConfigFileile(3bobcat)</title>
<link rev="made" href="mailto:Frank B. Brokken: f.b.brokken@rug.nl">
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr>
<h1>FBB::ConfigFileile(3bobcat)</h1>
<h2>libbobcat1-dev_2.20.01-x.tar.gz Configuration File Processing</h2>
<h2>2005-2011</h2>


<p>
<h2>NAME</h2>FBB::ConfigFileile - A class processing standard unix-like configuration files
<p>
<h2>SYNOPSIS</h2>
    <strong>#include &lt;bobcat/configfile&gt;</strong><br>
    Linking option: <em>-lbobcat</em> 
<p>
<h2>DESCRIPTION</h2>
    <strong>ConfigFile</strong> objects read standard <em>unix</em>-style configuration
files.  Lines are stored with initial white-space (blanks and tabs) removed.
If a line ends in \, then the next line (initial white-space removed) is
appended to the current line.
<p>
Information at and beyond the first <em>#</em> on individual lines is removed
if the <em>rmComment</em> flag is set to <em>true</em>.  In that case, lines containing
only blanks and tabs are not stored.
<p>
All non-empty lines of the configuration file (when comment is ignored comment
is not considered to be line-content) are stored in the <strong>ConfigFile</strong> object.
When line indices should be stored the (0-based) line indices of lines will be
available as well.
<p>
At construction time comment handling (keep comment / remove comment),
case-sensitive searching (sensitive / insensitive) and index storage (store /
don't store) can be specified.
<p>
It can't be modified using the <em>open</em> member, but overloaded assignment is
supported and comment and letter case handling can be modified by set-members.
<p>
<h2>NAMESPACE</h2>
    <strong>FBB</strong><br>
    All constructors, members, operators and manipulators, mentioned in this
man-page, are defined in the namespace <strong>FBB</strong>.
<p>
<h2>INHERITS FROM</h2>
    -
<p>
<h2>ENUMERATIONS</h2>
    The following enumerations are defined by the class <strong>ConfigFile</strong>:
    <ul>
    <li> <strong>Comment</strong>:<br>
        This enumeration has two values: <br>
        <strong>ConfigFile::KeepComment</strong> is used to indicate that comment on
lines must be kept; <br>
        <strong>ConfigFile::RemoveComment</strong> is used to indicate that comment on
lines must be removed;
    <li> <strong>SearchCasing</strong>:<br>
        This enumeration also has two values:<br> 
        <strong>ConfigFile::SearchCaseSensitive</strong> is used to do case sensitive
searches for targets;<br>
        <strong>ConfigFile::SearchCaseInsensitive</strong> is used to do case
insensitive searches for targets.
    <li> <strong>Indices</strong>:<br>
        This enumeration also has two values:<br> 
        <strong>ConfigFile::IgnoreIndices</strong> when used, the line numbers of the
original configuration file will not be made available;<br>
        <strong>ConfigFile::StoreIndices</strong> when used, the line numbers of the
original configuration file will be made available;<br>
    </ul>
<p>
<h2>TYPES</h2>
    The following types are defined by the class <em>ConfigFile</em>:
    <ul>
    <li> <strong>const_iterator</strong>:<br> 
        a <em>const_iterator</em> is an iterator pointing to a
line (<em>std::string</em>) of the configuration file;
    <li> <strong>const_RE_iterator</strong>:<br> a <em>const_RE_iterator</em> is an iterator pointing to
lines matching a regular expression. It supports the following operations:
        <ul>
        <li> <em>const_RE_iterator &amp;operator++()</em>: the prefix increment operator
increments the iterator to point to the next line in the configuration file
matching the iterator's regular expression;
        <li> <em>std::string const &amp;operator*()</em>: the dereferencing operator
returns the line of the configuration file the iterator refers to;
        <li> <em>std::string const *operator-&gt;()</em>: the pointer operator returns the
address of the line of the configuration file the iterator refers to;
        </ul>
    <em>const_RE_iterator</em>s can be compared for (in)equality and they can be
copy-constructed; <em>const_RE_iterator</em> objects are returned by the
<em>ConfigFile::beginRE</em>, <em>ConfigFile::endRE</em> and <em>ConfigFile::beginEndRE</em>
members and cannot otherwise be constructed.
<p>
When two <em>const_RE_iterator</em> objects are subtracted the
number of lines matching their regular expression is returned. E.g., (see
below for a description of the functions used in the next example):
        <pre>

    ConfigFile cf(...)
    auto iters = cf.beginEndRE("^hello");
    cout &lt;&lt; "There are " &lt;&lt; (iters.second - iters.first) &lt;&lt; 
            " lines starting with hello\n";
        
</pre>

    The two <em>const_RE_iterator</em> objects should refer to the same regular
expression. The provided example illustrates how this is realized using
<em>beginEndRE</em>.
<p>
<em>FBB::Pattern</em> is used to perform the regular expression pattern
matching.
    </ul>
<p>
<h2>CONSTRUCTORS</h2>
    <ul>
    <li> <strong>ConfigFile(Comment cType = KeepComment, SearchCasing sType =
            SearchCaseSensitive, Indices iType = IgnoreIndices)</strong>:<br>
        This constructor is used to create an empty <strong>ConfigFile</strong>
object. It is not associated with an input stream: the <em>open</em> member can
be used for that. The parameters can be used to specify specific handling of
comment, letter-casing and storage of line numbers in the original
configuration file.
    <li> <strong>ConfigFile(std::string const &amp;fname, Comment cType = KeepComment,
            SearchCasing sType = SearchCaseSensitive, 
            Indices iType = IgnoreIndices)</strong>:<br>
        This constructor is used to create a <strong>ConfigFile</strong> object, which
is filled with the information from a file whose name is provided as the
constructor's first argument. The other parameters are used as described with
the first constructor. It throws an <em>FBB::Errno</em> exception if the file
could not be opened.
    </ul><br>
        The copy and move constructors are available.
<p>
<h2>OVERLOADED OPERATORS</h2>
    <ul>
    <li> <strong>std::string const &amp;operator[](size_t idx) const</strong>:<br>
        This member returns the (0-based) <em>idx</em>-th line of the configuration
    file. 
    </ul><br>
    The overloaded assignment and move assignment operators are available.
<p>
<h2>MEMBER FUNCTIONS</h2>
    <ul>
    <li> <strong>ConfigFile::const_iterator begin() const</strong>:<br>
        This member returns a <em>const_iterator</em> to the first line of the
configuration file.
<p>
<li> <strong>ConfigFile::const_RE_iterator beginRE(std::string const &amp;target) const</strong>:<br>
        Deprecated. Use <em>beginEndRE</em> instead. 
<p>
<li> <strong>ConfigFile::const_iterator end() const</strong>:<br>
        This member returns a <em>const_iterator</em> pointing beyond the last line
of the configuration file.
<p>
<li> <strong>ConfigFile::const_RE_iterator endRE() const</strong>:<br>
        Deprecated. Use <em>BeginEndRE</em> instead.
<p>
<li> <strong>std::pair&lt;ConfigFile::const_RE_iterator, ConfigFile::const_RE_iterator&gt;
         beginEndRE(std::string const &amp;target) const</strong>:<br>
        A pair of <em>const_RE_iterators</em> is returned. The <em>first</em>
field of the pair is a <em>const</em> iterator to the first element (i.e.,
line) of the <strong>ConfigFile</strong> object in which the regular expression <em>target</em>
is found. 
<p>
The <em>second</em> field is a <em>const</em> iterator marking the end of the
series of lines started at the the first line matching the regular expression
specified by <em>target</em>.
<p>
If the <em>RemoveComment</em> flag was specified, then comment-text is not
searched.  The iterator returned in the pair's <em>first</em> field can be
incremented until the iteratr returned in the pair's <em>second</em> field is
reached; all iterators (unequal the iterator in <em>second</em>) point to lines
matching the specified regular expression.  
<p>
The iterator's increment operator searches the next line matching the
specified regular expression.
<p>
Although the difference between two <em>const_RE_iterators</em> can be computed
it is a relatively expensive operation. The difference is obtained by
performing repeated regular expression matchings rather than the mere
algebraic subtraction of pointer values. If the difference cannot be computed
<em>UINT_MAX</em> is returned.
<p>
This member also interprets the <em>SearchCasing</em> flag.
<p>
<li> <strong>ConfigFile::const_iterator find(std::string const &amp;target) const</strong>:<br>
        This member returns an iterator to the first element (i.e., line) of
the <em>FBB::ConfigFile</em> object in which <em>target</em> is found. Note that
<em>target</em> may appear anywhere within a line. If the <em>RemoveComment</em> flag
was specified, then comment-text is not searched. Use the <em>end</em> member to
determine the end-iterator. It is not guaranteed that all lines between the
returned iterator and <em>end</em> will also contain <em>target</em>.  This member also
interprets the <em>SearchCasing</em> flag.
<p>
<li> <strong>std::string findKey(std::string const &amp;keyPattern, 
                                                     size_t count = 1) const</strong>:<br>
        This member can be used to retrieve information from lines having the
general pattern `<em>keyPattern value</em>'. Initial and trailing white space on
lines are ignored. <em>keyPattern</em> itself should not contain initial or
trailing white space. At least one white space character must appear between
<em>keyPattern</em> and <em>value</em>. If at least <em>count</em> lines were found matching
<em>keyPattern value</em> then this member returns the first sequence of non white
space characters following <em>keyPattern</em> after matching <em>count</em> lines
matching <em>keyPattern value</em> (i.e., `<em>value</em>' is returned). If <em>value</em> is
empty or if fewer than <em>count</em> lines match <em>keyPattern</em> an empty string is
returned. An <em>FBB::Errno</em> exception is thrown if <em>count</em> equals 0.
<p>
<li> <strong>std::string findKeyTail(std::string const &amp;keyPattern, 
                                                    size_t count = 1) const</strong>:<br>
        This member can be used to retrieve information from lines having the
general pattern `<em>keyPattern value</em>', merely followed by white
space. Initial and trailing white space on lines are ignored. <em>keyPattern</em>
itself should not contain initial or trailing white space. At least one white
space character must appear between <em>keyPattern</em> and <em>value</em>.  If at least
<em>count</em> lines were found matching <em>keyPattern value</em> then this member
returns the information beyond <em>keyPattern</em> after matching <em>count</em> lines
matching <em>keyPattern</em> (i.e., `<em>value</em>' is returned). This function differs
from <em>findKey</em> in that all information trailing <em>keyPattern</em> is returned
in <em>value</em>.  If <em>value</em> is empty or if fewer than <em>count</em> lines match
<em>keyPattern</em> an empty string is returned. An <em>FBB::Errno</em> exception is
thrown if <em>count</em> equals 0.
<p>
<li> <strong>ConfigFile::const_iterator findRE(std::string const &amp;target) const</strong>:<br>
        This member returns an iterator to the first line of the
<strong>ConfigFile</strong> object matching the regular expression <em>target</em>. After
calling this function <em>beginRE</em> will return an iterator to the same line and
<em>endRE</em> returns the end-iterator for lines matching <em>target</em>. If the
<em>RemoveComment</em> flag was specified, then comment-text is not searched.  The
inherited <em>end</em> member can be used to determine the end-iterator. It is not
guaranteed that all lines between the returned iterator and <em>end</em> will also
contain <em>target</em>. If that is required, the members <em>beginRE</em> and <em>endRE</em>
can be used.  This member also interprets the <em>SearchCasing</em> flag.
<p>
<li> <strong>size_t index(size_t idx)</strong>:<br>
        This function should only be used when the parameter <em>StoreIndices</em>
was specified at construction time. In that case it will return the original
0-based line index in the configuration file associated with the <em>idx</em>sup(th)
(0-based) index in the current <em>Configuration</em> object. 
<p>
<li> <strong>size_t index(const_iterator const &amp;iter)</strong>:<br>
        This function should only be used when the parameter <em>StoreIndices</em>
was specified at construction time. In that case it will return the original
0-based line index in the configuration file associated with the configuration
line in the current <em>Configuration</em> object pointed to by <em>iter</em>. This may
also be an (incremented version of the) iterator returned by the member
<em>findRE</em> or <em>beginRE</em>, as long as the iterator's value is within the half
open range <em>beginRE</em> to <em>endRE</em>.
<p>
<li> <strong>void open(std::string const &amp;fname)</strong>:<br>
        This member will read the configuration file having name <em>fname</em>.
It will redefine the current contents of the <strong>ConfigFile</strong> object,
destroying any information previously stored in it. The configuation file is
read according to the latest setting of the comment-flag. It will throw an
<em>FBB::Errno</em> exception if the file could not be opened.
<p>
This member clears previously available information and reinitializes the
object with information read from the new file.
<p>
<li> <strong>void setCommentHandling(Comment type)</strong>:<br>
        This member can be used to change the comment-handling type originally
set by the constructor, or set by earlier calls of this function. When called
it won't affect the current contents of the <strong>ConfigFile</strong> object, but
new calls of its <em>open</em> member will read the configuation file according
to the last setting of the comment flag.
<p>
<li> <strong>void setSearchCasing(SearchCasing type)</strong>:<br>
        This member can be used to change the handling of the letter-casing
originally set by the constructor, or set by earlier calls of this
function. When called it won't affect the current contents of the
<strong>ConfigFile</strong> object, but new calls of its <em>open</em> member will read
the configuation file according to the last setting of the letter-casing flag.
<p>
<li> <strong>size_t size() const</strong>:<br>
        This member returns the number of lines in the configuration file.
    </ul>
<p>
<h2>EXAMPLE</h2>
    Assume the configuration file is called <em>config.rc</em> and contains the
following lines: 
<p>

    <pre>


# this is ignored

noline: this one too

line: this is found

this is not a line containing line: at the beginning of the line

line: this one is

    line: what about this one? \ 
        it's extending over multiple lines

and there may, of course, be more lines in this file
    
</pre>

<p>
The following program may be compiled and run as <em>a.out config.rc</em>:
    <pre>

#include &lt;iostream&gt;
#include &lt;iterator&gt;
#include &lt;algorithm&gt;
#include &lt;string&gt;
#include &lt;bobcat/configfile&gt;

using namespace std;
using namespace FBB;
    
int main(int argc, char **argv)
{
    ConfigFile cf(argv[1]);     

    cout &lt;&lt; *cf.find("this one") &lt;&lt; endl; // find text within a line

                                         // find all lines matching 
                                         // `^line:'
    copy(cf.beginRE("^line:"), cf.endRE(), 
                    ostream_iterator&lt;string&gt;(cout, "\n"));
}
    
</pre>

<p>
Producing the output:
    <pre>

noline: this one too
line: this is found
line: this one is
line: what about this one? it's extending over multiple lines
    
</pre>

<p>
<h2>FILES</h2>
    <em>bobcat/configfile</em> - defines the class interface
<p>
<h2>SEE ALSO</h2>
    <strong>bobcat</strong>(7), <strong>errno</strong>(3bobcat), <strong>pattern</strong>(3bobcat)
<p>
<h2>BUGS</h2>
    None Reported.
<p>

<h2>DISTRIBUTION FILES</h2>
    <ul>
    <li> <em>bobcat_2.20.01-x.dsc</em>: detached signature;
    <li> <em>bobcat_2.20.01-x.tar.gz</em>: source archive;
    <li> <em>bobcat_2.20.01-x_i386.changes</em>: change log;
    <li> <em>libbobcat1_2.20.01-x_*.deb</em>: debian package holding the
            libraries;
    <li> <em>libbobcat1-dev_2.20.01-x_*.deb</em>: debian package holding the
            libraries, headers and manual pages;
    <li> <em>http://sourceforge.net/projects/bobcat</em>: public archive location;
    </ul>
<p>
<h2>BOBCAT</h2>
    Bobcat is an acronym of `Brokken's Own Base Classes And Templates'.
<p>
<h2>COPYRIGHT</h2>
    This is free software, distributed under the terms of the 
    GNU General Public License (GPL).
<p>
<h2>AUTHOR</h2>
    Frank B. Brokken (<strong>f.b.brokken@rug.nl</strong>).
<p>
libbobcat-dev 2.20.01-1 / usr / share / doc / libbobcat2-dev / man / configfile.3.html
