Provided by: libbobcat-dev_4.08.02-2build1_amd64 
NAME
FBB::ArgConfig - A singleton class processing program arguments
SYNOPSIS
#include <bobcat/argconfig>
Linking option: -lbobcat
DESCRIPTION
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:
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
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. See below.
STATIC MEMBERS
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.
NON-STATIC MEMBER FUNCTIONS
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.
EXAMPLE
#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();
return 0;
}
catch (Exception const &err)
{
cout << "Terminating " << err.what() << endl;
return 1;
}
FILES
bobcat/argconfig - defines the class interface
SEE ALSO
arg(3bobcat), configfile(3obcat), bobcat(7)
BUGS
None Reported.
DISTRIBUTION FILES
o bobcat_4.08.02-x.dsc: detached signature;
o bobcat_4.08.02-x.tar.gz: source archive;
o bobcat_4.08.02-x_i386.changes: change log;
o libbobcat1_4.08.02-x_*.deb: debian package holding the libraries;
o libbobcat1-dev_4.08.02-x_*.deb: debian package holding the libraries, headers and
manual pages;
o http://sourceforge.net/projects/bobcat: public archive location;
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).