Manpages

NAME

FBB::Config - A class processing standard unix-like configuration files

SYNOPSIS

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

DESCRIPTION

Config objects process standard unix-style configuration files. Initial white-space (blanks and tabs) are removed from processed lines. If a line ends in a backslash (\), then the backslash is removed and 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 a backslash precedes the comment character (i.e., \#) then this is not considered comment, but it is replaced by a single # character. Similarly, if the rmComment flag was set two consecutive backslash characters are replaced by a single backslash character.

All lines of the configuration file (possibly without comment) are stored in the Config object. Their line numbers can also be retrieved.

At construction time comment handling (keep comment / remove comment) and type of searching (case sensitive / insensitive) can be specified.

In addition to one of the constructors, the load member can be used to processes a configuration file, replacing the object’s current content by the content of another configuration file. The load member cannot be used to alter the configuration file’s processing parameters, but overloaded assignment is supported and comment- and letter-case handling can be modified by set-members.

Often lines in configuration show the following structure:

id: value trailing content

If id is a C++ identifier it is called an ID in this man-page. When looking for IDs all non white-space characters immediately following the ID are ignored (in the example the ID is id). A Key is defined as the first white-space delimited entry on lines. In the example the key is id:. The first space-delimited entry following the key is called the line’s value, whereas all of the line’s content starting at value is called the line’s tail.

Config objects offer various members to process configuration file lines that are structured this way. However, lines do not have to be structured this way. All the lines of a configuration file are made available by Config objects and can be processed in several other ways as well.

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 Config:

This enumeration has two values:
Config::KeepComment specifies that comment on lines must be kept;
Config::NoComment specifies that comment on lines must be removed;

This enumeration also has two values:
Config::UseCase specifies that specified targets must match case-sensitively;
Config::NoCase specifies that specified targets are matched case-insensitively;

TYPES

The following types are defined by the class Config:

a random access iterator referring to a line read from a configuration file. FBB::Config::const_iterator objects point to FBB::CF_Line objects (see the next section for a description of the class CF_Line);

an iterator type referring to lines matching regular expressions or IDs. It supports the standard random access iterator facilities. The dereference operators of FBB::Config::CIVect::const_iterator objects return FBB::Config::const_iterator objects;

When two CIVect::const_iterator objects are subtracted the number of lines matching their regular expressions (or IDs) is returned. E.g.,

Config cf(...)
auto pair = cf.beginEndID("scenario");
cout << "There are " << (pair.second - pair.first) <<
" lines starting with the ID ’scenario’\n";

Pattern(3bobcat) objects are used when looking for lines matching regular expressions.

CF_Line

const_iterators point to objects of the class FBB::CF_Line. Objects of this class contain a line from the configuration file and its line number. The class offers the following facilities:

the default constructor initialized its object with line number 0, and an empty line;

this constructor initialized its object with line number lineNr, and a copy of the contents of line;

returns the object’s line;

returns the line’s key field;

returns the line’s line number;

returns the line’s tail field (i.e., the info beyond the key);

returns the line’s value field (i.e., the first white-space delimited entry following the line’s ID); CF_Line objects may be inserted into std::ostream objects, inserting their lines into the streams.

Copy- and move-constructors and -assignment operators are available.

CONSTRUCTORS

creates an empty object. It is not associated with a configuration file; the load member can be used for that. The parameters specify specific handling of comment, and letter-casing;

creates a Config object, containing the information from the configuration file fname. The other parameters are used as described with the abovementioned constructor. If the file cannot be opened an FBB::Exception exception is thrown;

same functionality as the previous constructor, but reading the configuration information from the std::istream stream;

same functionality as the previous constructor, but the line number of the first line read from stream is set to lineNr;

same functionality as the constructor expecting an istream reference, but this time the configuration information is read from the std::istream rvalue reference tmp;

same functionality as the previous constructor, but the line number of the first line read from stream is set to lineNr.

Copy- and move-constructors and -assignment operators are available.

OVERLOADED OPERATORS

returns the (0-based) idx-th line of the configuration file.

MEMBER FUNCTIONS

returns a const_iterator referring to the first line of the configuration file;

returns a pair of CIVect::const_iterators. Its first field is an CIVect::const_iterator referring to the first line containing ID id; its second field is a CIVect::const_iterator marking the end of the series of lines containing ID id.

The difference between the two iterators equals the number of lines containing ID id;

same functionality as the previous member, but returning a pair of iterators to lines matching regex;

returns a const_iterator pointing beyond the last line of the configuration file;

clears the current content of the Config object. This member is automatically called by the load members;

returns an iterator to the first line containing target, starting the search at begin(). Note that target may appear anywhere within a line. It returns end() if no such line was found;

same functionality as the previous member, but searching starts at from;

returns an iterator of the the first line containing ID id. It returns end() if no such line was found;

same functionality as the previous member, but searching starts at from;

returns an iterator of the the first line containing key ’key’. It returns end() if no such line was found;

same functionality as the previous member, but searching starts at from;

returns an iterator is returned to the first line matching the regular expression regex. It returns end() if no such line was found;

the content of the file named fname is stored in the Config object, replacing any previously stored content. The file is read according to the latest setting of the Comment and Casing flags. If the file cannot be opened an FBB::Exception exception is thrown;

same functionality as the previous member, but reading the configuration information from the std::istream reference stream. The lineNr value specifies the line number of the first read line;

same functionality as the previous member, but reading the configuration information from the std::istream rvalue reference tmp;

the object’s comment-handling type is set to ’type’ (ether KeepComment or NoComment). It doesn’t affect the current content of the Config object, but when calling load the configuration file is processed according to type’s value;

the object’s letter case handling type is set to ’type’ (either UseCase or NoCase);

returns the number of lines stored in the Config object;

EXAMPLE

Assume the configuration file is named config.rc, containing 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 extends over multiple lines

and there may, of course, be more lines in this file

The next program may be compiled and run as a.out config.rc:

#include <iostream>
#include <algorithm>
#include <string>
#include <bobcat/config>

using namespace std;
using namespace FBB;

int main(int argc, char **argv)
{
Config cf(argv[1]);

cout << *cf.find("this one") << ’\n’; // find text within a line

// find all lines specifying ID ’line’
auto [begin, end] = cv.beginEndID("line");
copy(begin, end, ostream_iterator<CF_Line>(cout, "\n"));
}

Producing the output:

line: this is found
line: this one is
line: what about this one? it extends over multiple lines

FILES

bobcat/config - defines the class interface

SEE ALSO

argconfig(3bobcat), bobcat(7), exception(3bobcat), pattern(3bobcat)

BUGS

None reported

BOBCAT PROJECT FILES

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 [AT] rug.nl).