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) handling short- and long command-line options,

NOTE: since bobcat version 6.07.00 FBB::Arg::Type::None was renamed to FBB::Arg::Type::NoArg.

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 is used to specify whether or not long options require arguments. It defines the following values: NoArg, Required, Optional.

o

NoArg: 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 defining long options (like --version), which are defined as objects of the (nested) class FBB::Arg::LongOption.

THE 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::NoArg):
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 specifying the -- characters which are only required when specifying a long option when calling a program).

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 specifying the -- characters which are only required when specifying a long option when calling a program).

To define long options use the following procedure:

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 arguments to an Arg::initialize member that supports long options.

Objects of the class LongOptions are normally used internally by the Arg object, but they can also be used outside of the Arg object. For that situation the following members are available:

o

std::string const &longName() const:
returns the LongOption’s long option name;

o

int optionChar() const:
returns the LongOption’s option character (or one of the Arg::Type enumeration values if there is no option character associated with the LongOption);

o

FBB::Arg::Type type() const:
returns the LongOption’s type.

CONSTRUCTORS

Since the class Arg is a singleton there are no public constructors. Instead, static members are available to initialize and to access the single FBB::Arg object.

STATIC MEMBERS

All initialize members initialize the FBB::Arg singleton, and can only be called once. An exception is thrown when called multiple times. All initialize members return a reference to the initialized Arg singleton object.

All initialize members define the parameters argc and argv which are interpreted as main’s argc and argv parameters. When an argv element points to two consecutive dashes (--) then that element is ignored, and all of argv’s subsequent elements are considered arguments instead of options.

Note: for backward compatibility all initialize members and the instance member defined in previous versions return non-const references, even though all members of the FBB::Arg class are const members. Some new initialize members were added in version 6.14.00. In future releases these members may all return Arg const references.

o

FBB::Arg &Arg::initialize(char const *optstring, int argc, char **argv):
The parameter optstring 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:

When optstring’s 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 optstring is +ab and no long options are defined, then calling

    prog -a -z -b -yvalue --long arg1 arg2


    

results in the member argv returning a vector containing the elements -z, -yvalue, --long, arg1, and arg2: options -a and -b were recognized as short options and were not added to the vector returned by the argv member. If optstring’s first character isn’t + and an undefined option is encountered then an exception is thrown.

o

FBB::Arg &Arg::initialize(int accept, char const *optstring, int argc, char **argv):
Acts like the previous member, but in addition defines the parameter accept specifying a (short) option character from where all subsequent arguments and options are considered arguments. To ignore accept the value 0 (not the character ’0’) can be specified or an initialize members can be used that does not define an accept parameter.

When arguments contain contain two consecutive dashes then all the -- argument is skipped and all remaining arguments are added as-is to the vector returned by the argv member.

For example, when specifying initialize(’t’, ...) and calling

    prog one -ttwo -c -- three


    

then argv returns a vector containing the elements one, -tttwo, -c, -- three, and when calling

    prog one -- -ttwo -c -- three


    

argv returns a vector containing the elements one, -tttwo, -c, three (see also the member beyondDashes below).

o

FBB::Arg const &Arg::initialize(char const *accept, char const *optstring, int argc, char **argv):
Acts like the previous member, but the parameter accept specifies (short) option characters from where all subsequent arguments and options are considered arguments. Specify an empty string if no accept characters are defined.

o

FBB::Arg const &Arg::initialize(char const *optstring, Arg::LongOption const *const begin, Arg::LongOption const *const end, int argc, char **argv):

Acts like the first Arg::initialize member, but in addition defines two parameters specifying the range of elements of an array of Arg::LongOption objects specifying long options. The parameter begin points to the first element of the range, the parameter end points just beyond the last element of the range. E.g., after defining

    FBB::Arg::LongOption longOptions[] = { c1, c2, ..., cn };


    

the arguments passed to begin and end could be specified as

    initialize(..., longOptions, longOptions + size(longOptions), ...);


    

o

FBB::Arg &Arg::initialize(char accept, char const *optstring, LongOption const *const begin, LongOption const *const end, int argc, char **argv):

Acts like the previous Arg::initialize member, but in addition defines an accept parameter as defined by the second Arg::initialize member.

o

FBB::Arg const &Arg::initialize(char const *accept, char const *optstring, LongOption const *const begin, LongOption const *const end, int argc, char **argv):
Acts like the previous member, but the parameter accept specifies (short) option characters from where all subsequent arguments and options are considered arguments. Specify an empty string if no accept characters are defined.

o

FBB::Arg &Arg::instance():
Once an Arg::initialize 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 Arg object.

If it is called before an Arg::initialize member has been called an exception is thrown.

OVERLOADED OPERATOR

o

char const *operator[](size_t idx) const:
Returns argument[idx], after all options have been removed. 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 after having removed (processed) the options.

NON-STATIC MEMBER FUNCTIONS

o

string const &argv0() const:
Returns the program’s name as specified by argv[0] (see also the member basename);

o

char const **argPointers() const:
Returns the (nArgs()) elements returned by argv as a series of pointers to all its arguments. Element nArgs() + 1 is a 0-pointer.

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:

    char const **ptr = Arg::instance().argPointers();


    delete[] ptr;       // *** don’t delete ptr[idx] elements !!


      

o

std::vector<std::string> const &args() const:
Returns a vector of strings containing all arguments after having removed the options. The program’s name (argv[0]) is not included here: its first element refers to the first argument, e.g., the program’s argv[1];

o

std::string const &basename() const:
Returns the program’s basename (i.e., argv0()’s value beyond the last directory separator);

o

std::vector<std::string>::const_iterator begin() const:
Returns the iterator to the program’s first argument (i.e., args().begin()). This member, in combination with the member end, allows processing of all arguments by, e.g., generic algorithms;

o

size_t beyondDashes() const:
Returns the index of the first argument beyond the -- argument or returns the index of the accept argument (whichever comes first) or returns nArgs() if no -- or accept argument was used. See also the member nArgs below;

o

std::vector<std::string>::const_iterator end() const:
Returns the iterator pointing beyond the program’s last argument (i.e., args().end()). This member, in combination with the member begin, allows processing of all arguments by generic algorithms;

o

void help() const:
If the member versionHelp (see below) was 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 exception is thrown;

o

size_t nArgs() const:
Returns the number of arguments after having removed the options (i.e., it returns args().size()). Note that the program’s name is not counted here;

o

size_t nLongOptions() const:
Returns the number of long options not having short option synonyms. Multiply specified long options are each 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 the helpFlag was specified usage() is called with argument basename() whereafter the program throws int 0.

If versionFlag was specified the program’s name (using basename()) and version is displayed to std::cout whereafter the program throws int 0.

If there are fewer arguments than minArgs usage() is called with argument basename() and the program ends with exit value 1.

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.

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;
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;
}


    

FILES

bobcat/arg - defines the class interface

SEE ALSO

ArgConfig(3bobcat), bobcat(7)

BUGS

None Reported.

BOBCAT PROJECT FILES

o

https://fbb-git.gitlab.io/bobcat/: gitlab project page;

Debian Bobcat project files:

o

libbobcat6: debian package containing the shared library, changelog and copyright note;

o

libbobcat-dev: debian package containing the static library, headers, manual pages, and developer info;

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).