.TH "FBB::Config" "3bobcat" "2005\-2023" "libbobcat\-dev_6\&.04\&.00" "Configuration File Processing" .PP .SH "NAME" FBB::Config \- A class processing standard unix\-like configuration files .PP .SH "SYNOPSIS" \fB#include \fP .br Linking option: \fI\-lbobcat\fP .PP .SH "DESCRIPTION" \fBConfig\fP objects process standard \fIunix\fP\-style configuration files\&. Initial white\-space (blanks and tabs) are removed from processed lines\&. If a line ends in a backslash (\e), then the backslash is removed and 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 a backslash precedes the comment character (i\&.e\&., \fI\e#\fP) then this is not considered comment, but it is replaced by a single \fI#\fP character\&. Similarly, if the \fIrmComment\fP flag was set two consecutive backslash characters are replaced by a single backslash character\&. .PP All lines of the configuration file (possibly without comment) are stored in the \fBConfig\fP object\&. Their line numbers can also be retrieved\&. .PP At construction time comment handling (keep comment / remove comment) and type of searching (case sensitive / insensitive) can be specified\&. .PP In addition to one of the constructors, the \fIload\fP member can be used to processes a configuration file, replacing the object\(cq\&s current content by the content of another configuration file\&. The \fIload\fP member cannot be used to alter the configuration file\(cq\&s processing parameters, but overloaded assignment is supported and comment\- and letter\-case handling can be modified by set\-members\&. .PP Often lines in configuration show the following structure: .nf id: value trailing content .fi If \fIid\fP is a \fBC++\fP identifier it is called an \fIID\fP in this man\-page\&. When looking for \fIIDs\fP all non white\-space characters immediately following the \fIID\fP are ignored (in the example the ID is \fIid\fP)\&. A \fIKey\fP is defined as the first white\-space delimited entry on lines\&. In the example the key is \fIid:\fP\&. The first space\-delimited entry following the key is called the line\(cq\&s \fIvalue\fP, whereas all of the line\(cq\&s content starting at \fIvalue\fP is called the line\(cq\&s \fItail\fP\&. .PP \fIConfig\fP 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 \fIConfig\fP objects and can be processed in several other ways as well\&. .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 \fBConfig\fP: .IP o \fBComment\fP: .br This enumeration has two values: .br \fBConfig::KeepComment\fP specifies that comment on lines must be kept; .br \fBConfig::NoComment\fP specifies that comment on lines must be removed; .IP .IP o \fBCasing\fP: .br This enumeration also has two values: .br \fBConfig::UseCase\fP specifies that specified targets must match case\-sensitively; .br \fBConfig::NoCase\fP specifies that specified targets are matched case\-insensitively; .br .PP .SH "TYPES" The following types are defined by the class \fIConfig\fP: .IP o \fBconst_iterator\fP: .br a random access iterator referring to a line read from a configuration file\&. \fIFBB::Config::const_iterator\fP objects point to \fIFBB::CF_Line\fP objects (see the next section for a description of the class \fICF_Line\fP); .IP .IP o \fBCIVect::const_iterator\fP: .br an iterator type referring to lines matching regular expressions or IDs\&. It supports the standard random access iterator facilities\&. The dereference operators of \fIFBB::Config::CIVect::const_iterator\fP objects return \fIFBB::Config::const_iterator\fP objects; .PP When two \fICIVect::const_iterator\fP objects are subtracted the number of lines matching their regular expressions (or IDs) is returned\&. E\&.g\&., .nf Config cf(\&.\&.\&.) auto pair = cf\&.beginEndID(\(dq\&scenario\(dq\&); cout << \(dq\&There are \(dq\& << (pair\&.second \- pair\&.first) << \(dq\& lines starting with the ID `scenario\(cq\&\en\(dq\&; .fi .PP \fBPattern\fP(3bobcat) objects are used when looking for lines matching regular expressions\&. .PP .SH "CF_Line" .PP \fIconst_iterators\fP point to objects of the class \fIFBB::CF_Line\fP\&. Objects of this class contain a line from the configuration file and its line number\&. The class offers the following facilities: .IP o \fBCF_Line()\fP: .br the default constructor initialized its object with line number 0, and an empty line; .IP o \fBCF_Line(uint16_t lineNr, std::string const &line)\fP: .br this constructor initialized its object with line number \fIlineNr\fP, and a copy of the contents of \fIline\fP; .IP o \fBstd::string const &line() const\fP: .br returns the object\(cq\&s line; .IP o \fBstd::string key() const\fP: .br returns the line\(cq\&s \fIkey\fP field; .IP o \fBuint16_t lineNr() const\fP: .br returns the line\(cq\&s line number; .IP o \fBstd::string tail() const\fP: .br returns the line\(cq\&s \fItail\fP field (i\&.e\&., the info beyond the \fIkey\fP); .IP o \fBstd::string value() const\fP: .br returns the line\(cq\&s \fIvalue\fP field (i\&.e\&., the first white\-space delimited entry following the line\(cq\&s ID); \fICF_Line\fP objects may be inserted into \fIstd::ostream\fP objects, inserting their lines into the streams\&. .PP Copy\- and move\-constructors and \-assignment operators are available\&. .PP .SH "CONSTRUCTORS" .IP o \fBConfig(Casing sType = UseCase, Comment cType = NoComment)\fP: .br creates an empty object\&. It is not associated with a configuration file; the \fIload\fP member can be used for that\&. The parameters specify specific handling of comment, and letter\-casing; .IP .IP o \fBConfig(std::string const &fname, Casing sType = UseCase, Comment cType = NoComment)\fP: .br creates a \fBConfig\fP object, containing the information from the configuration file \fIfname\fP\&. The other parameters are used as described with the abovementioned constructor\&. If the file cannot be opened an \fIFBB::Exception\fP exception is thrown; .IP .IP o \fBConfig(std::istream &stream, Casing sType = UseCase, Comment cType = NoComment)\fP: .br same functionality as the previous constructor, but reading the configuration information from the \fIstd::istream stream\fP; .IP .IP o \fBConfig(std::istream &stream, uint16_t lineNr, Casing sType = UseCase, Comment cType = NoComment)\fP: .br same functionality as the previous constructor, but the line number of the first line read from \fIstream\fP is set to \fIlineNr\fP; .IP .IP o \fBConfig(std::istream &&tmp, Casing sType = UseCase, Comment cType = NoComment)\fP: .br same functionality as the constructor expecting an \fIistream\fP reference, but this time the configuration information is read from the \fIstd::istream\fP rvalue reference \fItmp\fP; .IP .IP o \fBConfig(std::istream &&tmp, uint16_t lineNr, Casing sType = UseCase, Comment cType = NoComment)\fP: .br same functionality as the previous constructor, but the line number of the first line read from \fIstream\fP is set to \fIlineNr\fP\&. .PP Copy\- and move\-constructors and \-assignment operators are available\&. .PP .SH "OVERLOADED OPERATORS" .IP o \fBCF_Line const &operator[](size_t idx) const\fP: .br returns the (0\-based) \fIidx\fP\-th line of the configuration file\&. .PP .SH "MEMBER FUNCTIONS" .IP o \fBconst_iterator begin() const\fP: .br returns a \fIconst_iterator\fP referring to the first line of the configuration file; .IP .IP o \fBstd::pair beginEndID(std::string const &rid) const\fP: .br returns a pair of \fICIVect::const_iterators\fP\&. Its \fIfirst\fP field is an \fICIVect::const_iterator\fP referring to the first line containing ID \fIid\fP; its \fIsecond\fP field is a \fICIVect::const_iterator\fP marking the end of the series of lines containing ID \fIid\fP\&. .IP The difference between the two iterators equals the number of lines containing ID \fIid\fP; .IP .IP o \fBstd::pair beginEndRE(std::string const ®ex) const\fP: .br same functionality as the previous member, but returning a pair of iterators to lines matching \fIregex\fP; .IP .IP o \fBconst_iterator end() const\fP: .br returns a \fIconst_iterator\fP pointing beyond the last line of the configuration file; .IP .IP o \fBvoid clear()\fP: .br clears the current content of the \fIConfig\fP object\&. This member is automatically called by the \fIload\fP members; .IP .IP o \fBconst_iterator find(std::string const &target) const\fP: .br returns an iterator to the first line containing \fItarget\fP, starting the search at \fIbegin()\fP\&. Note that \fItarget\fP may appear anywhere within a line\&. It returns \fIend()\fP if no such line was found; .IP .IP o \fBconst_iterator find(std::string const &target, const_iterator from) const\fP: .br same functionality as the previous member, but searching starts at \fIfrom\fP; .IP .IP o \fBconst_iterator findID(std::string const &id) const\fP: .br returns an iterator of the the first line containing ID \fIid\fP\&. It returns \fIend()\fP if no such line was found; .IP .IP o \fBconst_iterator findID(std::string const &id, const_iterator from) const\fP: .br same functionality as the previous member, but searching starts at \fIfrom\fP; .IP .IP o \fBconst_iterator findKey(std::string const &key) const\fP: .br returns an iterator of the the first line containing key `\fIkey\fP\(cq\&\&. It returns \fIend()\fP if no such line was found; .IP .IP o \fBconst_iterator findKey(std::string const &key, const_iterator from) const\fP: .br same functionality as the previous member, but searching starts at \fIfrom\fP; .IP .IP o \fBconst_iterator findRE(std::string const ®ex) const\fP: .br returns an iterator is returned to the first line matching the regular expression \fIregex\fP\&. It returns \fIend()\fP if no such line was found; .IP .IP o \fBvoid load(std::string const &fname)\fP: .br the content of the file named \fIfname\fP is stored in the \fIConfig\fP object, replacing any previously stored content\&. The file is read according to the latest setting of the \fIComment\fP and \fICasing\fP flags\&. If the file cannot be opened an \fIFBB::Exception\fP exception is thrown; .IP .IP o \fBvoid load(std::istream &stream, uint16_t lineNr = 1)\fP: .br same functionality as the previous member, but reading the configuration information from the \fIstd::istream\fP reference \fIstream\fP\&. The \fIlineNr\fP value specifies the line number of the first read line; .IP .IP o \fBvoid load(std::istream &&tmp, uint16_t lineNr = 1)\fP: .br same functionality as the previous member, but reading the configuration information from the \fIstd::istream\fP rvalue reference \fItmp\fP; .IP .IP o \fBvoid setComment(Comment type)\fP: .br the object\(cq\&s comment\-handling type is set to \fI\(cq\&type\(cq\&\fP (ether \fIKeepComment\fP or \fINoComment\fP)\&. It doesn\(cq\&t affect the current content of the \fBConfig\fP object, but when calling \fIload\fP the configuration file is processed according to \fItype\(cq\&s\fP value; .IP .IP o \fBvoid setCasing(Casing type)\fP: .br the object\(cq\&s letter case handling type is set to \fI\(cq\&type\(cq\&\fP (either \fIUseCase\fP or \fINoCase\fP); .IP .IP o \fBsize_t size() const\fP: .br returns the number of lines stored in the \fIConfig\fP object; .PP .SH "EXAMPLE" Assume the configuration file is named \fIconfig\&.rc\fP, containing 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? it extends over multiple lines and there may, of course, be more lines in this file .fi .PP The next program may be compiled and run as \fIa\&.out config\&.rc\fP: .nf #include #include #include #include using namespace std; using namespace FBB; int main(int argc, char **argv) { Config cf(argv[1]); cout << *cf\&.find(\(dq\&this one\(dq\&) << \(cq\&\en\(cq\&; // find text within a line // find all lines specifying ID \(cq\&line\(cq\& auto [begin, end] = cv\&.beginEndID(\(dq\&line\(dq\&); copy(begin, end, ostream_iterator(cout, \(dq\&\en\(dq\&)); } .fi .PP Producing the output: .nf line: this is found line: this one is line: what about this one? it extends over multiple lines .fi .PP .SH "FILES" \fIbobcat/config\fP \- defines the class interface .PP .SH "SEE ALSO" \fBargconfig\fP(3bobcat), \fBbobcat\fP(7), \fBexception\fP(3bobcat), \fBpattern\fP(3bobcat) .PP .SH "BUGS" .PP None reported .PP .SH "BOBCAT PROJECT FILES" .PP .IP o \fIhttps://fbb\-git\&.gitlab\&.io/bobcat/\fP: gitlab project page; .IP o \fIbobcat_6\&.04\&.00\-x\&.dsc\fP: detached signature; .IP o \fIbobcat_6\&.04\&.00\-x\&.tar\&.gz\fP: source archive; .IP o \fIbobcat_6\&.04\&.00\-x_i386\&.changes\fP: change log; .IP o \fIlibbobcat1_6\&.04\&.00\-x_*\&.deb\fP: debian package containing the libraries; .IP o \fIlibbobcat1\-dev_6\&.04\&.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