Provided by: libbobcat-dev_4.08.02-2build1_amd64 bug

NAME

       FBB::ArgConfig - A singleton class processing program arguments

SYNOPSIS

       #include <bobcat/argconfig>
       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 as well as configuration files.

       In addition to the standard command-line  options,  configuration  files  containing  long
       options  as  their keys, optionally followed by a colon are also recognized by the various
       option members. E.g., an option --input filename can be  specified  in  the  configuration
       file like

       input: filename

       or

       input filename

       Options  without  arguments  should probably not use the colon, although it is accepted by
       ConfigArg. E.g., for the option --verbose both forms are OK:

       verbose
       verbose:

NAMESPACE

       FBB
       All constructors, members, operators and manipulators, mentioned  in  this  man-page,  are
       defined in the namespace FBB.

INHERITS FROM

       FBB::Arg,
       FBB::ConfigFile

CONSTRUCTORS

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

STATIC MEMBERS

       o      FBB::ArgConfig  &initialize(char  const  *optstring,   int   argc,   char   **argv,
              [std::string  const  &fname,]  Comment  cType  =  KeepComment, SearchCasing sType =
              SearchCaseSensitive, Indices iType = IgnoreIndices):
              Initializes the FBB::ArgConfig 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).  The  fname
              argument  is  optional.  If provided, a configuration file by the specified name is
              opened (and must exist); if omitted  the  ArgConfig  is  created  without  using  a
              configuration  file. In the latter case a configuration file may be specified later
              using the open member inherited from ConfigFile. The  final  three  parameters  are
              ConfigFile parameters, receiving the shown default values. This constructor returns
              a reference to the singleton object, allowing code initializing  ArgConfig  to  use
              the initialized object immediately.

       o      FBB::ArgConfig  &initialize(char  const *optstring, LongOption const * const begin,
              LongOption const * const end, int argc, char **argv,  [std::string  const  &fname,]
              Comment  cType  =  KeepComment,  SearchCasing  sType = SearchCaseSensitive, Indices
              iType = IgnoreIndices):
              Initializes the FBB::ArgConfig 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).  Refer to
              arg(3bobcat) for the description of Arg::LongOption.  The constructor’s  final  six
              parameters  are  identical  to the previous constructor’s final six arguments. This
              constructor returns a reference to the singleton object, allowing code initializing
              ArgConfig to use the initialized object immediately.

              The argument optstring should consist of letters, possibly postfixed by:

       o      a colon (:), indicating that the option has a required argument;

       o      a double colon (::), indicating that the option itself has an optional argument (in
              that case, the option’s value will be empty, unless specified).

       o      FBB::ArgConfig &instance():
              Returns the instance of the ArgConfig object, available after calling  one  of  the
              ArgConfig::initialize  members.  If called before initialization, an FBB::Exception
              exception is thrown.

NON-STATIC MEMBER FUNCTIONS

       All public members of the Arg and ConfigFile classes are also  offered  by  the  ArgConfig
       class.  As several  option members were reimplemented by this class all option members are
       discussed below. All other members inherit straight from the classes Arg  and  ConfigFile.
       Consult their man pages for details.

       o      size_t option(int option) const:
              Returns  the  number of times `option’ (or its long option synonym, if defined) was
              specified as command line option or as as a configuration file option.

       o      size_t option(std::string const &options) const:
              Returns the total number of times any of the characters specified in the  `options’
              string  (or  their long option synonyms) was specified as command line option or as
              as a configuration file 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  as  either a command line option or as a configuration file option. If the
              return value is non-zero then the value of the  first  occurrence  of  this  option
              (first  checking the command line options; then checking the configuration file) 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:
              This member acts  identically  to  the  Arg::option  member  having  the  identical
              prototype.  It  does  not  consider  the  configuration file but merely 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:
              This  member  acts  identically  to  the  Arg::option  member  having the identical
              prototype. It does not consider the  configuration  file  but  merely  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  as either a command line option or in the
              configuration file. If found, then the value found at the first occurrence  of  the
              option (first considering the command line options, then the configuration file) is
              stored in *value. The string pointed to by value 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:
              This member acts  identically  to  the  Arg::option  member  having  the  identical
              prototype.  It  does  not  consider  the  configuration file but merely 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:
              This  member  acts  identically  to  the  Arg::option  member  having the identical
              prototype. It does not consider the  configuration  file  but  merely  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.

EXAMPLE

       #include <iostream>
       #include <string>

       #include <bobcat/argconfig>
       #include <bobcat/exception>

       using namespace std;
       using namespace FBB;

       ArgConfig::LongOption lo[] =
       {
           ArgConfig::LongOption{"option", ’o’},
           ArgConfig::LongOption{"value-option", ’v’}
       };

       class X
       {
           ArgConfig &d_arg;

           public:
               X();
               void function();
       };

       X::X()
       :
           d_arg(ArgConfig::instance())
       {}

       void X::function()
       {
           if (d_arg.nArgs() == 0)
               throw Exception() << "Provide the name of a config file as 1st arg";

           cout << "Counting " << d_arg.option(’o’) << " instances of -o or "
                                                                   "--option\n";

           d_arg.open(d_arg[0]);       // Now open the config file explicitly
                                   // (alternatively: use a constructor expecting
                                   // a file name)

           cout << "Counting " << d_arg.option(’o’) << " instances of -o or "
                                                                   "--option\n";

           string optval;
           size_t count = d_arg.option(&optval, ’v’);

           cout << "Counting " << count <<
                               " instances of -v or --value-option\n";
           if (count)
               cout << "Option value = " << optval << endl;
       }

       int main(int argc, char **argv)
       try
       {
           ArgConfig::initialize("ov:", lo, lo + 2, argc, argv);

           X x;
           x.function();

           return 0;
       }
       catch (Exception const &err)
       {
           cout << "Terminating " << err.what() << endl;
           return 1;
       }

FILES

       bobcat/argconfig - defines the class interface

SEE ALSO

       arg(3bobcat), configfile(3obcat), 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).