.TH "FBB::ArgConfig" "3bobcat" "2005\-2023" "libbobcat\-dev_6\&.04\&.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_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 the various \fIoption\fP members also recognize long options as keys, optionally followed by a colon and an option value are also recognized\&. 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 accepted: .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 "ENUMERATION" .PP The \fBFBB::ArgConfig::Type\fP enumeration is inherited from the \fBFBB::Arg\fP class\&. It is used to specify whether or not long options require arguments\&. It defines the following values: \fBNone, Required, Optional\fP\&. .IP o \fBNone\fP: the long option does not use an argument; .IP o \fBRequired\fP: the long option requires an argument value; .IP o \fBOptional\fP: the long option may optionally be provided with an argument value; .PP These values are used when defining long options (like \fI\-\-version\fP), which are defined as objects of the (nested inherited) class \fBFBB::Arg::LongOption\fP (in the context of \fIArgConfig\fP this is identical to \fBFBB::ArgConfig::LongOption\fP\&. .PP .SH "THE NESTED INHERITED CLASS FBB::Arg::LongOption" Long options are defined using objects of the nested class \fBFBB::Arg::LongOption\fP\&. This class provides the following constructors: .IP o \fBFBB::Arg::LongOption(char const *name, FBB::Arg::Type type = FBB::Arg::None)\fP: .br This constructor is used to define a long option for which no corresponding short option is defined\&. The parameter \fIname\fP is the name of the long option (without specifying the \-\- characters which are only required when specifying a long option when calling a program)\&. .IP .IP o \fBFBB::Arg::LongOption(char const *name, int optionChar)\fP: .br This constructor is used to define a long option for which a corresponding short option is defined\&. The parameter \fIname\fP is the name of the long option (without specifying the \-\- characters which are only required when specifying a long option when calling a program)\&. .PP To define long options use the following procedure: .IP o First, construct an array .nf FBB::Arg::LongOption longOptions[] = { c1, c2, \&.\&.\&., cn }; .fi Where \fIc1, c2, \&.\&.\&., cn\fP are \fIn\fP constructor invocations of \fBFBB::Arg::LongOption()\fP constructors .IP .IP o Next, pass \fIlongOptions, LongOptions + n\fP as arguments to an \fIArg::initialize\fP member that supports long options\&. .PP Objects of the class \fILongOptions\fP are normally used internally by the \fIArgConfig\fP object, but they can also be used outside of the \fIArgConfig\fP object\&. For that situation the following members are available: .IP o \fBstd::string const &longName() const\fP: .br returns the \fILongOption\(cq\&s\fP long option name; .IP o \fBint optionChar() const\fP: .br returns the \fILongOption\(cq\&s\fP option character (or one of the \fIArg::Type\fP enumeration values if there is no option character associated with the \fILongOption\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\&. .PP .SH "STATIC MEMBERS" .PP All \fIinitialize\fP members initialize the \fBFBB::ArgConfig\fP singleton, and can only be called once\&. An exception is thrown when called multiple times\&. All \fIinitialize\fP members return a reference to the initialized \fIArgConfig\fP singleton object\&. .PP All \fIinitialize\fP members define the parameters \fIargc\fP and \fIargv\fP which are interpreted as \fImain\(cq\&s\fP \fIargc\fP and \fIargv\fP parameters\&. When an \fIargv\fP element points to two consecutive dashes (\fI\-\-\fP) then that element is ignored, and all of \fIargv\(cq\&s\fP subsequent elements are considered arguments instead of options\&. .PP .IP o \fBFBB::ArgConfig &ArgConfig::initialize(char const *optstring, int argc, char **argv, [std::string const &fname,] Comment cType = KeepComment, SearchCasing sType = SearchCaseSensitive, Indices iType = IgnoreIndices)\fP: .br The parameter \fIoptstring\fP is a null\-terminated byte string (NTBS) optionally starting with a + character, but otherwise containing option characters\&. One or two colons may be postfixed to option characters: .RS .IP o a single colon (:) indicates that the option requires an option value\&. .IP o a double colon (::) indicates that the option has an optional argument\&. With short options the option value is considered absent unless it is attached to the short option (e\&.g\&., \fI\-tvalue\fP)\&. Long options optionally accepting arguments should always immediately be followed by an assignment character (=), immediately followed by the option\(cq\&s value (which must start with a non\-blank character)\&. E\&.g\&., \fI\-\-value=\fP indicates an absent option value, \fI\-\-value=text\fP indicates the option\(cq\&s value equals \fItext\fP\&. If an option value itself contains blanks, it must be surrounded by single or double quotes (e\&.g\&., \fI\-t\(cq\&this value\(cq\&\fP, or \fI\-\-text=\(cq\&this value\(cq\&\fP)\&. The surrounding quotes are not part of the option\(cq\&s value\&. .RE .IP When \fIoptstring\(cq\&s\fP first character is + then all non\-specified options are considered arguments, appearing in the final arguments list at their current argument positions\&. E\&.g\&., when \fIoptstring\fP is \fI+ab\fP and no long options are defined, then calling .nf prog \-a \-z \-b \-yvalue \-\-long arg1 arg2 .fi results in the member \fIargv\fP returning a vector containing the elements \fI\-z, \-yvalue, \-\-long, arg1,\fP and \fIarg2\fP\&. If \fIoptstring\(cq\&s\fP first character isn\(cq\&t + and an undefined option is encountered then an exception is thrown\&. .IP 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\&. .IP 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 &ArgConfig::initialize(int accept\&. char const *optstring, int argc, char **argv, [std::string const &fname,] Comment cType = KeepComment, SearchCasing sType = SearchCaseSensitive, Indices iType = IgnoreIndices)\fP: .br Acts like the previous member, but in addition defines the parameter \fIaccept\fP specifying an option character from where all subsequent arguments and options are considered arguments\&. To ignore \fIaccept\fP the value 0 (not the character \(cq\&0\(cq\&) can be specified or an \fIinitialize\fP members can be used that does not define an \fIaccept\fP parameter\&. .IP When arguments contain both an \fIaccept\fP option and two consecutive dashes then the first one is interpreted, resulting in all remaining \fIargv\fP elements being interpreted as mere arguments\&. For example, when specifying \fIinitialize(\(cq\&t\(cq\&, \&.\&.\&.)\fP and calling .nf prog one \-ttwo \-c \-\- three .fi then the member \fIargv\fP returns a vector containing the elements \fIone, \-tttwo, \-c, \-\-\fP, and \fIthree\fP (see also the member \fIbeyondDashes\fP below)\&. .IP .IP o \fBFBB::ArgConfig &ArgConfig::initialize(char const *optstring, ArgConfig::LongOption const *const begin, ArgConfig::LongOption const *const end, int argc, char **argv, [std::string const &fname,] Comment cType = KeepComment, SearchCasing sType = SearchCaseSensitive, Indices iType = IgnoreIndices)\fP: .br Acts like the first \fIArgConfig::initialize\fP member, but in addition defines two parameters specifying the range of elements of an array of \fIArgConfig::LongOption\fP objects specifying long options\&. The parameter \fIbegin\fP points to the first element of the range, the parameter \fIend\fP points just beyond the last element of the range\&. E\&.g\&., after defining .nf FBB::ArgConfig::LongOption longOptions[] = { c1, c2, \&.\&.\&., cn }; .fi the arguments passed to \fIbegin\fP and \fIend\fP could be specified as .nf initialize(\&.\&.\&., longOptions, longOptions + size(longOptions), \&.\&.\&.); .fi .IP .IP o \fBFBB::ArgConfig &ArgConfig::initialize(char accept, 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 .IP Acts like the previous \fIArgConfig::initialize\fP member, but in addition defines an \fIaccept\fP parameter as defined by the second \fIArgConfig::initialize\fP member\&. .IP .IP o \fBFBB::ArgConfig &ArgConfig::instance()\fP: .br Once an \fIArgConfig::initialize\fP member has been called this member can be called from anywhere in the program (and it can be called multiple times), returning a reference to the initialized \fBArgConfig\fP object\&. .IP If it is called before an \fIArgConfig::initialize\fP member has been called an exception is thrown\&. .PP .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 \fBArg\fP and \fBConfigFile\fP classes are also supported by the \fIArgConfig\fP class\&. As several \fIArg::option\fP members were reimplemented by \fIArgConfig\fP all \fIoption\fP members are discussed below\&. All other members inherit straight from the classes \fBArg\fP and \fBConfigFile\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 \fBArg\fP\fI::option\fP member having the identical prototype\&. It does not consider the configuration file but merely considers the command line arguments, returning 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 \fBArg\fP\fI::option\fP member having the identical prototype\&. It does not consider the configuration file, but merely considers the command line arguments, returning 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 \fBArg\fP\fI::option\fP member having the identical prototype\&. It does not consider the configuration file, but merely considers the command line arguments, returning 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 \fBArg\fP\fI::option\fP member having the identical prototype\&. It does not consider the configuration file, but merely considers the command line arguments, returning 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 When using the \fIoption\fP members that don\(cq\&t consider configuration files use the \fIbeginEndRE\fP member (cf\&. \fBconfigfile\fP(3obcat)) to retrieve long options that are specified in configuration files\&. .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_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