libbobcat1-dev_2.02.03-x.tar.gz Command Line Arguments
2005-2009
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
FBB::Arg &initialize(char const *optstring, int argc, char **argv):
Initializes the FBB::Arg singleton. Must be called only once.
Throws an FBB::Errno exception if called repeatedly or if called with
argv not containing a defined option (which is shown by the
FBB::Errno's what() member). Returns a reference to the singleton
object, allowing code initializing Arg to use the initialized object
immediately.
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::Errno exception if called repeatedly or if
called with argv not containing a defined option (which is shown by the
FBB::Errno'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:
a colon (:), indicating that the option has a required
argument;
a double colon (::), indicating that the option itself
has an optional argument (in that case, the option's value
will be empty, unless specified).
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::Errno exception is thrown.
OVERLOADED OPERATOR
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
std::string const &basename() const:
Returns the program's basename.
size_t nArgs() const:
Returns the number of arguments left after option-removal. The
program name argv[0] is NOT counted here.
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.
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.
size_t option(int option) const:
The number of times `option' (or its long option synonym, if defined)
was specified is returned.
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.
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.
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.
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.
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.
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.
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.
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 minArgsusage() is called with argument
basename(). If either version- or help information is shown, the int
value 1 is thrown as an exception.
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.
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.
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:
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).
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:
Where c1, c2, ..., cn are n constructor invocations of
FBB::Arg::LongOption() constructors
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-fletched 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'),
};
Arg::LongOption const *const longEnd =
longOptions +
sizeof(longOptions) / sizeof(Arg::LongOption);
}
int main(int argc, char **argv)
try
{
Arg &arg = Arg::initialize("df:hv",
longOptions, longEnd, argc, argv);
// code using arg, etc.
}
catch(Errno 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
bobcat_2.02.03-x.dsc: detached signature;
bobcat_2.02.03-x.tar.gz: source archive;
bobcat_2.02.03-x_i386.changes: change log;
libbobcat1_2.02.03-x_*.deb: debian package holding the
libraries;
libbobcat1-dev_2.02.03-x_*.deb: debian package holding the
libraries, headers and manual pages;
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).