Provided by: libbobcat-dev_3.19.01-1ubuntu1_amd64 
NAME
FBB::ConfigFileile - A class processing standard unix-like configuration files
SYNOPSIS
#include <bobcat/configfile>
Linking option: -lbobcat
DESCRIPTION
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.
NAMESPACE
FBB
All constructors, members, operators and manipulators, mentioned in this man-page, are
defined in the namespace FBB.
INHERITS FROM
-
ENUMERATIONS
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;
TYPES
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.
CONSTRUCTORS
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.
The copy and move constructors are available.
OVERLOADED OPERATORS
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.
MEMBER FUNCTIONS
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 configuation 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 configuation 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 configuation 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.
EXAMPLE
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
FILES
bobcat/configfile - defines the class interface
SEE ALSO
argconfig(3bobcat), bobcat(7), errno(3bobcat), pattern(3bobcat)
BUGS
None Reported.
DISTRIBUTION FILES
o bobcat_3.19.01-x.dsc: detached signature;
o bobcat_3.19.01-x.tar.gz: source archive;
o bobcat_3.19.01-x_i386.changes: change log;
o libbobcat1_3.19.01-x_*.deb: debian package holding the libraries;
o libbobcat1-dev_3.19.01-x_*.deb: debian package holding the libraries, headers and
manual pages;
o http://sourceforge.net/projects/bobcat: public archive location;
BOBCAT
Bobcat is an acronym of `Brokken’s Own Base Classes And Templates’.
COPYRIGHT
This is free software, distributed under the terms of the GNU General Public License
(GPL).
AUTHOR
Frank B. Brokken (f.b.brokken@rug.nl).