--- name: "configfile" section: "3bobcat" platform: "linux" package: "libbobcat-dev" version: "6.07.01-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/configfile" --- # configfile(3bobcat) A class processing standard unix-like configuration files ## NAME FBB::ConfigFile - A class processing standard unix-like configuration files ## SYNOPSIS **#include \**\ Linking option: *-lbobcat* ## DESCRIPTION This class is deprecated: the class **FBB::Config** (cf. [**config**(3bobcat)](/config/3bobcat.md)) 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\_iterator*s 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\** **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\::max()* is returned. - This member also interprets the *SearchCasing* flag. - - o **std::pair\** **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 #include #include #include #include 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(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)](/argconfig/3bobcat.md), [**bobcat**(7)](/bobcat/7.md), [**config**(3bobcat)](/config/3bobcat.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**).