FBB::ConfigFile - A class processing standard unix-like
configuration files
#include <bobcat/configfile>
Linking option: -lbobcat
ConfigFile objects read standard unix-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.
If the rmComment flag is set to true blanks lines
and information on lines from the first # are removed. If the comment
character (#) is prefixed by a backslash (i.e., \#) it is not
considered comment, but replaced by a single # character. Likewise,
if the rmComment flag was set two consecutive backslash characters
are replaced by a single backslash character, In the retrieved configuration
information it appears as a single # character. If the configuration
file should contain \# write \\#, this results in replacing
\# by #, leaving \#.
All non-empty lines of the configuration file (when comment is
ignored comment is not considered to be line-content) are stored in the
ConfigFile object. When line indices should be stored the (0-based)
line indices of lines are available as well.
At construction time comment handling (keep comment / remove
comment), case-sensitive searching (sensitive / insensitive) and index
storage (store / don’t store) can be specified.
It can’t be modified using the open member, but
overloaded assignment is supported and comment and letter case handling can
be modified by set-members.
FBB
All constructors, members, operators and manipulators, mentioned in this
man-page, are defined in the namespace FBB.
The following enumerations are defined by the class
ConfigFile:
- o
- Comment:
This enumeration has two values:
ConfigFile::KeepComment is used to indicate that comment on lines
must be kept;
ConfigFile::RemoveComment is used to indicate that comment on lines
must be removed;
- o
- SearchCasing:
This enumeration also has two values:
ConfigFile::SearchCaseSensitive is used to do case sensitive searches
for targets;
ConfigFile::SearchCaseInsensitive is used to do case insensitive
searches for targets.
- o
- Indices:
This enumeration also has two values:
ConfigFile::IgnoreIndices when used, the line numbers of the original
configuration file are not available;
ConfigFile::StoreIndices when used, the line numbers of the original
configuration file are also available;
The following types are defined by the class
ConfigFile:
- o
- const_iterator:
a const_iterator is an iterator pointing to a line
(std::string) of the configuration file;
- o
- const_RE_iterator:
a const_RE_iterator is an iterator pointing to lines matching a
regular expression. It supports the following operations:
- o
- const_RE_iterator &operator++(): the prefix increment operator
increments the iterator to point to the next line in the configuration
file matching the iterator’s regular expression;
- o
- std::string const &operator*(): the dereferencing operator
returns the line of the configuration file the iterator refers to;
- o
- std::string const *operator->(): the pointer operator returns
the address of the line of the configuration file the iterator refers to;
const_RE_iterators can be compared for (in)equality and they can be
copy-constructed; const_RE_iterator objects are returned by the
ConfigFile::beginRE, ConfigFile::endRE and
ConfigFile::beginEndRE members and cannot otherwise be
constructed.
- When two const_RE_iterator 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):
ConfigFile cf(...)
auto iters = cf.beginEndRE("^hello");
cout << "There are " << (iters.second - iters.first) <<
" lines starting with hello\n";
The two const_RE_iterator objects should refer to the same regular
expression. The provided example illustrates how this is realized using
beginEndRE.
- FBB::Pattern is used to perform the regular expression pattern
matching.
- o
- ConfigFile(Comment cType = KeepComment, SearchCasing sType =
SearchCaseSensitive, Indices iType = IgnoreIndices):
This constructor is used to create an empty ConfigFile object. It is
not associated with an input stream: the open 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.
- o
- ConfigFile(std::string const &fname, Comment cType =
KeepComment, SearchCasing sType = SearchCaseSensitive,
Indices iType = IgnoreIndices):
This constructor is used to create a ConfigFile 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 FBB::Exception
exception if the file could not be opened.
Copy and move constructors are available.
- o
- std::string const &operator[](size_t idx) const:
This member returns the (0-based) idx-th line of the configuration
file.
The overloaded assignment and move assignment operators are available.
- o
- ConfigFile::const_iterator begin() const:
This member returns a const_iterator to the first line of the
configuration file.
- o
- ConfigFile::const_iterator end() const:
This member returns a const_iterator pointing beyond the last line of
the configuration file.
- o
- std::pair<ConfigFile::const_RE_iterator,
ConfigFile::const_RE_iterator> beginEndRE(std::string const
&target) const:
A pair of const_RE_iterators is returned. The first field of
the pair is a const iterator to the first element (i.e., line) of
the ConfigFile object in which the regular expression target
is found.
- The second field is a const iterator marking the end of the
series of lines started at the the first line matching the regular
expression specified by target.
- If the RemoveComment flag was specified, then comment-text is not
searched. The iterator returned in the pair’s first field
can be incremented until the iteratr returned in the pair’s
second field is reached; all iterators (unequal the iterator in
second) point to lines matching the specified regular
expression.
- The iterator’s increment operator searches the next line matching
the specified regular expression.
- Although the difference between two const_RE_iterators 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 std::numeric_limits<size_t>::max() is
returned.
- This member also interprets the SearchCasing flag.
- o
- std::pair<ConfigFile::const_RE_iterator,
ConfigFile::const_RE_iterator> beginEndRE() const:
A pair of const_RE_iterators is returned, both marking the end of a
regular expression search.
- o
- ConfigFile::const_iterator find(std::string const &target)
const:
This member returns an iterator to the first element (i.e., line) of the
FBB::ConfigFile object in which target is found. Note that
target may appear anywhere within a line. If the
RemoveComment flag was specified, then comment-text is not
searched. Use the end member to determine the end-iterator. It is
not guaranteed that all lines between the returned iterator and end
contain target. This member also interprets the SearchCasing
flag.
- o
- std::string findKey(std::string const &keyPattern, size_t
count = 1) const:
This member can be used to retrieve information from lines having the
general pattern `keyPattern value’. Initial and trailing
white space on lines are ignored. keyPattern itself should not
contain initial or trailing white space. At least one white space
character must appear between keyPattern and value. If at
least count lines were found matching keyPattern value then
this member returns the first sequence of non white space characters
following keyPattern after matching count lines matching
keyPattern value (i.e., `value’ is returned). If
value is empty or if fewer than count lines match
keyPattern an empty string is returned. An FBB::Exception
exception is thrown if count equals 0.
- o
- std::string findKeyTail(std::string const &keyPattern,
size_t count = 1) const:
This member can be used to retrieve information from lines having the
general pattern `keyPattern value’, merely followed by white
space. Initial and trailing white space on lines are ignored.
keyPattern itself should not contain initial or trailing white
space. At least one white space character must appear between
keyPattern and value. If at least count lines were
found matching keyPattern value then this member returns the
information beyond keyPattern after matching count lines
matching keyPattern (i.e., `value’ is returned). This
function differs from findKey in that all information trailing
keyPattern is returned in value. If value is empty or
if fewer than count lines match keyPattern an empty string
is returned. An FBB::Exception exception is thrown if count
equals 0.
- o
- ConfigFile::const_iterator findRE(std::string const &target)
const:
This member returns an iterator to the first line of the ConfigFile
object matching the regular expression target. After calling this
function beginEndRE returns an iterator pair whose first
field is an iterator to the same line and whose second field is the
end-iterator for lines matching target. If the RemoveComment
flag was specified, then comment-text is not searched. The inherited
end member can be used to determine the end-iterator. It is not
guaranteed that all lines between the returned iterator and end
also contain target. If that is required, the members
beginRE and endRE can be used. This member also interprets
the SearchCasing flag.
- o
- size_t index(size_t idx):
This function should only be used when the parameter StoreIndices was
specified at construction time. In that case it returns the original
0-based line index in the configuration file associated with the
idx (0-based) index in the current Configuration
object.
- o
- size_t index(const_iterator const &iter):
This function should only be used when the parameter StoreIndices was
specified at construction time. In that case it returns the original
0-based line index in the configuration file associated with the
configuration line in the current Configuration object pointed to
by iter. This may also be an (incremented version of the) iterator
returned by the member findRE or beginRE, as long as the
iterator’s value is within the half open range beginRE to
endRE.
- o
- void open(std::string const &fname):
This member reads the configuration file having name fname. It
redefines the current contents of the ConfigFile object, destroying
any information previously stored in it. The configuration file is read
according to the latest setting of the comment-flag. It throws an
FBB::Exception exception if the file cannot be opened.
- This member clears previously available information and reinitializes the
object with information read from the new file.
- o
- void setCommentHandling(Comment type):
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 ConfigFile
object, but new calls of its open member reads the configuration
file according to the last setting of the comment flag.
- o
- void setSearchCasing(SearchCasing type):
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
ConfigFile object, but new calls of its open member reads
the configuration file according to the last setting of the letter-casing
flag.
- o
- size_t size() const:
This member returns the number of lines in the configuration file.
Assume the configuration file is called config.rc and
contains the following lines:
# 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
The following program may be compiled and run as a.out
config.rc:
#include <iostream>
#include <iterator>
#include <algorithm>
#include <string>
#include <bobcat/configfile>
using namespace std;
using namespace FBB;
int main(int argc, char **argv)
{
ConfigFile cf(argv[1]);
cout << *cf.find("this one") << endl; // find text within a line
// find all lines matching
// `^line:’
copy(cf.beginRE("^line:"), cf.endRE(),
ostream_iterator<string>(cout, "\n"));
}
Producing the output:
noline: this one too
line: this is found
line: this one is
line: what about this one? it’s extending over multiple lines
bobcat/configfile - defines the class interface
- o
- bobcat_4.08.06-x.dsc: detached signature;
- o
- bobcat_4.08.06-x.tar.gz: source archive;
- o
- bobcat_4.08.06-x_i386.changes: change log;
- o
- libbobcat1_4.08.06-x_*.deb: debian package holding the
libraries;
- o
- libbobcat1-dev_4.08.06-x_*.deb: debian package holding the
libraries, headers and manual pages;
- o
- http://sourceforge.net/projects/bobcat: public archive location;
Bobcat is an acronym of `Brokken’s Own Base Classes And
Templates’.
This is free software, distributed under the terms of the GNU
General Public License (GPL).
Frank B. Brokken (f.b.brokken@rug.nl).