config

FBB::Config(3bobcat)      Configuration File Processing     FBB::Config(3bobcat)



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:

       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;


TYPES
       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.

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:

       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.

CONSTRUCTORS
       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.

OVERLOADED OPERATORS
       o      CF_Line const &operator[](size_t idx) const:
              returns the (0-based) idx-th line of the configuration file.


MEMBER FUNCTIONS
       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 &regex) 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 &regex) 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;


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
       o      https://fbb-git.gitlab.io/bobcat/: gitlab project page;

       o      bobcat_5.09.01-x.dsc: detached signature;

       o      bobcat_5.09.01-x.tar.gz: source archive;

       o      bobcat_5.09.01-x_i386.changes: change log;

       o      libbobcat1_5.09.01-x_*.deb: debian package containing the
              libraries;

       o      libbobcat1-dev_5.09.01-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).

libbobcat-dev_5.09.01               2005-2021               FBB::Config(3bobcat)