.TH "FBB::ArgConfig" "3bobcat" "2005\-2020" "libbobcat\-dev_5\&.07\&.00" "Program Arguments" .PP .SH "NAME" FBB::ArgConfig \- A singleton class processing program arguments .PP .SH "SYNOPSIS" \fB#include \fP .br Linking option: \fI\-lbobcat\fP .PP .SH "DESCRIPTION" Singleton class (see Gamma \fIet al\&.\fP, 1995) built around \fBgetopt\fP(3) and \fBgetopt_long\fP(3)\&. The class handles short\- and long command\-line options as well as configuration files\&. .PP In addition to the standard command\-line options, configuration files containing long options as their keys, optionally followed by a colon are also recognized by the various \fIoption\fP members\&. E\&.g\&., an option \fI\-\-input filename\fP can be specified in the configuration file like .nf input: filename .fi or .nf input filename .fi Options without arguments should probably not use the colon, although it is accepted by \fIConfigArg\fP\&. E\&.g\&., for the option \fI\-\-verbose\fP both forms are OK: .nf verbose verbose: .fi .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" \fBFBB::Arg\fP, .br \fBFBB::ConfigFile\fP .PP .SH "CONSTRUCTORS" Since the class is a \fISingleton\fP, no public constructors are available\&. Instead, static members are offered to initialize and access the single \fBArgConfig\fP object\&. See below\&. .PP .SH "STATIC MEMBERS" .IP o \fBFBB::ArgConfig &initialize(char const *optstring, int argc, char **argv, [std::string const &fname,] Comment cType = KeepComment, SearchCasing sType = SearchCaseSensitive, Indices iType = IgnoreIndices)\fP: .br Initializes the \fBFBB::ArgConfig\fP singleton\&. Must be called only once\&. Throws an \fBFBB::Exception\fP exception if called repeatedly or if called with \fIargv\fP not containing a defined option (which is shown by the \fBFBB::Exception\fP\(cq\&s \fIwhat\fP member)\&. The \fIfname\fP argument is optional\&. If provided, a configuration file by the specified name is opened (and must exist); if omitted the \fIArgConfig\fP is created without using a configuration file\&. In the latter case a configuration file may be specified later using the \fIopen\fP member inherited from \fIConfigFile\fP\&. The final three parameters are \fIConfigFile\fP parameters, receiving the shown default values\&. This constructor returns a reference to the singleton object, allowing code initializing \fBArgConfig\fP to use the initialized object immediately\&. .IP .IP o \fBFBB::ArgConfig &initialize(char const *optstring, LongOption const * const begin, LongOption const * const end, int argc, char **argv, [std::string const &fname,] Comment cType = KeepComment, SearchCasing sType = SearchCaseSensitive, Indices iType = IgnoreIndices)\fP: .br Initializes the \fBFBB::ArgConfig\fP singleton\&. Accepts two iterators of an array of \fBArg::LongOption\fP objects, holding long\-options\&. Must be called only once\&. Throws an \fBFBB::Exception\fP exception if called repeatedly or if called with \fIargv\fP not containing a defined option (which is shown by the \fBFBB::Exception\fP\(cq\&s \fIwhat\fP member)\&. Refer to \fBarg\fP(3bobcat) for the description of \fBArg::LongOption\fP\&. The constructor\(cq\&s final six parameters are identical to the previous constructor\(cq\&s final six arguments\&. This constructor returns a reference to the singleton object, allowing code initializing \fBArgConfig\fP to use the initialized object immediately\&. .IP The argument \fIoptstring\fP should consist of letters, possibly postfixed by: .IP o a colon (\fI:\fP), indicating that the option has a required argument; .IP o a double colon (\fI::\fP), indicating that the option itself has an optional argument (in that case, the option\(cq\&s value will be empty, unless specified)\&. .IP o \fBFBB::ArgConfig &instance()\fP: .br Returns the instance of the \fBArgConfig\fP object, available after calling one of the \fBArgConfig::initialize\fP members\&. If called before initialization, an \fIFBB::Exception\fP exception is thrown\&. .PP .SH "NON\-STATIC MEMBER FUNCTIONS" All public members of the \fIArg\fP and \fIConfigFile\fP classes are also offered by the \fIArgConfig\fP class\&. As several \fIoption\fP members were reimplemented by this class all \fIoption\fP members are discussed below\&. All other members inherit straight from the classes \fIArg\fP and \fIConfigFile\fP\&. Consult their man pages for details\&. .IP o \fBsize_t option(int option) const\fP: .br Returns the number of times `option\(cq\& (or its long option synonym, if defined) was specified as command line option or as as a configuration file option\&. .IP o \fBsize_t option(std::string const &options) const\fP: .br Returns the total number of times any of the characters specified in the `options\(cq\& string (or their long option synonyms) was specified as command line option or as as a configuration file option\&. .IP o \fBsize_t option(string *value, int option) const\fP: .br Returns the number of times the provided option (or its long option synonym) was present as either a command line option or as a configuration file option\&. If the return value is non\-zero then the value of the first occurrence of this option (first checking the command line options; then checking the configuration file) is stored in \fI*value\fP, which is left untouched if `option\(cq\& was not present\&. 0 may be specified for \fBvalue\fP if the option does not have a value or if the value should not be stored\&. .IP o \fBsize_t option(size_t idx, string *value, int option) const\fP: .br This member acts identically to the \fIArg::option\fP member having the identical prototype\&. It does not consider the configuration file but merely returns the number of times the provided option (or its long option synonym) was present\&. If the return value is non\-zero then the value of the \fIidx\fPth occurrence (0\-based offset) of this option is stored in \fI*value\fP, which is left untouched if `option\(cq\& was not present or if \fIidx\fP is or exceeds the number of specifications of the provided option\&. 0 may be specified for \fBvalue\fP if the option does not have a value or if the value should not be stored\&. .IP o \fBsize_t option(size_t *idx, string *value, int option) const\fP: .br This member acts identically to the \fIArg::option\fP member having the identical prototype\&. It does not consider the configuration file but merely returns the number of times the provided option (or its long option synonym) was present\&. If the return value is non\-zero then the offset (within the series of \fIoption\fP specifications) of the first option having a non\-empty option value is returned in \fI*idx\fP, while its option value is stored in \fI*value\fP\&. Both \fI*value\fP and \fI*idx\fP are left untouched if `option\(cq\& was not present\&. 0 may be specified for \fBvalue\fP if the option does not have a value or if the value should not be stored\&. .IP o \fBsize_t option(string *value, char const *longOption) const\fP: .br Returns the number of times the specified long option (not having a single\-character synonym) was present as either a command line option or in the configuration file\&. If found, then the value found at the first occurrence of the option (first considering the command line options, then the configuration file) is stored in \fI*value\fP\&. The string pointed to by \fIvalue\fP is left untouched if the long option was not present\&. 0 may be specified for \fBvalue\fP if the option does not have a value or if the value should not be stored\&. .IP o \fBsize_t option(size_t idx, string *value, char const * longOption) const\fP: .br This member acts identically to the \fIArg::option\fP member having the identical prototype\&. It does not consider the configuration file but merely returns the number of times the provided long option (not having a single\-character synonym) was present\&. If the return value is non\-zero then the value of the \fIidx\fPth occurrence (0\-based offset) of this long option is stored in \fI*value\fP, which is left untouched if the long option was not present or if \fIidx\fP is or exceeds the number of specifications of the provided long option\&. 0 may be specified for \fBvalue\fP if the long option does not have a value or if the value should not be stored\&. .IP o \fBsize_t option(size_t *idx, string *value, int longOption) const\fP: .br This member acts identically to the \fIArg::option\fP member having the identical prototype\&. It does not consider the configuration file but merely returns the number of times the provided long option (not having a single\-character synonym) was present\&. If the return value is non\-zero then the offset (within the series of this long option specifications) of the first long option having a non\-empty option value is returned in \fI*idx\fP, while its option value is stored in \fI*value\fP\&. Both \fI*value\fP and \fI*idx\fP are left untouched if long option was not present\&. 0 may be specified for \fBvalue\fP if the long option does not have a value or if the value should not be stored\&. .PP .SH "EXAMPLE" .PP .nf #include #include #include #include using namespace std; using namespace FBB; ArgConfig::LongOption lo[] = { ArgConfig::LongOption{\(dq\&option\(dq\&, \(cq\&o\(cq\&}, ArgConfig::LongOption{\(dq\&value\-option\(dq\&, \(cq\&v\(cq\&} }; class X { ArgConfig &d_arg; public: X(); void function(); }; X::X() : d_arg(ArgConfig::instance()) {} void X::function() { if (d_arg\&.nArgs() == 0) throw Exception() << \(dq\&Provide the name of a config file as 1st arg\(dq\&; cout << \(dq\&Counting \(dq\& << d_arg\&.option(\(cq\&o\(cq\&) << \(dq\& instances of \-o or \(dq\& \(dq\&\-\-option\en\(dq\&; d_arg\&.open(d_arg[0]); // Now open the config file explicitly // (alternatively: use a constructor expecting // a file name) cout << \(dq\&Counting \(dq\& << d_arg\&.option(\(cq\&o\(cq\&) << \(dq\& instances of \-o or \(dq\& \(dq\&\-\-option\en\(dq\&; string optval; size_t count = d_arg\&.option(&optval, \(cq\&v\(cq\&); cout << \(dq\&Counting \(dq\& << count << \(dq\& instances of \-v or \-\-value\-option\en\(dq\&; if (count) cout << \(dq\&Option value = \(dq\& << optval << endl; } int main(int argc, char **argv) try { ArgConfig::initialize(\(dq\&ov:\(dq\&, lo, lo + 2, argc, argv); X x; x\&.function(); } catch (Exception const &err) { cout << \(dq\&Terminating \(dq\& << err\&.what() << endl; return 1; } .fi .PP .SH "FILES" \fIbobcat/argconfig\fP \- defines the class interface .PP .SH "SEE ALSO" \fBarg\fP(3bobcat), \fBconfigfile\fP(3obcat), \fBbobcat\fP(7) .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