includefile(include/header)

COMMENT(manpage, section, releasedate, archive, short name)
manpage(FBB::Arg)(3bobcat)(_CurYrs_)(libbobcat-dev__CurVers_)
                    (Command Line Arguments)

manpagename(FBB::Arg)(A singleton class interfacing command line arguments)

manpagesynopsis()
    bf(#include <bobcat/arg>)nl()
    Linking option: tt(-lbobcat)

manpagedescription()
    Singleton class (see Gamma em(et al.), 1995) built around
bf(getopt_long())(3). The class handles short- and long command-line options,

includefile(include/namespace)

manpagesection(INHERITS FROM)
    -

manpagesection(ENUMERATION)

    The bf(FBB::Arg::Type) enumeration is defined by the bf(FBB::Arg)
class. It is used to specify whether or not long options require arguments. It
defines the following values: bf(None, Required, Optional).
    itemization(
    it() bf(None): the long option does not use an argument;
    it() bf(Required): the long option requires an argument value;
    it() bf(Optional): the long option may optionally be provided with  an
        argument value;
    )

These values are used when defining long options (like tt(--version)), which
are defined as objects of the (nested) class bf(FBB::Arg::LongOption).

manpagesection(THE NESTED CLASS FBB::Arg::LongOption)
   Long options are defined using objects of the nested class
    bf(FBB::Arg::LongOption). This class provides the following constructors:
   itemization(
    itb(FBB::Arg::LongOption(char const *name, FBB::Arg::Type type =
        FBB::Arg::None))
       This constructor is used to define a long option for which no
        corresponding short option is defined. The parameter tt(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).

    itb(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 tt(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:
    itemization(
    it() First, construct an array
        verb(
    FBB::Arg::LongOption longOptions[] = { c1, c2, ..., cn };
        )
    Where tt(c1, c2, ..., cn) are tt(n) constructor invocations of
        bf(FBB::Arg::LongOption()) constructors

    it() Next, pass tt(longOptions, LongOptions + n) as arguments to an
        tt(Arg::initialize) member that supports long options.
    )

    Objects of the class tt(LongOptions) are normally used internally by the
tt(Arg) object, but they can also be used outside of the tt(Arg) object. For
that situation the following members are available:
    itemization(
    itb(std::string const &longName() const)
       returns the tt(LongOption's) long option name;
    itb(int optionChar() const)
       returns the tt(LongOption's) option character (or one of the
        tt(Arg::Type) enumeration values if there is no option character
        associated with the tt(LongOption)).
    )

manpagesection(CONSTRUCTORS)
    Since the class tt(Arg) is a em(singleton) there are no public
constructors. Instead, static members are available to initialize and to
access the single bf(FBB::Arg) object.

manpagesection(STATIC MEMBERS)

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

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


    itemization(
    itb(FBB::Arg &Arg::initialize(char const *optstring, int argc, char
        **argv))
       The parameter tt(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:
       quote(
       itemization(
        it() a single colon (:) indicates that the option requires an
            option value.
        it() 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.,
            tt(-tvalue)). Long options optionally accepting arguments should
            always immediately be followed by an assignment character (=),
            immediately followed by the option's value (which must start with
            a non-blank character). E.g., tt(--value=) indicates an absent
            option value, tt(--value=text) indicates the option's value equals
            tt(text).  If an option value itself contains blanks, it must be
            surrounded by single or double quotes (e.g., tt(-t'this value'),
            or tt(--text='this value')). The surrounding quotes are not part
            of the option's value.
        ))

        When tt(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 tt(optstring)
        is tt(+ab) and no long options are defined, then calling
    verb(
    prog -a -z -b -yvalue --long arg1 arg2
    )
       results in the member tt(argv) returning a vector containing the
        elements tt(-z, -yvalue, --long, arg1,) and tt(arg2). If
        tt(optstring's) first character isn't + and an undefined option is
        encountered then an exception is thrown.

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

        When arguments contain both an tt(accept) option and two consecutive
        dashes then the first one is interpreted, resulting in all remaining
        tt(argv) elements being interpreted as mere arguments. For example,
        when specifying tt(initialize('t', ...)) and calling
    verb(
    prog one -ttwo -c -- three
    )
       then the member tt(argv) returns a vector containing the elements
        tt(one, -tttwo, -c, --), and tt(three) (see also the member
        tt(beyondDashes) below).

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

      Acts like the first tt(Arg::initialize) member, but in addition defines
        two parameters specifying the range of elements of an array of
        tt(Arg::LongOption) objects specifying long options. The parameter
        tt(begin) points to the first element of the range, the parameter
        tt(end) points just beyond the last element of the range. E.g., after
        defining
    verb(
    FBB::Arg::LongOption longOptions[] = { c1, c2, ..., cn };
    )
       the arguments passed to tt(begin) and tt(end) could be specified as
    verb(
    initialize(..., longOptions, longOptions + size(longOptions), ...);
    )

    itb(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 tt(Arg::initialize) member, but in addition
        defines an tt(accept) parameter as defined by the second
        tt(Arg::initialize) member.

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

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

manpagesection(OVERLOADED OPERATOR)

    itemization(
    itb(char const *operator[](size_t idx) const)
       Returns tt(argument[idx]), after all options have been removed.
        It returns 0 if no tt(arg[x]) is available.  The program's name
        (tt(argv[0])) is NOT counted here: index 0 refers to the first
        ARGUMENT, e.g., the program's tt(argv[1]).
    )

manpagesection(NON-STATIC MEMBER FUNCTIONS)

    itemization(
    itb(string const &argv0() const)
       Returns the program's name as specified by tt(argv[0]) (see also the
        member tt(basename));

    itb(char const **argPointers() const)
       Returns tt(argv)-like set of pointers to all remaining
        arguments. Element tt(nArgs() + 1) is a 0-pointer. The first
        tt(nArgs()) elements point to the respective values of the NTBS
        arguments that were passed to the program, after having removed the
        options.

       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:
      verb(
    char const **ptr = Arg::instance().argPointers();
    delete[] ptr;   // don't delete ptr[idx] elements!
      )

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

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

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

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

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

    itb(void help() const)
       If the member tt(versionHelp) (see below) was called then this member
        calls the tt(usage) function that was passed to tt(versionHelp). If
        tt(versionHelp) has not been called (i.e., if no tt(usage) function
        has been specified) an exception is thrown;

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

    itb(size_t nLongOptions() const)
       Returns the number of long options not having short option synonyms.
        Multiply specified long options are each counted;

    itb(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;

    itb(size_t option(int option) const)
       Returns the number of times `option' was specified (or its long option
        synonym, if defined);

    itb(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 tt(options) must specify a single-character
        option;

    itb(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 tt(*value), which
        is left untouched if `option' was not present. The parameter tt(value)
        may be initialized to 0 if the option does not have a value or if the
        option's value should not be stored;

    itb(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 tt(idx)th occurrence (0-based offset) of this option is stored
        in tt(*value), which is left untouched if `option' was not present or
        if tt(idx) is or exceeds the number of specifications of the provided
        option. 0 may be specified for bf(value) if the option does not have a
        value or if the value should not be stored;

    itb(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 tt(option) specifications) of the first option
        having a non-empty option value is returned in tt(*idx), while its
        option value is stored in tt(*value). Both tt(*value) and tt(*idx) are
        left untouched if `option' was not present. 0 may be specified for
        bf(value) if the option does not have a value or if the value should
        not be stored;

    itb(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
        tt(*value), which is left untouched if the long option was not
        present. 0 may be specified for bf(value) if the option does not have
        a value or if the value should not be stored;

    itb(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 tt(idx)th occurrence (0-based offset) of this
        long option is stored in tt(*value), which is left untouched if the
        long option was not present or if tt(idx) is or exceeds the number of
        specifications of the provided long option. 0 may be specified for
        bf(value) if the long option does not have a value or if the value
        should not be stored;

    itb(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 tt(*idx), while its option value is stored in tt(*value). Both
        tt(*value) and tt(*idx) are left untouched if long option was not
        present. 0 may be specified for bf(value) if the long option does not
        have a value or if the value should not be stored;

    itb(void versionHelp(void (*usage)(std::string const &progname),
        char const *version, size_t minArgs, int helpFlag = 'h',
        int versionFlag = 'v') const)
       If the tt(helpFlag) was specified tt(usage()) is called with
        argument bf(basename()) whereafter the program throws tt(int 0).

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

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

       Note that tt(versionhelp) compares tt(minArgs) against tt(nArgs). If
        tt(minArgs) should be compaired against the number of arguments up to
        a possible `--' argument (i.e., tt(beyondDashes)' return value), then
        add tt(nArgs() - beyondDashes()) to the tt(minArg) argument. E.g.,
            verb(
    arg.versionHelp(usage, version, 2 + arg.nArgs()
                                      - arg.beyondDashes());
            )
       The address of the tt(usage()) function, the current version and the
        minimum number of arguments must be specified. Default argument values
        are provided for the option flags.
    )

manpagesection(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.
        verb(
#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;
}
    )

manpagefiles()
    em(bobcat/arg) - defines the class interface

manpageseealso()
    bf(bobcat)(7)

manpagebugs()
    None Reported.

includefile(include/trailer)