Provided by: libbobcat-dev_4.08.02-2build1_amd64 
NAME
FBB::Arg - A singleton class interfacing command line arguments
SYNOPSIS
#include <bobcat/arg>
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,
NAMESPACE
FBB
All constructors, members, operators and manipulators, mentioned in this man-page, are
defined in the namespace FBB.
INHERITS FROM
-
ENUMERATION
The FBB::Arg::Type enumeration is defined by the FBB::Arg class. It has the following
values intended for public use: None, Required, Optional. These values are used when
constructing objects of the nested class FBB::Arg::LongOption, see below.
CONSTRUCTORS
Since the class is a Singleton, no public constructors are available. Instead, static
members are offered to initialize and access the single FBB::Arg object. See below.
STATIC MEMBERS
o FBB::Arg &initialize(char const *optstring, int argc, char **argv):
Initializes the FBB::Arg 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). Returns a
reference to the singleton object, allowing code initializing Arg to use the
initialized object immediately.
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, 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). See the
description of Arg::LongOption below. Returns a reference to the singleton object,
allowing code initializing Arg to use the initialized object immediately.
optstring should consist of letters, possibly postfixed by:
o a colon (:), indicating that the option requires an option value.
o a double colon (::), indicating that the option itself has an optional argument.
With short options the option value is considered absent unless it immediately
follows the short option (e.g., -tvalue for a short option -t). Long options
optionally accepting arguments should always immediately be followed by a =
character. Here the option’s value must immediately follow the = character, and
must start with a non-blank character, or the option’s value is considered absent.
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 should
be surrounded by single or double quotes (e.g., -t’this value’, or --text=’this
value’). The surrounding quotes themselves are not part of the option’s value.
o FBB::Arg &instance():
Returns the instance of the Arg object, available after calling one of the
Arg::initialize() members. If called before initialization, an FBB::Exception
exception is thrown.
OVERLOADED OPERATOR
o char const *operator[](size_t idx) const:
Returns argument[idx], after having removed all specified options. 0 is returned
if no arg[x] is available. The program name (argv[0]) is NOT counted here: index 0
refers to the first ARGUMENT, e.g., the program’s argv[1].
NON-STATIC MEMBER FUNCTIONS
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
C-string values of the arguments.
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 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) then an 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 for which no short option synonym exist. 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 counted.
o size_t option(int option) const:
The number of times `option’ (or its long option synonym, if defined) was specified
is returned.
o size_t option(std::string const &options) const:
The number of times one of the options specified in the `option’ argument (or their
long option synonyms) were present is returned.
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. 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 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 NESTED CLASS FBB::Arg::LongOption
Long options are defined using objects of the nested class FBB::Arg::LongOption. This
class offers the following constructors:
o FBB::Arg::LongOption(char const *name, FBB::Arg::Type type = 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 initialize()
EXAMPLE
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;
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 + sizeof(longOptions) / sizeof(longOptions[0]);
}
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() << endl;
return err.which();
}
catch(int x)
{
return x;
}
FILES
bobcat/arg - defines the class interface
SEE ALSO
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).