Provided by: libbobcat-dev_6.04.00-1ubuntu3_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_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 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::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
              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).

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.

       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:

              o      a single colon (:) indicates that the option requires an option value.

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

              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.  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 an 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  both an accept option and two consecutive dashes then the
              first  one  is  interpreted,  resulting  in  all  remaining  argv  elements   being
              interpreted  as  mere  arguments. For example, when specifying initialize(’t’, ...)
              and calling

                  prog one -ttwo -c -- three

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

       o      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 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 &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, e.g., the program’s argv[1].

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  argv-like  set of pointers to all remaining arguments. Element nArgs() + 1
              is a 0-pointer. The first 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:

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

       bobcat(7)

BUGS

       None Reported.

BOBCAT PROJECT FILES

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

       o      bobcat_6.04.00-x.dsc: detached signature;

       o      bobcat_6.04.00-x.tar.gz: source archive;

       o      bobcat_6.04.00-x_i386.changes: change log;

       o      libbobcat1_6.04.00-x_*.deb: debian package containing the libraries;

       o      libbobcat1-dev_6.04.00-x_*.deb:  debian  package  containing the libraries, headers
              and manual pages;

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