FBB::Config(3bobcat)
Configuration File Processing
(libbobcat-dev_6.06.02)
2005-2024
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:
    
    -  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;
 
-  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;
 
TYPES
    The following types are defined by the class Config:
    
    -  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);
 
-  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.
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:
    
    -  CF_Line():
 the default constructor initialized its object with line number 0,
        and an empty line;
-  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;
-  std::string const &line() const:
 returns the object's line;
-  std::string key() const:
 returns the line's key field;
-  uint16_t lineNr() const:
 returns the line's line number;
-  std::string tail() const:
 returns the line's tail field (i.e., the info beyond the key);
-  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.
CONSTRUCTORS
    
    -  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;
 
-  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;
 
-  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;
 
-  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;
 
-  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;
 
-  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.
OVERLOADED OPERATORS
    
    -  CF_Line const &operator[](size_t idx) const:
 returns the (0-based) idx-th line of the configuration file.
MEMBER FUNCTIONS
    
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
    -  https://fbb-git.gitlab.io/bobcat/: gitlab project page;
    
-  bobcat_6.06.02-x.dsc: detached signature;
    
-  bobcat_6.06.02-x.tar.gz: source archive;
    
-  bobcat_6.06.02-x_i386.changes: change log;
    
-  libbobcat1_6.06.02-x_*.deb: debian package containing the
            libraries;
    
-  libbobcat1-dev_6.06.02-x_*.deb: debian package containing the
            libraries, headers and manual pages;
    
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).