FBB::ArgConfig - A singleton class processing program
arguments
#include <bobcat/argconfig>
Linking option: -lbobcat
Singleton class (see Gamma et al., 1995) built around
getopt(3) and 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, configuration
files containing long options as their keys, optionally followed by a colon
are also recognized by the various option members. 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 OK:
verbose
verbose:
FBB
All constructors, members, operators and manipulators, mentioned in this
man-page, are defined in the namespace FBB.
FBB::Arg,
FBB::ConfigFile
Since the class is a Singleton, no public constructors are
available. Instead, static members are offered to initialize and access the
single ArgConfig object. See below.
- o
- FBB::ArgConfig &initialize(char const *optstring, int argc,
char **argv, [std::string const &fname,] Comment cType =
KeepComment, SearchCasing sType = SearchCaseSensitive,
Indices iType = IgnoreIndices):
Initializes the FBB::ArgConfig singleton. Must be called only once.
Throws an FBB::Exception exception if called repeatedly or if
called with argv not containing a defined option (which is shown by
the FBB::Exception’s what member). 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 &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):
Initializes the FBB::ArgConfig singleton. Accepts two iterators of an
array of Arg::LongOption objects, holding long-options. Must be
called only once. Throws an FBB::Exception exception if called
repeatedly or if called with argv not containing a defined option
(which is shown by the FBB::Exception’s what member).
Refer to arg(3bobcat) for the description of
Arg::LongOption. The constructor’s final six parameters are
identical to the previous constructor’s final six arguments. This
constructor returns a reference to the singleton object, allowing code
initializing ArgConfig to use the initialized object
immediately.
- The argument optstring should consist of letters, possibly
postfixed by:
- o
- a colon (:), indicating that the option has a required
argument;
- o
- a double colon (::), indicating that the option itself has an
optional argument (in that case, the option’s value will be empty,
unless specified).
- 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.
All public members of the Arg and ConfigFile classes
are also offered by the ArgConfig class. As several option
members were reimplemented by this class 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 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 idxth 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 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 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 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 idxth 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 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
*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.
#include <iostream>
#include <string>
#include <bobcat/argconfig>
#include <bobcat/exception>
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;
}
bobcat/argconfig - defines the class interface
- o
- bobcat_4.08.06-x.dsc: detached signature;
- o
- bobcat_4.08.06-x.tar.gz: source archive;
- o
- bobcat_4.08.06-x_i386.changes: change log;
- o
- libbobcat1_4.08.06-x_*.deb: debian package holding the
libraries;
- o
- libbobcat1-dev_4.08.06-x_*.deb: debian package holding the
libraries, headers and manual pages;
- o
- http://sourceforge.net/projects/bobcat: public archive location;
Bobcat is an acronym of `Brokken’s Own Base Classes And
Templates’.
This is free software, distributed under the terms of the GNU
General Public License (GPL).
Frank B. Brokken (f.b.brokken@rug.nl).