arg

FBB::Arg(3bobcat)            Command Line Arguments            FBB::Arg(3bobcat)



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

       o      None: 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 constructing objects of the following (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::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).

       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 prefixing the -- characters,
              which are required when specifying the long option).  In a
              program, long options may be specified as follows:

       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 2nd and 3rd arguments
              to Arg’s member initialize()


CONSTRUCTORS
       Since the class is a Singleton there are no public constructors. Instead,
       static members are offered for initializing and accessing the single
       FBB::Arg object.

STATIC MEMBERS
       o      FBB::Arg &initialize(char const *optstring, int argc, char
              **argv):
              Initializes the FBB::Arg singleton. May be called only once.
              Throws an FBB::Exception exception if called repeatedly or if
              called with argv containing an undefined option. If so, the
              Exception object’s what() member provides details. A reference to
              the singleton object is returned.

       o      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. May be called only once. Throws
              an FBB::Exception exception if called repeatedly or if called with
              argv containing a undefined option. If so, the Exception object’s
              what() member provides details.  See the description of
              Arg::LongOption below.  A reference to the singleton object is
              returned.

              The parameter optstring must point to a null-terminated byte
              string (NTBS) containing option characters, possibly postfixed by:

       o      a colon (:), indicating that the option requires an option value.

       o      a double colon (::), 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.,
              -tvalue). Long options optionally accepting arguments should
              always immediately be followed by an assignment character (=).
              Here the option’s value must immediately follow the = character,
              and must start with a non-blank character. E.g., --value=
              indicates an absent option value, --value=text indicates the
              option’s value equals text.  If an option value itself contains
              blanks, it must be surrounded by single or double quotes (e.g.,
              -t’this value’, or --text=’this value’). The surrounding quotes
              are not part of the option’s value.


       o      FBB::Arg &instance():
              Returns a reference to the iitialized Arg object. If called before
              initialization, an FBB::Exception exception is thrown.


OVERLOADED OPERATOR
       o      char const *operator[](size_t idx) const:
              Returns argument[idx], after having removed all specified options.
              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, e.g., the program’s argv[1].


NON-STATIC MEMBER FUNCTIONS
       o      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 values of the NTBS arguments that
              were passed to the program.

       o      std::string const &basename() const:
              Returns the program’s basename.

       o      size_t beyondDashes() const:
              Returns the index of the first argument after a -- argument or
              returns nArgs() if no -- argument was encountered.
              A -- argument ends Arg’s argument processing, and all arguments
              beyond the first -- argument are kept `as is’. The beyondDashes
              member returns the index of the first argument beyond the --
              argument, which itself is removed from the remaining set of
              arguments.

       o      void help() const:
              If the member versionHelp (see below) has been 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 FBB::Exception is thrown.

       o      size_t nArgs() const:
              Returns the number of arguments left after option-removal.  The
              program name argv[0] is NOT counted here.

       o      size_t nLongOptions() const:
              Returns the number of long options not having short option
              synonyms If long options are multiply specified, then each
              specification is 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 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 minArgs usage() is called with argument
              basename(). If either version- or help information is shown, the
              int value 1 is thrown as an exception.
              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
       bobcat(7)

BUGS
       None Reported.

DISTRIBUTION FILES
       o      bobcat_5.02.00-x.dsc: detached signature;

       o      bobcat_5.02.00-x.tar.gz: source archive;

       o      bobcat_5.02.00-x_i386.changes: change log;

       o      libbobcat1_5.02.00-x_*.deb: debian package holding the libraries;

       o      libbobcat1-dev_5.02.00-x_*.deb: debian package holding the
              libraries, headers and manual pages;

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

AUTHOR
       Frank B. Brokken (f.b.brokken@rug.nl).

libbobcat-dev_5.02.00-x.tar.gz      2005-2019                  FBB::Arg(3bobcat)