--- name: "argconfig" section: "3bobcat" platform: "linux" package: "libbobcat-dev" version: "6.07.01-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/argconfig" --- # argconfig(3bobcat) A singleton class processing program arguments ## NAME FBB::ArgConfig - A singleton class processing program arguments ## SYNOPSIS **#include \**\ Linking option: *-lbobcat* ## DESCRIPTION Singleton class (see Gamma *et al.*, 1995) built around **getopt\_long()**(3). The class handles short- and long command-line options, as well as configuration files. In addition to the standard command-line options the various *option* members also recognize long options as keys, optionally followed by a colon and an option value are also recognized. E.g., an option *--input filename* can be specified in the configuration file like ``` input: filename ``` or ``` input filename ``` Options without arguments should probably not use the colon, although it is accepted by *ConfigArg*. E.g., for the option *--verbose* both forms are accepted: ``` verbose verbose: ``` ## NAMESPACE **FBB**\ All constructors, members, operators and manipulators, mentioned in this man-page, are defined in the namespace **FBB**. ## INHERITS FROM **FBB::Arg**,\ **FBB::ConfigFile** ## ENUMERATION The **FBB::ArgConfig::Type** enumeration is inherited from the **FBB::Arg** class. It is used to specify whether or not long options require arguments. It defines the following values: **None, Required, Optional**. - o **None**: the long option does not use an argument; - o **Required**: the long option requires an argument value; - o **Optional**: the long option may optionally be provided with an argument value; These values are used when defining long options (like *--version*), which are defined as objects of the (nested inherited) class **FBB::Arg::LongOption** (in the context of *ArgConfig* this is identical to **FBB::ArgConfig::LongOption**. ## THE NESTED INHERITED CLASS FBB::Arg::LongOption Long options are defined using objects of the nested class **FBB::Arg::LongOption**. This class provides the following constructors: - o **FBB::Arg::LongOption(char const \*name, FBB::Arg::Type type =** **FBB::Arg::None)**:\ This constructor is used to define a long option for which no corresponding short option is defined. The parameter *name* is the name of the long option (without specifying the -- characters which are only required when specifying a long option when calling a program). - - o **FBB::Arg::LongOption(char const \*name, int optionChar)**:\ This constructor is used to define a long option for which a corresponding short option is defined. The parameter *name* is the name of the long option (without specifying the -- characters which are only required when specifying a long option when calling a program). To define long options use the following procedure: - o First, construct an array ``` FBB::Arg::LongOption longOptions[] = { c1, c2, ..., cn }; ``` Where *c1, c2, ..., cn* are *n* constructor invocations of **FBB::Arg::LongOption()** constructors - - o Next, pass *longOptions, LongOptions + n* as arguments to an *Arg::initialize* member that supports long options. Objects of the class *LongOptions* are normally used internally by the *ArgConfig* object, but they can also be used outside of the *ArgConfig* object. For that situation the following members are available: - o **std::string const &longName() const**:\ returns the *LongOption’s* long option name; - o **int optionChar() const**:\ returns the *LongOption’s* option character (or one of the *Arg::Type* enumeration values if there is no option character associated with the *LongOption*). ## CONSTRUCTORS Since the class is a *Singleton*, no public constructors are available. Instead, static members are offered to initialize and access the single **ArgConfig** object. ## STATIC MEMBERS All *initialize* members initialize the **FBB::ArgConfig** singleton, and can only be called once. An exception is thrown when called multiple times. All *initialize* members return a reference to the initialized *ArgConfig* singleton object. All *initialize* members define the parameters *argc* and *argv* which are interpreted as *main’s* *argc* and *argv* parameters. When an *argv* element points to two consecutive dashes (*--*) then that element is ignored, and all of *argv’s* subsequent elements are considered arguments instead of options. - o **FBB::ArgConfig &ArgConfig::initialize(char const \*optstring, int argc,** **char \*\*argv, \[std::string const &fname,\] Comment cType = KeepComment,** **SearchCasing sType = SearchCaseSensitive, Indices iType =** **IgnoreIndices)**:\ The parameter *optstring* 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: - o a single colon (:) indicates that the option requires an option value. - 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., *-tvalue*). Long options optionally accepting arguments should always immediately be followed by an assignment character (=), immediately followed by the option’s value (which must start with a non-blank character). E.g., *--value=* indicates an absent option value, *--value=text* indicates the option’s value equals *text*. If an option value itself contains blanks, it must be surrounded by single or double quotes (e.g., *-t’this value’*, or *--text=’this value’*). The surrounding quotes are not part of the option’s value. - When *optstring’s* 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 *optstring* is *+ab* and no long options are defined, then calling ``` prog -a -z -b -yvalue --long arg1 arg2 ``` results in the member *argv* returning a vector containing the elements *-z, -yvalue, --long, arg1,* and *arg2*. If *optstring’s* first character isn’t + and an undefined option is encountered then an exception is thrown. - The *fname* argument is optional. If provided, a configuration file by the specified name is opened (and must exist); if omitted the *ArgConfig* is created without using a configuration file. In the latter case a configuration file may be specified later using the *open* member inherited from *ConfigFile*. - The final three parameters are *ConfigFile* parameters, receiving the shown default values. This constructor returns a reference to the singleton object, allowing code initializing **ArgConfig** to use the initialized object immediately. - - o **FBB::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)**:\ Acts like the previous member, but in addition defines the parameter *accept* specifying an option character from where all subsequent arguments and options are considered arguments. To ignore *accept* the value 0 (not the character ’0’) can be specified or an *initialize* members can be used that does not define an *accept* parameter. - When arguments contain both an *accept* option and two consecutive dashes then the first one is interpreted, resulting in all remaining *argv* elements being interpreted as mere arguments. For example, when specifying *initialize(’t’, ...)* and calling ``` prog one -ttwo -c -- three ``` then the member *argv* returns a vector containing the elements *one, -tttwo, -c, --*, and *three* (see also the member *beyondDashes* below). - - o **FBB::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)**:\ Acts like the first *ArgConfig::initialize* member, but in addition defines two parameters specifying the range of elements of an array of *ArgConfig::LongOption* objects specifying long options. The parameter *begin* points to the first element of the range, the parameter *end* points just beyond the last element of the range. E.g., after defining ``` FBB::ArgConfig::LongOption longOptions[] = { c1, c2, ..., cn }; ``` the arguments passed to *begin* and *end* could be specified as ``` initialize(..., longOptions, longOptions + size(longOptions), ...); ``` - - o **FBB::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)**:\ - Acts like the previous *ArgConfig::initialize* member, but in addition defines an *accept* parameter as defined by the second *ArgConfig::initialize* member. - - o **FBB::ArgConfig &ArgConfig::instance()**:\ Once an *ArgConfig::initialize* 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 **ArgConfig** object. - If it is called before an *ArgConfig::initialize* member has been called an exception is thrown. - o **FBB::ArgConfig &instance()**:\ Returns the instance of the **ArgConfig** object, available after calling one of the **ArgConfig::initialize** members. If called before initialization, an *FBB::Exception* exception is thrown. ) ## NON-STATIC MEMBER FUNCTIONS All public members of the **Arg** and **ConfigFile** classes are also supported by the *ArgConfig* class. As several *Arg::option* members were reimplemented by *ArgConfig* all *option* members are discussed below. All other members inherit straight from the classes **Arg** and **ConfigFile**. Consult their man pages for details. - o **size\_t option(int option) const**:\ Returns the number of times \`option’ (or its long option synonym, if defined) was specified as command line option or as as a configuration file option. - o **size\_t option(std::string const &options) const**:\ Returns the total number of times any of the characters specified in the \`options’ string (or their long option synonyms) was specified as command line option or as as a configuration file option. - o **size\_t option(string \*value, int option) const**:\ 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 *\*value*, which is left untouched if \`option’ was not present. 0 may be specified for **value** if the option does not have a value or if the value should not be stored. - o **size\_t option(size\_t idx, string \*value, int option) const**:\ This member acts identically to the **Arg***::option* 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 *idx*th occurrence (0-based offset) of this option is stored in *\*value*, which is left untouched if \`option’ was not present or if *idx* is or exceeds the number of specifications of the provided option. 0 may be specified for **value** if the option does not have a value or if the value should not be stored. - o **size\_t option(size\_t \*idx, string \*value, int option) const**:\ This member acts identically to the **Arg***::option* 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 *option* specifications) of the first option having a non-empty option value is returned in *\*idx*, while its option value is stored in *\*value*. Both *\*value* and *\*idx* are left untouched if \`option’ was not present. 0 may be specified for **value** if the option does not have a value or if the value should not be stored. - o **size\_t option(string \*value, char const \*longOption) const**:\ 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 *\*value*. The string pointed to by *value* is left untouched if the long option was not present. 0 may be specified for **value** if the option does not have a value or if the value should not be stored. - o **size\_t option(size\_t idx, string \*value,** **char const \* longOption) const**:\ This member acts identically to the **Arg***::option* 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 *idx*th occurrence (0-based offset) of this long option is stored in *\*value*, which is left untouched if the long option was not present or if *idx* is or exceeds the number of specifications of the provided long option. 0 may be specified for **value** if the long option does not have a value or if the value should not be stored. - o **size\_t option(size\_t \*idx, string \*value, int longOption) const**:\ This member acts identically to the **Arg***::option* 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 *\*idx*, while its option value is stored in *\*value*. Both *\*value* and *\*idx* are left untouched if long option was not present. 0 may be specified for **value** if the long option does not have a value or if the value should not be stored. When using the *option* members that don’t consider configuration files use the *beginEndRE* member (cf. **configfile**(3obcat)) to retrieve long options that are specified in configuration files. ## EXAMPLE ``` #include #include #include #include using namespace std; using namespace FBB; ArgConfig::LongOption lo[] = { ArgConfig::LongOption{"option", ’o’}, ArgConfig::LongOption{"value-option", ’v’} }; 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() << "Provide the name of a config file as 1st arg"; cout << "Counting " << d_arg.option(’o’) << " instances of -o or " "--option\n"; d_arg.open(d_arg[0]); // Now open the config file explicitly // (alternatively: use a constructor expecting // a file name) cout << "Counting " << d_arg.option(’o’) << " instances of -o or " "--option\n"; string optval; size_t count = d_arg.option(&optval, ’v’); cout << "Counting " << count << " instances of -v or --value-option\n"; if (count) cout << "Option value = " << optval << endl; } int main(int argc, char **argv) try { ArgConfig::initialize("ov:", lo, lo + 2, argc, argv); X x; x.function(); } catch (Exception const &err) { cout << "Terminating " << err.what() << endl; return 1; } ``` ## FILES *bobcat/argconfig* - defines the class interface ## SEE ALSO [**arg**(3bobcat)](/arg/3bobcat.md), **configfile**(3obcat), [**bobcat**(7)](/bobcat/7.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**).