FBB::ConfigFile(3bobcat)

📦

version 6.15.01 · 7 versions

6.15.01 · ubuntu stonking (latest)
5.11.01 · nixos 26.05, nixpkgs unstable
5.09.01 · ubuntu jammy
6.04.00 · ubuntu noble
6.02.02 · debian bookworm
6.11.00 · ubuntu resolute
6.07.01 · debian trixie, ubuntu questing

, in ubuntu stonking

✨ FBB::ConfigFile ✨

so bestie, welcome to FBB::ConfigFile(3bobcat) — the Configuration File Processing page 💖

💅 NAME 💅

FBB::ConfigFile — a whole class that processes standard unix-like configuration files 🎀

🌸 SYNOPSIS 🌸

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

🦋 DESCRIPTION 🦋

okay first thing first, and I need you to hear me on this one: this class is deprecated 😭. like, it still works, but you should be using the class FBB::Config instead (check config(3bobcat)). periodt.

So. ConfigFile objects read standard unix-style configuration files ✨. The way it works: every line gets stored with its initial white-space (that's blanks and tabs) stripped off. And if a line ends in \? then the next line gets appended to the current one — also with its initial white-space removed. it's giving "continuation line" energy 💫

Now, if the rmComment flag is set to true, blank lines get removed, and so does everything on a line from the first # onward. But — plot twist — if the comment character (#) is prefixed by a backslash (so, \#), it is not treated as a comment. Instead it gets replaced by a single # character. 🫶

Similarly, 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. So if your configuration file should actually contain \#, you write \\# — which results in replacing \# by #, leaving \#. yes queen, the escaping is escaping 💀

Every non-empty line of the configuration file is stored in the ConfigFile object (and when comment is ignored, comment is not considered to be line-content, ok bestie?). And when line indices should be stored, the (0-based) line indices of the lines are available as well 👑

At construction time you get to specify comment handling (keep comment / remove comment), case-sensitive searching (sensitive / insensitive) and index storage (store / don't store). it's giving ✨customizable✨

One thing though: 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 🌈

-

(yeah, nothing. it's giving independent main character energy 👑)

🎀 ENUMERATIONS 🎀

The following enumerations are defined by the class ConfigFile:

Comment — this enumeration has two values:
- ConfigFile::KeepComment — used to indicate that comment on lines must be kept 💖
- ConfigFile::RemoveComment — used to indicate that comment on lines must be removed 🙈
SearchCasing — this enumeration also has two values:
- ConfigFile::SearchCaseSensitive — used to do case sensitive searches for targets 🔍
- ConfigFile::SearchCaseInsensitive — used to do case insensitive searches for targets 🔍
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:

const_iterator — a const_iterator is an iterator pointing to a line (std::string) of the configuration file 🌸
const_RE_iterator — a const_RE_iterator is an iterator pointing to lines matching a regular expression. It supports the following operations:
- 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 ✨
- std::string const &operator*() — the dereferencing operator returns the line of the configuration file the iterator refers to 💖
- 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. iykyk 💅

💜 CONSTRUCTORS 💜

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 🌸
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 😭

The copy and move constructors and assignment operators are available. 🎀

👑 OVERLOADED OPERATORS 👑

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 🫶

ConfigFile::const_iterator begin() const — bestie this just hands you a const_iterator pointing at the first line of the configuration file. The opening act. ✨
ConfigFile::const_iterator end() const — returns a const_iterator pointing beyond the last line of the configuration file. That's your lil' end sentinel, she's not a real line, she's the boundary. 💅
std::pair<ConfigFile::const_RE_iterator, ConfigFile::const_RE_iterator> beginEndRE(std::string const &target) const — you get back a pair of const_RE_iterators, and here's the tea on what's inside:
- 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 that first line matching the regular expression specified by target.
- If the RemoveComment flag was specified, then comment-text is not searched. 🙈
- The iterator in the pair's first field can be incremented until the iterator returned in the pair's second field is reached; all iterators (that aren't equal to 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.
- Ngl, you can compute the difference between two const_RE_iterators, but it's a relatively expensive operation — it's obtained by performing repeated regular expression matchings rather than the mere algebraic subtraction of pointer values. And if the difference can't be computed, std::numeric_limits<size_t>::max() is returned. 💀
- This member also interprets the SearchCasing flag.
std::pair<ConfigFile::const_RE_iterator, ConfigFile::const_RE_iterator> beginEndRE() const — returns a pair of const_RE_iterators, and both of them mark the end of a regular expression search. Two ends, zero content, it's giving "the party's over" 🎀
ConfigFile::const_iterator find(std::string const &target) const — this one returns an iterator to the first element (i.e., line) of the FBB::ConfigFile object in which target is found. Lore drop: 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 — so don't get cocky. This member also interprets the SearchCasing flag. 🔍
std::string findKey(std::string const &keyPattern, size_t count = 1) const — use this cutie 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. And an FBB::Exception exception is thrown if count equals 0. Zero. Nada. She said no. 🚫
std::string findKeyTail(std::string const &keyPattern, size_t count = 1) const — same energy, slightly different flavor: this one retrieves 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). The way this differs from findKey is 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. Same rule, same refusal. ✋
ConfigFile::const_iterator findRE(std::string const &target) const — 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. 🌈
size_t index(size_t idx) const — only use this one 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. 🔢
size_t index(const_iterator const &iter) const — again, only for when the parameter StoreIndices was specified at construction time. Then 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. And surprise: this may also be an (incremented version of the) iterator returned by the member findRE. 🧚
void open(std::string const &fname) — this member reads the configuration file having name fname. Heads up: it redefines the current content of the ConfigFile object, destroying any information previously stored in it. (Gone. Poof. No undo. 😭) 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.

So basically: this member clears previously available information and reinitializes the object with information read from the new file. Fresh start, new me. 💖

void setCommentHandling(Comment type) — use this to change the comment-handling type originally set by the constructor, or set by earlier calls of this function. Important: when called it won't affect the current content of the ConfigFile object — but new calls of its open member read the configuration file according to the last setting of the comment flag. So it's a "settings for next time" kinda girl. 💅
void setSearchCasing(SearchCasing type) — same deal for letter-casing: changes the handling 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 read the configuration file according to the last setting of the letter-casing flag. 🔤
size_t size() const — returns the number of lines in the configuration file. That's it. That's the whole function. Iconic. 👑

🌸 EXAMPLE 🌸

Okay so imagine the configuration file is called config.rc and it contains these 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

Ate, no cap. 🫶

🎀 FILES 🎀

bobcat/configfile — defines the class interface

🦋 SEE ALSO 🦋

💀 BUGS 💀

None Reported.

👑 BOBCAT PROJECT FILES 👑

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

Debian Bobcat project files:

libbobcat6: debian package containing the shared library, changelog and copyright note;
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).

And that's a wrap on the whole page, bestie!! 🥳 This one ships out of libbobcat-dev_6.15.01, dated 2005-2026, and it lives at FBB::ConfigFile(3bobcat) — go forth and configure your little heart out. Mwah. 💖🎀🦋

📦 where this page comes from

ubuntu stonking: libbobcat-dev 6.15.01-1 · GPL-3.0-or-later WITH OpenSSL exception
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms