Provided by: libbobcat-dev_6.04.00-1ubuntu3_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_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 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 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 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 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 <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;
}
FILES
bobcat/argconfig - defines the class interface
SEE ALSO
arg(3bobcat), configfile(3obcat), bobcat(7)
BUGS
None Reported.
BOBCAT PROJECT FILES
o https://fbb-git.gitlab.io/bobcat/: gitlab project page;
o bobcat_6.04.00-x.dsc: detached signature;
o bobcat_6.04.00-x.tar.gz: source archive;
o bobcat_6.04.00-x_i386.changes: change log;
o libbobcat1_6.04.00-x_*.deb: debian package containing the libraries;
o libbobcat1-dev_6.04.00-x_*.deb: debian package containing the libraries, headers
and manual pages;
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).