---
name: "config"
section: "3bobcat"
platform: "linux"
package: "libbobcat-dev"
version: "6.07.01-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/config/3bobcat"
---

# config(3bobcat)

A class processing standard unix-like configuration files

## 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)](/argconfig/3bobcat.md), [**bobcat**(7)](/bobcat/7.md), [**exception**(3bobcat)](/exception/3bobcat.md), [**pattern**(3bobcat)](/pattern/3bobcat.md)

## BUGS

None reported

## BOBCAT PROJECT FILES

- o

  *https://fbb-git.gitlab.io/bobcat/*: gitlab project page;

Debian Bobcat project files:

- o

  *libbobcat6*: debian package containing the shared library, changelog and copyright note;

- o

  *libbobcat-dev*: debian package containing the static library, headers, manual pages, and developer info;

## 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**).