Provided by: libbobcat-dev_6.04.00-1ubuntu3_amd64 bug

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_6.04.00-x.dsc: detached signature;

       o      bobcat_6.04.00-x.tar.gz: source archive;

       o      bobcat_6.04.00-x_i386.changes: change log;

       o      libbobcat1_6.04.00-x_*.deb: debian package containing the libraries;

       o      libbobcat1-dev_6.04.00-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).