Provided by: libbobcat-dev_5.00.02-2_amd64 bug

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.00.02-x.dsc: detached signature;

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

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

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

       o      libbobcat1-dev_5.00.02-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).