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

NAME

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

SYNOPSIS

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

DESCRIPTION

       This  class  is  deprecated:  the  class  FBB::Config (cf. config(3bobcat)) should be used
       instead.

       ConfigFile objects read standard unix-style configuration files.  Lines  are  stored  with
       initial  white-space  (blanks  and tabs) removed.  If a line ends in \, then 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 the comment character (#) is prefixed by a backslash (i.e., \#) it is
       not considered comment, but replaced by a single # character. Likewise, if  the  rmComment
       flag  was  set  two  consecutive  backslash  characters are replaced by a single backslash
       character, In the retrieved configuration information it appears as a single #  character.
       If  the configuration file should contain \# write \\#, this results in replacing \# by #,
       leaving \#.

       All non-empty lines of the configuration file (when comment  is  ignored  comment  is  not
       considered  to  be  line-content)  are stored in the ConfigFile object.  When line indices
       should be stored the (0-based) line indices of lines are available as well.

       At construction time comment handling (keep  comment  /  remove  comment),  case-sensitive
       searching  (sensitive  /  insensitive)  and  index  storage  (store  / don’t store) can be
       specified.

       It can’t be modified using the open member, but overloaded  assignment  is  supported  and
       comment and letter case handling can be modified by set-members.

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

       o      Comment:
              This enumeration has two values:
              ConfigFile::KeepComment is used to indicate that comment on lines must be kept;
              ConfigFile::RemoveComment is used  to  indicate  that  comment  on  lines  must  be
              removed;

       o      SearchCasing:
              This enumeration also has two values:
              ConfigFile::SearchCaseSensitive is used to do case sensitive searches for targets;
              ConfigFile::SearchCaseInsensitive  is  used  to  do  case  insensitive searches for
              targets.

       o      Indices:
              This enumeration also has two values:
              ConfigFile::IgnoreIndices when used, the line numbers of the original configuration
              file are not available;
              ConfigFile::StoreIndices  when used, the line numbers of the original configuration
              file are also available;

TYPES

       The following types are defined by the class ConfigFile:

       o      const_iterator:
              a  const_iterator  is  an  iterator  pointing  to  a  line  (std::string)  of   the
              configuration file;

       o      const_RE_iterator:
              a const_RE_iterator is an iterator pointing to lines matching a regular expression.
              It supports the following operations:

       o      const_RE_iterator &operator++():  the  prefix  increment  operator  increments  the
              iterator  to  point  to  the  next  line  in  the  configuration  file matching the
              iterator’s regular expression;

       o      std::string const &operator*(): the dereferencing operator returns the line of  the
              configuration file the iterator refers to;

       o      std::string  const  *operator->():  the pointer operator returns the address of the
              line of the configuration file the iterator refers to;  const_RE_iterators  can  be
              compared  for  (in)equality  and  they  can  be copy-constructed; const_RE_iterator
              objects are returned by the ConfigFile::beginEndRE member and cannot  otherwise  be
              constructed.

              When  two  const_RE_iterator  objects  are  subtracted the number of lines matching
              their regular expression is returned. E.g., (see below for  a  description  of  the
              functions used in the next example):

                  ConfigFile cf(...)
                  auto iters = cf.beginEndRE("^hello");
                  cout << "There are " << (iters.second - iters.first) <<
                          " lines starting with hello\n";

              The  two const_RE_iterator objects should refer to the same regular expression. The
              provided example illustrates how this is realized using beginEndRE.

              FBB::Pattern is used to perform the regular expression pattern matching.

CONSTRUCTORS

       o      ConfigFile(Comment cType = KeepComment, SearchCasing sType  =  SearchCaseSensitive,
              Indices iType = IgnoreIndices):
              This constructor is used to create an empty ConfigFile object. It is not associated
              with an input stream: the open member can be used for that. The parameters  can  be
              used  to  specify  specific  handling of comment, letter-casing and storage of line
              numbers in the original configuration file.

       o      ConfigFile(std::string const &fname,  Comment  cType  =  KeepComment,  SearchCasing
              sType = SearchCaseSensitive, Indices iType = IgnoreIndices):
              This  constructor  is  used to create a ConfigFile object, which is filled with the
              information from a file whose name is provided as the constructor’s first argument.
              The other parameters are used as described with the first constructor. It throws an
              FBB::Exception exception if the file could not be opened.

OVERLOADED OPERATORS

       o      std::string const &operator[](size_t idx) const:
              This member returns the (0-based) idx-th line of the configuration file.

       Copy and move constructors (and assignment operators) are available.

MEMBER FUNCTIONS

       o      ConfigFile::const_iterator begin() const:
              This member returns a const_iterator to the first line of the configuration file.

       o      ConfigFile::const_iterator end() const:
              This member  returns  a  const_iterator  pointing  beyond  the  last  line  of  the
              configuration file.

       o      std::pair<ConfigFile::const_RE_iterator,             ConfigFile::const_RE_iterator>
              beginEndRE(std::string const &target) const:
              A pair of const_RE_iterators is returned. The first field of the pair  is  a  const
              iterator  to  the  first element (i.e., line) of the ConfigFile object in which the
              regular expression target is found.

              The second field is a const iterator marking the end of the series of lines started
              at the the first line matching the regular expression specified by target.

              If  the  RemoveComment  flag was specified, then comment-text is not searched.  The
              iterator returned in the pair’s first field can be incremented  until  the  iteratr
              returned in the pair’s second field is reached; all iterators (unequal the iterator
              in second) point to lines matching the specified regular expression.

              The iterator’s increment operator searches the next  line  matching  the  specified
              regular expression.

              Although  the  difference  between  two  const_RE_iterators can be computed it is a
              relatively expensive operation. The difference is obtained by  performing  repeated
              regular  expression matchings rather than the mere algebraic subtraction of pointer
              values. If the difference cannot be computed std::numeric_limits<size_t>::max()  is
              returned.

              This member also interprets the SearchCasing flag.

       o      std::pair<ConfigFile::const_RE_iterator,             ConfigFile::const_RE_iterator>
              beginEndRE() const:
              A pair of const_RE_iterators is  returned,  both  marking  the  end  of  a  regular
              expression search.

       o      ConfigFile::const_iterator find(std::string const &target) const:
              This  member  returns  an  iterator  to  the  first  element  (i.e.,  line)  of the
              FBB::ConfigFile object in which target  is  found.  Note  that  target  may  appear
              anywhere  within a line. If the RemoveComment flag was specified, then comment-text
              is not searched. Use the end member  to  determine  the  end-iterator.  It  is  not
              guaranteed  that  all  lines  between the returned iterator and end contain target.
              This member also interprets the SearchCasing flag.

       o      std::string findKey(std::string const &keyPattern, size_t count = 1) const:
              This member can be used to retrieve  information  from  lines  having  the  general
              pattern  `keyPattern value’. Initial and trailing white space on lines are ignored.
              keyPattern itself should not contain initial or trailing white space. At least  one
              white  space  character must appear between keyPattern and value. If at least count
              lines were found matching keyPattern value  then  this  member  returns  the  first
              sequence  of  non  white space characters following keyPattern after matching count
              lines matching keyPattern value (i.e., `value’ is returned). If value is  empty  or
              if  fewer  than  count  lines  match  keyPattern  an  empty  string is returned. An
              FBB::Exception exception is thrown if count equals 0.

       o      std::string findKeyTail(std::string const &keyPattern, size_t count = 1) const:
              This member can be used to retrieve  information  from  lines  having  the  general
              pattern  `keyPattern  value’,  merely followed by white space. Initial and trailing
              white space on lines are ignored. keyPattern itself should not contain  initial  or
              trailing  white  space.  At  least  one  white  space character must appear between
              keyPattern and value.  If at least count lines were found matching keyPattern value
              then  this  member  returns  the information beyond keyPattern after matching count
              lines matching keyPattern (i.e., `value’ is returned). This function  differs  from
              findKey in that all information trailing keyPattern is returned in value.  If value
              is empty or if fewer than count lines match keyPattern an empty string is returned.
              An FBB::Exception exception is thrown if count equals 0.

       o      ConfigFile::const_iterator findRE(std::string const &target) const:
              This member returns an iterator to the first line of the ConfigFile object matching
              the regular expression target. After calling this function  beginEndRE  returns  an
              iterator  pair  whose  first field is an iterator to the same line and whose second
              field is the end-iterator for lines matching target. If the RemoveComment flag  was
              specified, then comment-text is not searched.  The inherited end member can be used
              to determine the end-iterator. It is not guaranteed  that  all  lines  between  the
              returned iterator and end also contain target.

       o      size_t index(size_t idx):
              This  function should only be used when the parameter StoreIndices was specified at
              construction time. In that case it returns the original 0-based line index  in  the
              configuration  file  associated  with  the  idx  (0-based)  index  in  the  current
              Configuration object.

       o      size_t index(const_iterator const &iter):
              This function should only be used when the parameter StoreIndices was specified  at
              construction  time.  In that case it returns the original 0-based line index in the
              configuration  file  associated  with  the  configuration  line  in   the   current
              Configuration  object  pointed to by iter. This may also be an (incremented version
              of the) iterator returned by the member findRE.

       o      void open(std::string const &fname):
              This member reads the configuration file  having  name  fname.   It  redefines  the
              current  content  of  the  ConfigFile object, destroying any information previously
              stored in it. The configuration file is read according to the latest setting of the
              comment-flag. It throws an FBB::Exception exception if the file cannot be opened.

              This  member  clears  previously available information and reinitializes the object
              with information read from the new file.

       o      void setCommentHandling(Comment type):
              This member can be used to change the comment-handling type originally set  by  the
              constructor,  or set by earlier calls of this function. When called it won’t affect
              the current content of the ConfigFile object, but new  calls  of  its  open  member
              reads the configuration file according to the last setting of the comment flag.

       o      void setSearchCasing(SearchCasing type):
              This  member can be used to change the handling of the letter-casing originally set
              by the constructor, or set by earlier calls of this function. When called it  won’t
              affect  the  current  content  of  the ConfigFile object, but new calls of its open
              member  reads  the  configuration  file  according  to  the  last  setting  of  the
              letter-casing flag.

       o      size_t size() const:
              This member returns the number of lines in the configuration file.

EXAMPLE

       Assume the configuration file is called config.rc and contains 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’s extending over multiple lines

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

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

       #include <iostream>
       #include <iterator>
       #include <algorithm>
       #include <string>
       #include <bobcat/configfile>

       using namespace std;
       using namespace FBB;

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

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

                                                // find all lines matching
           auto [begin, end] = cv.beginEndRE("^line:"); // `^line:’

           copy(begin, end, ostream_iterator<string>(cout, "\n"));
       }

       Producing the output:

       noline: this one too
       line: this is found
       line: this one is
       line: what about this one? it’s extending over multiple lines

FILES

       bobcat/configfile - defines the class interface

SEE ALSO

       argconfig(3bobcat), bobcat(7), config(3bobcat) 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).