FBB::Config - A class processing standard unix-like configuration
files
#include <bobcat/config>
Linking option: -lbobcat
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.
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
Config:
- o
- Comment:
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;
- o
- Casing:
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;
The following types are defined by the class Config:
- o
- const_iterator:
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);
- o
- CIVect::const_iterator:
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.
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:
- o
- CF_Line():
the default constructor initialized its object with line number 0, and an
empty line;
- o
- CF_Line(uint16_t lineNr, std::string const &line):
this constructor initialized its object with line number lineNr, and
a copy of the contents of line;
- o
- std::string const &line() const:
returns the object’s line;
- o
- std::string key() const:
returns the line’s key field;
- o
- uint16_t lineNr() const:
returns the line’s line number;
- o
- std::string tail() const:
returns the line’s tail field (i.e., the info beyond the
key);
- o
- std::string value() const:
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.
- o
- Config(Casing sType = UseCase, Comment cType = NoComment):
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;
- o
- Config(std::string const &fname, Casing sType = UseCase,
Comment cType = NoComment):
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;
- o
- Config(std::istream &stream, Casing sType = UseCase, Comment
cType = NoComment):
same functionality as the previous constructor, but reading the
configuration information from the std::istream stream;
- o
- Config(std::istream &stream, uint16_t lineNr, Casing sType =
UseCase, Comment cType = NoComment):
same functionality as the previous constructor, but the line number of the
first line read from stream is set to lineNr;
- o
- Config(std::istream &&tmp, Casing sType = UseCase,
Comment cType = NoComment):
same functionality as the constructor expecting an istream reference,
but this time the configuration information is read from the
std::istream rvalue reference tmp;
- o
- Config(std::istream &&tmp, uint16_t lineNr, Casing sType =
UseCase, Comment cType = NoComment):
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.
- o
- CF_Line const &operator[](size_t idx) const:
returns the (0-based) idx-th line of the configuration file.
- o
- const_iterator begin() const:
returns a const_iterator referring to the first line of the
configuration file;
- o
- std::pair<CIVect::const_iterator, CIVect::const_iterator>
beginEndID(std::string const &rid) const:
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;
- o
- std::pair<CIVect::const_iterator, CIVect::const_iterator>
beginEndRE(std::string const ®ex) const:
same functionality as the previous member, but returning a pair of iterators
to lines matching regex;
- o
- const_iterator end() const:
returns a const_iterator pointing beyond the last line of the
configuration file;
- o
- void clear():
clears the current content of the Config object. This member is
automatically called by the load members;
- o
- const_iterator find(std::string const &target) const:
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;
- o
- const_iterator find(std::string const &target, const_iterator
from) const:
same functionality as the previous member, but searching starts at
from;
- o
- const_iterator findID(std::string const &id) const:
returns an iterator of the the first line containing ID id. It
returns end() if no such line was found;
- o
- const_iterator findID(std::string const &id, const_iterator
from) const:
same functionality as the previous member, but searching starts at
from;
- o
- const_iterator findKey(std::string const &key) const:
returns an iterator of the the first line containing key
`key’. It returns end() if no such line was
found;
- o
- const_iterator findKey(std::string const &key, const_iterator
from) const:
same functionality as the previous member, but searching starts at
from;
- o
- const_iterator findRE(std::string const ®ex) const:
returns an iterator is returned to the first line matching the regular
expression regex. It returns end() if no such line was
found;
- o
- void load(std::string const &fname):
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;
- o
- void load(std::istream &stream, uint16_t lineNr = 1):
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;
- o
- void load(std::istream &&tmp, uint16_t lineNr = 1):
same functionality as the previous member, but reading the configuration
information from the std::istream rvalue reference tmp;
- o
- void setComment(Comment type):
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;
- o
- void setCasing(Casing type):
the object’s letter case handling type is set to
’type’ (either UseCase or NoCase);
- o
- size_t size() const:
returns the number of lines stored in the Config object;
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
bobcat/config - defines the class interface
- o
- https://fbb-git.gitlab.io/bobcat/: gitlab project page;
- o
- bobcat_6.02.02-x.dsc: detached signature;
- o
- bobcat_6.02.02-x.tar.gz: source archive;
- o
- bobcat_6.02.02-x_i386.changes: change log;
- o
- libbobcat1_6.02.02-x_*.deb: debian package containing the
libraries;
- o
- libbobcat1-dev_6.02.02-x_*.deb: debian package containing the
libraries, headers and manual pages;
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).