.TH "FBB::ConfigFile" "3bobcat" "2005\-2020" "libbobcat\-dev_5\&.07\&.00" "Configuration File Processing" .PP .SH "NAME" FBB::ConfigFile \- A class processing standard unix\-like configuration files .PP .SH "SYNOPSIS" \fB#include \fP .br Linking option: \fI\-lbobcat\fP .PP .SH "DESCRIPTION" This class is deprecated: the class \fBFBB::Config\fP (cf\&. \fBconfig\fP(3bobcat)) should be used instead\&. .PP \fBConfigFile\fP objects read standard \fIunix\fP\-style configuration files\&. Lines are stored with initial white\-space (blanks and tabs) removed\&. If a line ends in \e, then the next line (initial white\-space removed) is appended to the current line\&. .PP If the \fIrmComment\fP flag is set to \fItrue\fP blanks lines and information on lines from the first \fI#\fP are removed\&. If the comment character (\fI#\fP) is prefixed by a backslash (i\&.e\&., \fI\e#\fP) it is not considered comment, but replaced by a single \fI#\fP character\&. Likewise, if the \fIrmComment\fP flag was set two consecutive backslash characters are replaced by a single backslash character, In the retrieved configuration information it appears as a single \fI#\fP character\&. If the configuration file should contain \fI\e#\fP write \fI\e\e#\fP, this results in replacing \fI\e#\fP by \fI#\fP, leaving \fI\e#\fP\&. .PP All non\-empty lines of the configuration file (when comment is ignored comment is not considered to be line\-content) are stored in the \fBConfigFile\fP object\&. When line indices should be stored the (0\-based) line indices of lines are available as well\&. .PP At construction time comment handling (keep comment / remove comment), case\-sensitive searching (sensitive / insensitive) and index storage (store / don\(cq\&t store) can be specified\&. .PP It can\(cq\&t be modified using the \fIopen\fP member, but overloaded assignment is supported and comment and letter case handling can be modified by set\-members\&. .PP .SH "NAMESPACE" \fBFBB\fP .br All constructors, members, operators and manipulators, mentioned in this man\-page, are defined in the namespace \fBFBB\fP\&. .PP .SH "INHERITS FROM" \- .PP .SH "ENUMERATIONS" The following enumerations are defined by the class \fBConfigFile\fP: .IP o \fBComment\fP: .br This enumeration has two values: .br \fBConfigFile::KeepComment\fP is used to indicate that comment on lines must be kept; .br \fBConfigFile::RemoveComment\fP is used to indicate that comment on lines must be removed; .IP o \fBSearchCasing\fP: .br This enumeration also has two values: .br \fBConfigFile::SearchCaseSensitive\fP is used to do case sensitive searches for targets; .br \fBConfigFile::SearchCaseInsensitive\fP is used to do case insensitive searches for targets\&. .IP o \fBIndices\fP: .br This enumeration also has two values: .br \fBConfigFile::IgnoreIndices\fP when used, the line numbers of the original configuration file are not available; .br \fBConfigFile::StoreIndices\fP when used, the line numbers of the original configuration file are also available; .br .PP .SH "TYPES" The following types are defined by the class \fIConfigFile\fP: .IP o \fBconst_iterator\fP: .br a \fIconst_iterator\fP is an iterator pointing to a line (\fIstd::string\fP) of the configuration file; .IP o \fBconst_RE_iterator\fP: .br a \fIconst_RE_iterator\fP is an iterator pointing to lines matching a regular expression\&. It supports the following operations: .IP o \fIconst_RE_iterator &operator++()\fP: the prefix increment operator increments the iterator to point to the next line in the configuration file matching the iterator\(cq\&s regular expression; .IP o \fIstd::string const &operator*()\fP: the dereferencing operator returns the line of the configuration file the iterator refers to; .IP o \fIstd::string const *operator\->()\fP: the pointer operator returns the address of the line of the configuration file the iterator refers to; \fIconst_RE_iterator\fPs can be compared for (in)equality and they can be copy\-constructed; \fIconst_RE_iterator\fP objects are returned by the \fIConfigFile::beginEndRE\fP member and cannot otherwise be constructed\&. .IP When two \fIconst_RE_iterator\fP 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): .nf ConfigFile cf(\&.\&.\&.) auto iters = cf\&.beginEndRE(\(dq\&^hello\(dq\&); cout << \(dq\&There are \(dq\& << (iters\&.second \- iters\&.first) << \(dq\& lines starting with hello\en\(dq\&; .fi The two \fIconst_RE_iterator\fP objects should refer to the same regular expression\&. The provided example illustrates how this is realized using \fIbeginEndRE\fP\&. .IP \fIFBB::Pattern\fP is used to perform the regular expression pattern matching\&. .PP .SH "CONSTRUCTORS" .IP o \fBConfigFile(Comment cType = KeepComment, SearchCasing sType = SearchCaseSensitive, Indices iType = IgnoreIndices)\fP: .br This constructor is used to create an empty \fBConfigFile\fP object\&. It is not associated with an input stream: the \fIopen\fP 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\&. .IP o \fBConfigFile(std::string const &fname, Comment cType = KeepComment, SearchCasing sType = SearchCaseSensitive, Indices iType = IgnoreIndices)\fP: .br This constructor is used to create a \fBConfigFile\fP object, which is filled with the information from a file whose name is provided as the constructor\(cq\&s first argument\&. The other parameters are used as described with the first constructor\&. It throws an \fIFBB::Exception\fP exception if the file could not be opened\&. .PP .SH "OVERLOADED OPERATORS" .IP o \fBstd::string const &operator[](size_t idx) const\fP: .br This member returns the (0\-based) \fIidx\fP\-th line of the configuration file\&. .PP Copy and move constructors (and assignment operators) are available\&. .PP .SH "MEMBER FUNCTIONS" .IP o \fBConfigFile::const_iterator begin() const\fP: .br This member returns a \fIconst_iterator\fP to the first line of the configuration file\&. .IP .IP o \fBConfigFile::const_iterator end() const\fP: .br This member returns a \fIconst_iterator\fP pointing beyond the last line of the configuration file\&. .IP .IP o \fBstd::pair beginEndRE(std::string const &target) const\fP: .br A pair of \fIconst_RE_iterators\fP is returned\&. The \fIfirst\fP field of the pair is a \fIconst\fP iterator to the first element (i\&.e\&., line) of the \fBConfigFile\fP object in which the regular expression \fItarget\fP is found\&. .IP The \fIsecond\fP field is a \fIconst\fP iterator marking the end of the series of lines started at the the first line matching the regular expression specified by \fItarget\fP\&. .IP If the \fIRemoveComment\fP flag was specified, then comment\-text is not searched\&. The iterator returned in the pair\(cq\&s \fIfirst\fP field can be incremented until the iteratr returned in the pair\(cq\&s \fIsecond\fP field is reached; all iterators (unequal the iterator in \fIsecond\fP) point to lines matching the specified regular expression\&. .IP The iterator\(cq\&s increment operator searches the next line matching the specified regular expression\&. .IP Although the difference between two \fIconst_RE_iterators\fP 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 \fIstd::numeric_limits::max()\fP is returned\&. .IP This member also interprets the \fISearchCasing\fP flag\&. .IP .IP o \fBstd::pair beginEndRE() const\fP: .br A pair of \fIconst_RE_iterators\fP is returned, both marking the end of a regular expression search\&. .IP .IP o \fBConfigFile::const_iterator find(std::string const &target) const\fP: .br This member returns an iterator to the first element (i\&.e\&., line) of the \fIFBB::ConfigFile\fP object in which \fItarget\fP is found\&. Note that \fItarget\fP may appear anywhere within a line\&. If the \fIRemoveComment\fP flag was specified, then comment\-text is not searched\&. Use the \fIend\fP member to determine the end\-iterator\&. It is not guaranteed that all lines between the returned iterator and \fIend\fP contain \fItarget\fP\&. This member also interprets the \fISearchCasing\fP flag\&. .IP .IP o \fBstd::string findKey(std::string const &keyPattern, size_t count = 1) const\fP: .br This member can be used to retrieve information from lines having the general pattern `\fIkeyPattern value\fP\(cq\&\&. Initial and trailing white space on lines are ignored\&. \fIkeyPattern\fP itself should not contain initial or trailing white space\&. At least one white space character must appear between \fIkeyPattern\fP and \fIvalue\fP\&. If at least \fIcount\fP lines were found matching \fIkeyPattern value\fP then this member returns the first sequence of non white space characters following \fIkeyPattern\fP after matching \fIcount\fP lines matching \fIkeyPattern value\fP (i\&.e\&., `\fIvalue\fP\(cq\& is returned)\&. If \fIvalue\fP is empty or if fewer than \fIcount\fP lines match \fIkeyPattern\fP an empty string is returned\&. An \fIFBB::Exception\fP exception is thrown if \fIcount\fP equals 0\&. .IP .IP o \fBstd::string findKeyTail(std::string const &keyPattern, size_t count = 1) const\fP: .br This member can be used to retrieve information from lines having the general pattern `\fIkeyPattern value\fP\(cq\&, merely followed by white space\&. Initial and trailing white space on lines are ignored\&. \fIkeyPattern\fP itself should not contain initial or trailing white space\&. At least one white space character must appear between \fIkeyPattern\fP and \fIvalue\fP\&. If at least \fIcount\fP lines were found matching \fIkeyPattern value\fP then this member returns the information beyond \fIkeyPattern\fP after matching \fIcount\fP lines matching \fIkeyPattern\fP (i\&.e\&., `\fIvalue\fP\(cq\& is returned)\&. This function differs from \fIfindKey\fP in that all information trailing \fIkeyPattern\fP is returned in \fIvalue\fP\&. If \fIvalue\fP is empty or if fewer than \fIcount\fP lines match \fIkeyPattern\fP an empty string is returned\&. An \fIFBB::Exception\fP exception is thrown if \fIcount\fP equals 0\&. .IP .IP o \fBConfigFile::const_iterator findRE(std::string const &target) const\fP: .br This member returns an iterator to the first line of the \fBConfigFile\fP object matching the regular expression \fItarget\fP\&. After calling this function \fIbeginEndRE\fP returns an iterator pair whose \fIfirst\fP field is an iterator to the same line and whose \fIsecond\fP field is the end\-iterator for lines matching \fItarget\fP\&. If the \fIRemoveComment\fP flag was specified, then comment\-text is not searched\&. The inherited \fIend\fP member can be used to determine the end\-iterator\&. It is not guaranteed that all lines between the returned iterator and \fIend\fP also contain \fItarget\fP\&. .IP .IP o \fBsize_t index(size_t idx)\fP: .br This function should only be used when the parameter \fIStoreIndices\fP was specified at construction time\&. In that case it returns the original 0\-based line index in the configuration file associated with the \fIidx\fP (0\-based) index in the current \fIConfiguration\fP object\&. .IP .IP o \fBsize_t index(const_iterator const &iter)\fP: .br This function should only be used when the parameter \fIStoreIndices\fP 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 \fIConfiguration\fP object pointed to by \fIiter\fP\&. This may also be an (incremented version of the) iterator returned by the member \fIfindRE\fP\&. .IP .IP o \fBvoid open(std::string const &fname)\fP: .br This member reads the configuration file having name \fIfname\fP\&. It redefines the current content of the \fBConfigFile\fP 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 \fIFBB::Exception\fP exception if the file cannot be opened\&. .IP This member clears previously available information and reinitializes the object with information read from the new file\&. .IP .IP o \fBvoid setCommentHandling(Comment type)\fP: .br 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\(cq\&t affect the current content of the \fBConfigFile\fP object, but new calls of its \fIopen\fP member reads the configuration file according to the last setting of the comment flag\&. .IP .IP o \fBvoid setSearchCasing(SearchCasing type)\fP: .br 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\(cq\&t affect the current content of the \fBConfigFile\fP object, but new calls of its \fIopen\fP member reads the configuration file according to the last setting of the letter\-casing flag\&. .IP .IP o \fBsize_t size() const\fP: .br This member returns the number of lines in the configuration file\&. .PP .SH "EXAMPLE" Assume the configuration file is called \fIconfig\&.rc\fP and contains the following lines: .PP .nf # 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? \e it\(cq\&s extending over multiple lines and there may, of course, be more lines in this file .fi .PP The following program may be compiled and run as \fIa\&.out config\&.rc\fP: .nf #include #include #include #include #include using namespace std; using namespace FBB; int main(int argc, char **argv) { ConfigFile cf(argv[1]); cout << *cf\&.find(\(dq\&this one\(dq\&) << \(cq\&\en\(cq\&; // find text within a line // find all lines matching auto [begin, end] = cv\&.beginEndRE(\(dq\&^line:\(dq\&); // `^line:\(cq\& copy(begin, end, ostream_iterator(cout, \(dq\&\en\(dq\&)); } .fi .PP Producing the output: .nf noline: this one too line: this is found line: this one is line: what about this one? it\(cq\&s extending over multiple lines .fi .PP .SH "FILES" \fIbobcat/configfile\fP \- defines the class interface .PP .SH "SEE ALSO" \fBargconfig\fP(3bobcat), \fBbobcat\fP(7), \fBconfig\fP(3bobcat) \fBexception\fP(3bobcat), \fBpattern\fP(3bobcat) .PP .SH "BUGS" None Reported\&. .PP .SH "BOBCAT PROJECT FILES" .PP .IP o \fIhttps://fbb\-git\&.gitlab\&.io/bobcat/\fP: gitlab project page; .IP o \fIbobcat_5\&.07\&.00\-x\&.dsc\fP: detached signature; .IP o \fIbobcat_5\&.07\&.00\-x\&.tar\&.gz\fP: source archive; .IP o \fIbobcat_5\&.07\&.00\-x_i386\&.changes\fP: change log; .IP o \fIlibbobcat1_5\&.07\&.00\-x_*\&.deb\fP: debian package containing the libraries; .IP o \fIlibbobcat1\-dev_5\&.07\&.00\-x_*\&.deb\fP: debian package containing the libraries, headers and manual pages; .PP .SH "BOBCAT" Bobcat is an acronym of `Brokken\(cq\&s Own Base Classes And Templates\(cq\&\&. .PP .SH "COPYRIGHT" This is free software, distributed under the terms of the GNU General Public License (GPL)\&. .PP .SH "AUTHOR" Frank B\&. Brokken (\fBf\&.b\&.brokken@rug\&.nl\fP)\&. .PP