.TH "FBB::Arg" "3bobcat" "2005\-2023" "libbobcat\-dev_6\&.04\&.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_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 defining long options (like \fI\-\-version\fP), which
are defined as objects of the (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 specifying the \-\- characters which
are only required when specifying a long option when calling a
program)\&.
.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 specifying the \-\- characters which
are only required when specifying a long option when calling a
program)\&.

.PP 
To define long options use the following procedure:
.IP o 
First, construct an array
.nf 

    FBB::Arg::LongOption longOptions[] = { c1, c2, \&.\&.\&., cn };
        
.fi 
Where \fIc1, c2, \&.\&.\&., cn\fP are \fIn\fP constructor invocations of
\fBFBB::Arg::LongOption()\fP constructors
.IP 
.IP o 
Next, pass \fIlongOptions, LongOptions + n\fP as arguments to an
\fIArg::initialize\fP member that supports long options\&.

.PP 
Objects of the class \fILongOptions\fP are normally used internally by the
\fIArg\fP object, but they can also be used outside of the \fIArg\fP object\&. For
that situation the following members are available:
.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 \fIArg\fP is a \fIsingleton\fP there are no public
constructors\&. Instead, static members are available to initialize and to
access the single \fBFBB::Arg\fP object\&.
.PP 
.SH "STATIC MEMBERS"

.PP 
All \fIinitialize\fP members initialize the \fBFBB::Arg\fP singleton, and can
only be called once\&. An exception is thrown when called multiple
times\&. All \fIinitialize\fP members return a reference to the initialized
\fIArg\fP singleton object\&.
.PP 
All \fIinitialize\fP members define the parameters \fIargc\fP and \fIargv\fP
which are interpreted as \fImain\(cq\&s\fP \fIargc\fP and \fIargv\fP parameters\&.  When an
\fIargv\fP element points to two consecutive dashes (\fI\-\-\fP) then that element
is ignored, and all of \fIargv\(cq\&s\fP subsequent elements are considered
arguments instead of options\&.
.PP 
.IP o 
\fBFBB::Arg &Arg::initialize(char const *optstring, int argc, char
**argv)\fP:
.br 
The parameter \fIoptstring\fP 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:
.RS 
.IP o 
a single colon (:) indicates that the option requires an
option value\&.
.IP 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\&.,
\fI\-tvalue\fP)\&. Long options optionally accepting arguments should
always immediately be followed by an assignment character (=),
immediately followed by the option\(cq\&s value (which 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\&.
.RE

.IP 
When \fIoptstring\(cq\&s\fP 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 \fIoptstring\fP
is \fI+ab\fP and no long options are defined, then calling
.nf 

    prog \-a \-z \-b \-yvalue \-\-long arg1 arg2
    
.fi 
results in the member \fIargv\fP returning a vector containing the
elements \fI\-z, \-yvalue, \-\-long, arg1,\fP and \fIarg2\fP\&. If
\fIoptstring\(cq\&s\fP first character isn\(cq\&t + and an undefined option is
encountered then an exception is thrown\&.
.IP 
.IP o 
\fBFBB::Arg &Arg::initialize(int accept, char const *optstring, int
argc, char **argv)\fP:
.br 
Acts like the previous member, but in addition defines the
parameter \fIaccept\fP specifying an option character from where all
subsequent arguments and options are considered arguments\&. To ignore
\fIaccept\fP the value 0 (not the character \(cq\&0\(cq\&) can be specified or an
\fIinitialize\fP members can be used that does not define an
\fIaccept\fP parameter\&.
.IP 
When arguments contain both an \fIaccept\fP option and two consecutive
dashes then the first one is interpreted, resulting in all remaining
\fIargv\fP elements being interpreted as mere arguments\&. For example,
when specifying \fIinitialize(\(cq\&t\(cq\&, \&.\&.\&.)\fP and calling
.nf 

    prog one \-ttwo \-c \-\- three
    
.fi 
then the member \fIargv\fP returns a vector containing the elements
\fIone, \-tttwo, \-c, \-\-\fP, and \fIthree\fP (see also the member
\fIbeyondDashes\fP below)\&.
.IP 
.IP o 
\fBFBB::Arg &Arg::initialize(char const *optstring,
Arg::LongOption const *const begin,
Arg::LongOption const *const end,
int argc, char **argv)\fP:
.br 

.IP 
Acts like the first \fIArg::initialize\fP member, but in addition defines
two parameters specifying the range of elements of an array of
\fIArg::LongOption\fP objects specifying long options\&. The parameter
\fIbegin\fP points to the first element of the range, the parameter
\fIend\fP points just beyond the last element of the range\&. E\&.g\&., after
defining
.nf 

    FBB::Arg::LongOption longOptions[] = { c1, c2, \&.\&.\&., cn };
    
.fi 
the arguments passed to \fIbegin\fP and \fIend\fP could be specified as
.nf 

    initialize(\&.\&.\&., longOptions, longOptions + size(longOptions), \&.\&.\&.);
    
.fi 

.IP 
.IP o 
\fBFBB::Arg &Arg::initialize(char accept, char const *optstring,
LongOption const *const begin,
LongOption const *const end,
int argc, char **argv)\fP:
.br 

.IP 
Acts like the previous \fIArg::initialize\fP member, but in addition
defines an \fIaccept\fP parameter as defined by the second
\fIArg::initialize\fP member\&.
.IP 
.IP o 
\fBFBB::Arg &Arg::instance()\fP:
.br 
Once an \fIArg::initialize\fP 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 \fBArg\fP object\&.
.IP 
If it is called before an \fIArg::initialize\fP member has been called
an exception is thrown\&.

.PP 
.SH "OVERLOADED OPERATOR"

.PP 
.IP o 
\fBchar const *operator[](size_t idx) const\fP:
.br 
Returns \fIargument[idx]\fP, after all options have been removed\&.
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"

.PP 
.IP o 
\fBstring const &argv0() const\fP:
.br 
Returns the program\(cq\&s name as specified by \fIargv[0]\fP (see also the
member \fIbasename\fP);
.IP 
.IP o 
\fBchar const **argPointers() const\fP:
.br 
Returns \fIargv\fP\-like set of pointers to all remaining
arguments\&. Element \fInArgs() + 1\fP is a 0\-pointer\&. The first
\fInArgs()\fP elements point to the respective values of the NTBS
arguments that were passed to the program, after having removed the
options\&.
.IP 
The caller is responsible for returning the array of pointers returned
by this member to the common pool, but the caller should not delete
the NTBSs to which the pointers point as illustrated by the following
two statements:
.nf 

    char const **ptr = Arg::instance()\&.argPointers();
    delete[] ptr;   // don\(cq\&t delete ptr[idx] elements!
      
.fi 

.IP 
.IP o 
\fBstd::vector<std::string> const &args() const\fP:
.br 
Returns a vector of strings containing all arguments after having
removed all options\&.  The program\(cq\&s name (\fIargv[0]\fP) is
NOT included here: its first element refers to the first ARGUMENT,
e\&.g\&., the program\(cq\&s \fIargv[1]\fP;
.IP 
.IP o 
\fBstd::string const &basename() const\fP:
.br 
Returns the program\(cq\&s basename (i\&.e\&., \fIargv0()\(cq\&s\fP value beyond the
last directory separator);
.IP 
.IP o 
\fBstd::vector<std::string>::const_iterator begin() const\fP:
.br 
Returns the iterator to the program\(cq\&s first argument (i\&.e\&.,
\fIargs()\&.begin()\fP)\&. This member, in combination with the member
\fIend\fP, allows processing of all arguments by generic algorithms;
.IP 
.IP o 
\fBsize_t beyondDashes() const\fP:
.br 
Returns the index of the first argument beyond the \fI\-\-\fP argument or
returns the index of the \fIaccept\fP argument (whichever comes first)
or returns \fInArgs()\fP if no \fI\-\-\fP or \fIaccept\fP argument was
encountered\&. See also the member \fInArgs\fP below;
.IP 
.IP o 
\fBstd::vector<std::string>::const_iterator end() const\fP:
.br 
Returns the iterator pointing beyond the program\(cq\&s last argument (i\&.e\&.,
\fIargs()\&.end()\fP)\&. This member, in combination with the member
\fIbegin\fP, allows processing of all arguments by generic algorithms;
.IP 
.IP o 
\fBvoid help() const\fP:
.br 
If the member \fIversionHelp\fP (see below) was 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 exception is thrown;
.IP 
.IP o 
\fBsize_t nArgs() const\fP:
.br 
Returns the number of arguments after having removed the options (i\&.e\&.,
it returns \fIargs()\&.size()\fP)\&. Note that the program\(cq\&s name is not
counted here;
.IP 
.IP o 
\fBsize_t nLongOptions() const\fP:
.br 
Returns the number of long options not having short option synonyms\&.
Multiply specified long options are each 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_6\&.04\&.00\-x\&.dsc\fP: detached signature;
.IP o 
\fIbobcat_6\&.04\&.00\-x\&.tar\&.gz\fP: source archive;
.IP o 
\fIbobcat_6\&.04\&.00\-x_i386\&.changes\fP: change log;
.IP o 
\fIlibbobcat1_6\&.04\&.00\-x_*\&.deb\fP: debian package containing the
libraries;
.IP o 
\fIlibbobcat1\-dev_6\&.04\&.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