FBB::ConfigFileile(3) A class processing standard unix-like configuration files

SYNOPSIS

#include <bobcat/configfile>
Linking option: -lbobcat

DESCRIPTION

FBB::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.

Information at and beyond the first # on individual lines is removed if the rmComment flag is set to true. In that case, lines containing only blanks and tabs are not stored.

NAMESPACE

FBB
All constructors, members, operators and manipulators, mentioned in this man-page, are defined in the namespace FBB.

INHERITS FROM

std::vector<std::string>

ENUMERATIONS

The following enumerations are defined by the class FBB::ConfigFile:
  • Comment:
    This enumeration has two values:
    FBB::ConfigFile::KeepComment is used to indicate that comment on lines must be kept;
    FBB::ConfigFile::RemoveComment is used to indicate that comment on lines must be removed;
  • SearchCasing:
    This enumeration also has two values:
    FBB::ConfigFile::SearchCaseSensitive is used to do case sensitive searches for targets;
    FBB::ConfigFile::SearchCaseInsensitive is used to do case insensitive searches for targets.
  • Indices:
    This enumeration also has two values:
    FBB::ConfigFile::IgnoreIndices when used, the line numbers of the original configuration file will not be made available;
    FBB::ConfigFile::StoreIndices when used, the line numbers of the original configuration file will be made available;

CONSTRUCTORS

  • ConfigFile(Comment cType = KeepComment, SearchCasing sType = SearchCaseSensitive, Indices iType = IgnoreIndices):
    This constructor is used to create an empty FBB::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.
  • ConfigFile(std::string const &fname, Comment cType = KeepComment, SearchCasing sType = SearchCaseSensitive, Indices iType = IgnoreIndices):
    This constructor is used to create a FBB::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. The copy constructor is available.

OVERLOADED OPERATORS

  • std::string const &operator[](size_t idx) const:
    This member overloads the inherited std::string &std::vector<std::string>::operator[](size_t idx) offering a basic protection against accidentally modifying the configuration file's lines by clients.

MEMBER FUNCTIONS

All members of std::vector<std::string> are available, as FBB::ConfigFile inherits from this class.
o
ConfigFile::const_RE_iterator beginRE(std::string const &target) const:
This member returns a const iterator to the first element (i.e., line) of the FBB::ConfigFile object in which the regular expression target is found. FBB::Pattern is used to perform the pattern matching. If the RemoveComment flag was specified, then comment-text is not searched. The returned iterator can be incremented until endRe() is reached; all iterators will point to lines matching the specified regular expression. When increment operator will search for 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 UINT_MAX is returned.
This member also interprets the SearchCasing flag.
o
ConfigFile::const_RE_iterator endRE() const:
This member returns a const iterator marking the end of the series of lines started at the the first line matching the regular expression specified by beginRE()
o
ConfigFile::const_iterator find(std::string const &target) const:
This member will return 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 FBB::ConfigFile::end() member to determine the end-iterator. It is not guaranteed that all lines between the returned iterator and end() will also contain target. This member also interprets the SearchCasing flag.
o
std::string findKey(std::string const &keyPattern, size_t nr = 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 is ignored. keyPattern itself should not contain white space. At least one white space character must appear between keyPattern and value. If at least nr lines were found matching keyPattern then the member returns the first series of non white space characters beyond value of the nr line. Otherwise an empty string is returned.
o
std::string findKeyTail(std::string const &keyPattern, size_t nr = 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 is ignored. keyPattern itself should not contain white space. At least one white space character must appear between keyPattern and value. If at least nr lines were found matching keyPattern then the member returns the (white space trimmed) contents of the text beyond keyPattern of the nr line. Otherwise an empty string is returned. The member findKeyTail uses the member findRE() (see below) to retrieve lines matching keyPattern.
o
ConfigFile::const_iterator findRE(std::string const &target) const:
This member returns an iterator to the first element (i.e., line) of the FBB::ConfigFile object in which the regular expression target is found. FBB::Pattern is used to perform the pattern matching. If the RemoveComment flag was specified, then comment-text is not searched. The inherited FBB::ConfigFile::end() member can be used to determine the end-iterator. It is not guaranteed that all lines between the returned iterator and end() will 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 will return the original 0-based line index in the configuration file associated with the idxsup(th) (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 will return 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 will read the configuration file having name fname. It will redefine the current contents of the FBB::ConfigFile 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 FBB::Errno exception if the file could not be opened.
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 FBB::ConfigFile object, but new calls of its open() member will read 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 FBB::ConfigFile object, but new calls of its open() member will read the configuation file according to the last setting of the letter-casing flag.

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

BUGS

None Reported.

DISTRIBUTION FILES

  • bobcat_2.08.01-x.dsc: detached signature;
  • bobcat_2.08.01-x.tar.gz: source archive;
  • bobcat_2.08.01-x_i386.changes: change log;
  • libbobcat1_2.08.01-x_*.deb: debian package holding the libraries;
  • libbobcat1-dev_2.08.01-x_*.deb: debian package holding the libraries, headers and manual pages;
  • 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 ([email protected]).

SEE ALSO

LAST SEARCHED