FBB::Arg - A singleton class interfacing command line
arguments
#include <bobcat/arg>
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,
FBB
All constructors, members, operators and manipulators, mentioned in this
man-page, are defined in the namespace FBB.
The FBB::Arg::Type enumeration is defined by 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 constructing objects of the following
(nested) 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 prefixing the -- characters, which are
required when specifying the long option).
- 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 prefixing the -- characters, which are
required when specifying the long option). In a program, long options may
be specified as follows:
- 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 2nd and 3rd arguments to
Arg’s member initialize()
Since the class is a Singleton there are no public
constructors. Instead, static members are offered for initializing and
accessing the single FBB::Arg object.
- o
- FBB::Arg &initialize(char const *optstring, int argc, char
**argv):
Initializes the FBB::Arg singleton. May be called only once. Throws
an FBB::Exception exception if called repeatedly or if called with
argv containing an undefined option. If so, the Exception
object’s what() member provides details. A reference to the
singleton object is returned.
- o
- FBB::Arg &initialize(char const *optstring, LongOption const
*const begin, LongOption const *const end, int argc, char
**argv):
Initializes the FBB::Arg singleton. Accepts two iterators of an array
of Arg::LongOption objects. May be called only once. Throws an
FBB::Exception exception if called repeatedly or if called with
argv containing a undefined option. If so, the Exception
object’s what() member provides details. See the description
of Arg::LongOption below. A reference to the singleton object is
returned.
- The parameter optstring must point to a null-terminated byte string
(NTBS) containing option characters, possibly postfixed by:
- o
- a colon (:), indicating that the option requires an option
value.
- o
- a double colon (::), indicating that the option has an optional
argument. With short options the option value is considered absent unless
it it directly attached to the short option (e.g., -tvalue). Long
options optionally accepting arguments should always immediately be
followed by an assignment character (=). Here the option’s
value must immediately follow the = character, and 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.
- o
- FBB::Arg &instance():
Returns a reference to the iitialized Arg object. If called before
initialization, an FBB::Exception exception is thrown.
- o
- char const *operator[](size_t idx) const:
Returns argument[idx], after having removed all specified options. It
returns 0 if no arg[x] is available. The program’s name
(argv[0]) is NOT counted here: index 0 refers to the first
ARGUMENT, e.g., the program’s argv[1].
- o
- char const **argPointers():
Returns argv-like set of pointers to all remaining arguments. The
last element is guaranteed to be a 0-pointer. The first nArg()
elements point to the respective values of the NTBS arguments that were
passed to the program.
- o
- std::string const &basename() const:
Returns the program’s basename.
- o
- size_t beyondDashes() const:
Returns the index of the first argument after a -- argument or
returns nArgs() if no -- argument was encountered.
A -- argument ends Arg’s argument processing, and all
arguments beyond the first -- argument are kept `as is’. The
beyondDashes member returns the index of the first argument beyond
the -- argument, which itself is removed from the remaining set of
arguments.
- o
- void help() const:
If the member versionHelp (see below) has been called then this
member calls the usage function that was passed to
versionHelp. If versionHelp has not been called (i.e., if no
usage function has been specified) an FBB::Exception is
thrown.
- o
- size_t nArgs() const:
Returns the number of arguments left after option-removal. The program name
argv[0] is NOT counted here.
- o
- size_t nLongOptions() const:
Returns the number of long options not having short option synonyms If long
options are multiply specified, then each specification is counted.
- o
- size_t nOptions() const:
Returns the number of specified single character options. If short options
have long option synonyms, then these long option synonyms are counted as
if they were specified as single character options. If single character
options (or their long option synonyms) are multiply specified, then each
specification is separately counted.
- o
- size_t option(int option) const:
Returns the number of times `option’ was specified (or its long
option synonym, if defined).
- o
- size_t option(std::string const &options) const:
Returns the number of times each of the options specified in the
`option’ argument were specified (or their long option synonyms).
Note that each character in options must specify a single-character
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. If the return value is non-zero then the value of the first
occurrence of this option is stored in *value, which is left
untouched if `option’ was not present. The parameter value
may be initialized to 0 if the option does not have a value or if the
option’s value should not be stored.
- o
- size_t option(size_t idx, string *value, int option) const:
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:
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. Its value is then stored in
*value, which 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:
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:
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.
- o
- void versionHelp(void (*usage)(std::string const &progname),
char const *version, size_t minArgs, int helpFlag =
’h’, int versionFlag = ’v’) const:
If versionFlag was specified, and the helpFlag was not
specified the program’s name (using basename()) and
version is displayed to std::cout. Otherwise, if the
helpFlag was provided or if there are fewer arguments than
minArgs usage() is called with argument basename().
If either version- or help information is shown, the int value 1 is
thrown as an exception.
Note that versionhelp compares minArgs against nArgs.
If minArgs should be compaired against the number of arguments up
to a possible `--’ argument (i.e., beyondDashes’
return value), then add nArgs() - beyondDashes() to the
minArg argument. E.g.,
arg.versionHelp(usage, version, 2 + arg.nArgs()
- arg.beyondDashes());
The address of the usage() function, the current version and the
minimum number of arguments must be specified. Default argument values are
provided for the option flags.
The following example illustrates defining long options and shows
an initialization. It is not a full-fledched example in the sense of a small
runnable program.
#include <bobcat/arg>
using namespace FBB;
using namespace std;
namespace // the anonymous namespace can be used here
{
Arg::LongOption longOptions[] =
{
Arg::LongOption{"debug"},
Arg::LongOption{"filenames", ’f’},
Arg::LongOption{"help", ’h’},
Arg::LongOption{"version", ’v’},
};
auto longEnd = longOptions + size(longOptions);
}
int main(int argc, char **argv)
try
{
Arg &arg = Arg::initialize("df:hv",
longOptions, longEnd,
argc, argv);
// code using arg, etc.
}
catch (exception const &err) // handle exceptions
{
cerr << err.what() << ’\n’;
return 1;
}
bobcat/arg - 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).