.TH "FBB::Arg" "3bobcat" "2005\-2020" "libbobcat\-dev_5\&.07\&.00" "Command Line Arguments"

.PP 
.SH "NAME"
FBB::Arg \- A singleton class interfacing command line arguments
.PP 
.SH "SYNOPSIS"
\fB#include <bobcat/arg>\fP
.br 
Linking option: \fI\-lbobcat\fP 
.PP 
.SH "DESCRIPTION"
Singleton class (see Gamma \fIet al\&.\fP, 1995) built around \fBgetopt()\fP(3)
and \fBgetopt_long()\fP(3)\&. The class handles short\- and long command\-line
options,
.PP 
.SH "NAMESPACE"
\fBFBB\fP
.br 
All constructors, members, operators and manipulators, mentioned in this
man\-page, are defined in the namespace \fBFBB\fP\&.
.PP 
.SH "INHERITS FROM"
\-
.PP 
.SH "ENUMERATION"

.PP 
The \fBFBB::Arg::Type\fP enumeration is defined by the \fBFBB::Arg\fP
class\&. It is used to specify whether or not long options require arguments\&. It
defines the following values: \fBNone, Required, Optional\fP\&.
.IP o 
\fBNone\fP: the long option does not use an argument;
.IP o 
\fBRequired\fP: the long option requires an argument value;
.IP o 
\fBOptional\fP: the long option may optionally be provided with  an
argument value; 

.PP 
These values are used when constructing objects of the following (nested)
class \fBFBB::Arg::LongOption\fP\&.
.PP 
.SH "THE NESTED CLASS FBB::Arg::LongOption"
Long options are defined using objects of the nested class
\fBFBB::Arg::LongOption\fP\&. This class provides the following constructors:
.IP o 
\fBFBB::Arg::LongOption(char const *name, FBB::Arg::Type type =
FBB::Arg::None)\fP:
.br 
This constructor is used to define a long option for which no
corresponding short option is defined\&. The parameter \fIname\fP is the
name of the long option (without prefixing the \fI\-\-\fP characters,
which \fIare\fP required when specifying the long option)\&.
.IP 
.IP o 
\fBFBB::Arg::LongOption(char const *name, int optionChar)\fP:
.br 
This constructor is used to define a long option for which a
corresponding short option is defined\&. The parameter \fIname\fP is the
name of the long option (without prefixing the \fI\-\-\fP characters,
which \fIare\fP required when specifying the long option)\&.
In a program, long options may be specified as follows:
.IP o 
First, construct an array 
.nf 

    FBB::Arg::LongOption longOptions[] = { c1, c2, \&.\&.\&. cn };
        
.fi 
Where \fIc1, c2, \&.\&.\&., cn\fP are \fBn\fP constructor invocations of 
\fBFBB::Arg::LongOption()\fP constructors
.IP 
.IP o 
Next, pass \fBlongOptions, LongOptions + n\fP
as 2nd and 3rd arguments to \fBArg\(cq\&s\fP member \fBinitialize()\fP

.PP 
The class \fILongOptions\fP is primarily used internally by the \fIArg\fP
object, but it can also be used outside of the \fIArg\fP object\&. For that
situation the following members are provided:
.IP o 
\fBstd::string const &longName() const\fP:
.br 
returns the \fILongOption\(cq\&s\fP long option name;
.IP o 
\fBint optionChar() const\fP:
.br 
returns the \fILongOption\(cq\&s\fP option character (or one of the
\fIArg::Type\fP enumeration values if there is no option character
associated with the \fILongOption\fP)\&.

.PP 
.SH "CONSTRUCTORS"
Since the class is a \fISingleton\fP there are no public
constructors\&. Instead, static members are offered for initializing and
accessing the single \fBFBB::Arg\fP object\&.
.PP 
.SH "STATIC MEMBERS"
.IP o 
\fBFBB::Arg &initialize(char const *optstring, int argc, char **argv)\fP:
.br 
Initializes the \fBFBB::Arg\fP singleton\&. May be called only once\&.
Throws an \fBFBB::Exception\fP exception if called repeatedly or if
called with \fIargv\fP containing an undefined option\&. If so, the
\fBException\fP object\(cq\&s \fIwhat()\fP member provides details\&. A
reference to the singleton object is returned\&.
.IP 
.IP o 
\fBFBB::Arg &initialize(char const *optstring,
LongOption const *const begin,
LongOption const *const end,
int argc, char **argv)\fP:
.br 
Initializes the \fBFBB::Arg\fP singleton\&. Accepts two iterators of an
array of \fBArg::LongOption\fP objects\&. May be called only once\&. Throws
an \fBFBB::Exception\fP exception if called repeatedly or if called with
\fIargv\fP containing a undefined option\&. If so, the \fBException\fP
object\(cq\&s \fIwhat()\fP member provides details\&.  See the description of
\fBArg::LongOption\fP below\&.  A reference to the singleton
object is returned\&.
.IP 
The parameter \fIoptstring\fP must point to a null\-terminated byte
string (NTBS) containing option characters, possibly postfixed by:
.IP o 
a colon (\fI:\fP), indicating that the option requires an option
value\&. 
.IP o 
a double colon (\fI::\fP), 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\&., \fI\-tvalue\fP)\&. Long options optionally accepting
arguments should always immediately be followed by an assignment
character (\fI=\fP)\&. Here the option\(cq\&s value must immediately follow
the \fI=\fP character, and must start with a non\-blank
character\&. E\&.g\&., \fI\-\-value=\fP indicates an absent option value,
\fI\-\-value=text\fP indicates the option\(cq\&s value equals \fItext\fP\&.  If
an option value itself contains blanks, it must be surrounded by
single or double quotes (e\&.g\&., \fI\-t\(cq\&this value\(cq\&\fP, or
\fI\-\-text=\(cq\&this value\(cq\&\fP)\&. The surrounding quotes are
not part of the option\(cq\&s value\&.

.IP 
.IP o 
\fBFBB::Arg &instance()\fP:
.br 
Returns a reference to the iitialized \fBArg\fP object\&. If called before
initialization, an \fIFBB::Exception\fP exception is thrown\&.

.PP 
.SH "OVERLOADED OPERATOR"

.PP 
.IP o 
\fBchar const *operator[](size_t idx) const\fP:
.br 
Returns \fIargument[idx]\fP, after having removed all specified options\&.
It returns 0 if no \fIarg[x]\fP is available\&.  The program\(cq\&s name
(\fIargv[0]\fP) is NOT counted here: index 0 refers to the first
ARGUMENT, e\&.g\&., the program\(cq\&s \fIargv[1]\fP\&.

.PP 
.SH "NON\-STATIC MEMBER FUNCTIONS"
.IP o 
\fBchar const **argPointers() const\fP:
.br 
Returns \fIargv\fP\-like set of pointers to all remaining arguments\&. The
last element is guaranteed to be a 0\-pointer\&. The first \fInArg()\fP
elements point to the respective values of the NTBS arguments that
were passed to the program\&.
.IP 
The caller is responsible for returning the array of pointers to the
common pool, but should not delete the C\-strings to which the pointers
point\&. The following two statements illustrate this:
.nf 

    char const **ptr = Arg::instance()\&.argPointers();
    delete[] ptr;
      
.fi 

.IP 
.IP o 
\fBstd::string const &basename() const\fP:
.br 
Returns the program\(cq\&s basename\&.
.IP 
.IP o 
\fBsize_t beyondDashes() const\fP:
.br 
Returns the index of the first argument after a \fI\-\-\fP argument or
returns \fInArgs()\fP if no \fI\-\-\fP argument was encountered\&.
.br 
A \fI\-\-\fP argument ends \fIArg\fP\(cq\&s argument processing, and all arguments
beyond the first \fI\-\-\fP argument are kept `as is\(cq\&\&. The
\fIbeyondDashes\fP member returns the index of the first argument beyond
the \fI\-\-\fP argument, which itself is removed from the remaining set of
arguments\&.
.IP 
.IP o 
\fBvoid help() const\fP:
.br 
If the member \fIversionHelp\fP (see below) has been called then this
member calls the \fIusage\fP function that was passed to
\fIversionHelp\fP\&. If \fIversionHelp\fP has not been called (i\&.e\&., if no
\fIusage\fP function has been specified) an \fBFBB::Exception\fP is
thrown\&.
.IP 
.IP o 
\fBsize_t nArgs() const\fP:
.br 
Returns the number of arguments left after option\-removal\&.  The
program name \fBargv[0]\fP is NOT counted here\&.
.IP 
.IP o 
\fBsize_t nLongOptions() const\fP:
.br 
Returns the number of long options not having short option synonyms If
long options are multiply specified, then each specification is
counted\&.
.IP 
.IP o 
\fBsize_t nOptions() const\fP:
.br 
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\&.
.IP 
.IP o 
\fBsize_t option(int option) const\fP:
.br 
Returns the number of times `option\(cq\& was specified (or its long option
synonym, if defined)\&.
.IP 
.IP o 
\fBsize_t option(std::string const &options) const\fP:
.br 
Returns the number of times each of the options specified in the `option\(cq\&
argument were specified (or their long option synonyms)\&. Note that
each character in \fIoptions\fP must specify a single\-character option\&.
.IP 
.IP o 
\fBsize_t option(string *value, int option) const\fP:
.br 
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 \fI*value\fP, which
is left untouched if `option\(cq\& was not present\&. The parameter \fIvalue\fP
may be initialized to 0 if the option does not have a value or if the
option\(cq\&s value should not be stored\&.
.IP 
.IP o 
\fBsize_t option(size_t idx, string *value, int option) const\fP:
.br 
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 \fIidx\fPth occurrence (0\-based offset) of this option is stored
in \fI*value\fP, which is left untouched if `option\(cq\& was not present or
if \fIidx\fP is or exceeds the number of specifications of the provided
option\&. 0 may be specified for \fBvalue\fP if the option does not have a
value or if the value should not be stored\&.
.IP 
.IP o 
\fBsize_t option(size_t *idx, string *value, int option) const\fP:
.br 
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 \fIoption\fP specifications) of the first option
having a non\-empty option value is returned in \fI*idx\fP, while its
option value is stored in \fI*value\fP\&. Both \fI*value\fP and \fI*idx\fP are
left untouched if `option\(cq\& was not present\&. 0 may be specified for
\fBvalue\fP if the option does not have a value or if the value should
not be stored\&.
.IP 
.IP o 
\fBsize_t option(string *value, char const *longOption) const\fP:
.br 
Returns the number of times the specified long option (not having a
single\-character synonym) was present\&. Its value is then stored in
\fI*value\fP, which is left untouched if the long option was not
present\&. 0 may be specified for \fBvalue\fP if the option does not have
a value or if the value should not be stored\&.
.IP 
.IP o 
\fBsize_t option(size_t idx, string *value, 
char const * longOption) const\fP:
.br 
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 \fIidx\fPth occurrence (0\-based offset) of this
long option is stored in \fI*value\fP, which is left untouched if the
long option was not present or if \fIidx\fP is or exceeds the number of
specifications of the provided long option\&. 0 may be specified for
\fBvalue\fP if the long option does not have a value or if the value
should not be stored\&.
.IP 
.IP o 
\fBsize_t option(size_t *idx, string *value, int longOption) const\fP:
.br 
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 \fI*idx\fP, while its option value is stored in \fI*value\fP\&. Both
\fI*value\fP and \fI*idx\fP are left untouched if long option was not
present\&. 0 may be specified for \fBvalue\fP if the long option does not
have a value or if the value should not be stored\&.
.IP 
.IP o 
\fBvoid versionHelp(void (*usage)(std::string const &progname), 
char const *version, size_t minArgs, int helpFlag = \(cq\&h\(cq\&, 
int versionFlag = \(cq\&v\(cq\&) const\fP:
.br 
If the \fIhelpFlag\fP was specified \fIusage()\fP is called with
argument \fBbasename()\fP whereafter the program throws \fIint 0\fP\&.
.IP 
If \fIversionFlag\fP was specified the program\(cq\&s name (using basename())
and version is displayed to \fIstd::cout\fP whereafter the program
throws \fIint 0\fP\&.
.IP 
If there are fewer arguments than \fIminArgs\fP \fIusage()\fP is called with
argument \fBbasename()\fP and the program ends with exit value 1\&.
.IP 
Note that \fIversionhelp\fP compares \fIminArgs\fP against \fInArgs\fP\&. If
\fIminArgs\fP should be compaired against the number of arguments up to
a possible `\-\-\(cq\& argument (i\&.e\&., \fIbeyondDashes\fP\(cq\& return value), then
add \fInArgs() \- beyondDashes()\fP to the \fIminArg\fP argument\&. E\&.g\&.,
.nf 

    arg\&.versionHelp(usage, version, 2 + arg\&.nArgs() 
                                      \- arg\&.beyondDashes());
            
.fi 
The address of the \fIusage()\fP function, the current version and the
minimum number of arguments must be specified\&. Default argument values
are provided for the option flags\&.

.PP 
.SH "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\&.
.nf 

#include <bobcat/arg>

using namespace FBB;
using namespace std;

namespace   // the anonymous namespace can be used here
{
    Arg::LongOption longOptions[] = 
    {
        Arg::LongOption{\(dq\&debug\(dq\&},
        Arg::LongOption{\(dq\&filenames\(dq\&, \(cq\&f\(cq\&},
        Arg::LongOption{\(dq\&help\(dq\&, \(cq\&h\(cq\&},
        Arg::LongOption{\(dq\&version\(dq\&, \(cq\&v\(cq\&},
    };
    auto longEnd = longOptions + size(longOptions);
}

int main(int argc, char **argv)
try
{
    Arg &arg = Arg::initialize(\(dq\&df:hv\(dq\&, 
                    longOptions, longEnd, 
                    argc, argv);

    // code using arg, etc\&.
}
catch (exception const &err)     // handle exceptions
{
    cerr << err\&.what() << \(cq\&\en\(cq\&;
    return 1;
}
    
.fi 

.PP 
.SH "FILES"
\fIbobcat/arg\fP \- defines the class interface
.PP 
.SH "SEE ALSO"
\fBbobcat\fP(7)
.PP 
.SH "BUGS"
None Reported\&.
.PP 
.SH "BOBCAT PROJECT FILES"

.PP 
.IP o 
\fIhttps://fbb\-git\&.gitlab\&.io/bobcat/\fP: gitlab project page;
.IP o 
\fIbobcat_5\&.07\&.00\-x\&.dsc\fP: detached signature;
.IP o 
\fIbobcat_5\&.07\&.00\-x\&.tar\&.gz\fP: source archive;
.IP o 
\fIbobcat_5\&.07\&.00\-x_i386\&.changes\fP: change log;
.IP o 
\fIlibbobcat1_5\&.07\&.00\-x_*\&.deb\fP: debian package containing the
libraries;
.IP o 
\fIlibbobcat1\-dev_5\&.07\&.00\-x_*\&.deb\fP: debian package containing the
libraries, headers and manual pages;

.PP 
.SH "BOBCAT"
Bobcat is an acronym of `Brokken\(cq\&s Own Base Classes And Templates\(cq\&\&.
.PP 
.SH "COPYRIGHT"
This is free software, distributed under the terms of the 
GNU General Public License (GPL)\&.
.PP 
.SH "AUTHOR"
Frank B\&. Brokken (\fBf\&.b\&.brokken@rug\&.nl\fP)\&.
.PP