FBB::ArgConfig - A singleton class processing program
arguments
#include <bobcat/argconfig>
Linking option: -lbobcat
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:
FBB
All constructors, members, operators and manipulators, mentioned in this
man-page, are defined in the namespace FBB.
FBB::Arg,
FBB::ConfigFile
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.
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).
Since the class is a Singleton, no public constructors are
available. Instead, static members are offered to initialize and access the
single ArgConfig object.
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. )
All public members of the Arg and ConfigFile classes
are also offered 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 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
- https://fbb-git.gitlab.io/bobcat/: gitlab project page;
- o
- bobcat_6.02.02-x.dsc: detached signature;
- o
- bobcat_6.02.02-x.tar.gz: source archive;
- o
- bobcat_6.02.02-x_i386.changes: change log;
- o
- libbobcat1_6.02.02-x_*.deb: debian package containing the
libraries;
- o
- libbobcat1-dev_6.02.02-x_*.deb: debian package containing the
libraries, headers and manual pages;
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).