Provided by: libbobcat-dev_4.08.02-2build1_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 has the following
       values intended for public use: None, Required,  Optional.  These  values  are  used  when
       constructing objects of the nested class FBB::Arg::LongOption, see below.

CONSTRUCTORS

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

STATIC MEMBERS

       o      FBB::Arg &initialize(char const *optstring, int argc, char **argv):
              Initializes  the  FBB::Arg  singleton.  Must  be  called  only  once.   Throws   an
              FBB::Exception exception if called repeatedly or if called with argv not containing
              a defined option (which is shown by the FBB::Exception’s what() member). Returns  a
              reference  to  the  singleton  object,  allowing  code  initializing Arg to use the
              initialized object immediately.

       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, holding long-options. Must be called only once. Throws  an
              FBB::Exception exception if called repeatedly or if called with argv not containing
              a defined option (which is shown by the FBB::Exception’s what() member).   See  the
              description of Arg::LongOption below.  Returns a reference to the singleton object,
              allowing code initializing Arg to use the initialized object immediately.

              optstring should consist of letters, possibly postfixed by:

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

       o      a double colon (::), indicating that the option itself has  an  optional  argument.
              With  short  options  the  option  value is considered absent unless it immediately
              follows the short option (e.g., -tvalue  for  a  short  option  -t).  Long  options
              optionally  accepting  arguments  should  always  immediately  be  followed  by a =
              character. Here the option’s value must immediately follow  the  =  character,  and
              must  start with a non-blank character, or the option’s value is considered absent.
              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 should
              be surrounded by single or double quotes (e.g.,  -t’this  value’,  or  --text=’this
              value’). The surrounding quotes themselves are not part of the option’s value.

       o      FBB::Arg &instance():
              Returns  the  instance  of  the  Arg  object,  available  after  calling one of the
              Arg::initialize() members.  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.  0 is returned
              if no arg[x] is available.  The program 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
              C-string values of the arguments.

       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 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) then an 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 for which no short option synonym exist. 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 counted.

       o      size_t option(int option) const:
              The number of times `option’ (or its long option synonym, if defined) was specified
              is returned.

       o      size_t option(std::string const &options) const:
              The number of times one of the options specified in the `option’ argument (or their
              long option synonyms) were present is returned.

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

THE NESTED CLASS FBB::Arg::LongOption

       Long options are defined using objects of  the  nested  class  FBB::Arg::LongOption.  This
       class offers the following constructors:

       o      FBB::Arg::LongOption(char const *name, FBB::Arg::Type type = 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 initialize()

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;

       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 + sizeof(longOptions) / sizeof(longOptions[0]);
       }

       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() << endl;
           return err.which();
       }
       catch(int x)
       {
           return x;
       }

FILES

       bobcat/arg - defines the class interface

SEE ALSO

       bobcat(7)

BUGS

       None Reported.

DISTRIBUTION FILES

       o      bobcat_4.08.02-x.dsc: detached signature;

       o      bobcat_4.08.02-x.tar.gz: source archive;

       o      bobcat_4.08.02-x_i386.changes: change log;

       o      libbobcat1_4.08.02-x_*.deb: debian package holding the libraries;

       o      libbobcat1-dev_4.08.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).