FBB::ArgConfig(3bobcat)

Program Arguments
(libbobcat-dev_6.04.00)

2005-2023

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_long()(3). The class handles short- and long command-line options, as well as configuration files.

In addition to the standard command-line options the various option members also recognize long options as keys, optionally followed by a colon and an option value are also recognized. 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 accepted:

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

ENUMERATION

The FBB::ArgConfig::Type enumeration is inherited from the FBB::Arg class. It is used to specify whether or not long options require arguments. It defines the following values: None, Required, Optional.

These values are used when defining long options (like --version), which are defined as objects of the (nested inherited) class FBB::Arg::LongOption (in the context of ArgConfig this is identical to FBB::ArgConfig::LongOption.

THE NESTED INHERITED CLASS FBB::Arg::LongOption

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

To define long options use the following procedure:

Objects of the class LongOptions are normally used internally by the ArgConfig object, but they can also be used outside of the ArgConfig object. For that situation the following members are available:

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.

STATIC MEMBERS

All initialize members initialize the FBB::ArgConfig singleton, and can only be called once. An exception is thrown when called multiple times. All initialize members return a reference to the initialized ArgConfig 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.

  • 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 supported by the ArgConfig class. As several Arg::option members were reimplemented by ArgConfig all option members are discussed below. All other members inherit straight from the classes Arg and ConfigFile. Consult their man pages for details.

    When using the option members that don't consider configuration files use the beginEndRE member (cf. configfile(3obcat)) to retrieve long options that are specified in configuration files.

    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();
    }
    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.

    BOBCAT PROJECT FILES

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