4.4. CmdLineOpts class

4.4.1. DEFINITION

#include <assa/CmdLineOpts.h>

class Option {
public:
    friend class CmdLineOpts; 

    enum type_t { string_t=0, int_t, uint_t, long_t, ulong_t, 
	          double_t, float_t, flag_t, func_t, 
                  func_one_t, none_t };
};

public CmdLineOpts
{
public:
    typedef void (* OPTS_FUNC) (void);
    typedef void (* OPTS_FUNC_ONE) (const string&);

    CmdLineOpts ();

    bool add_flag_opt (const char c, const string& s, bool* f);

    bool add_opt (const char c, const string& s, string* str);
    bool add_opt (const char c, const string& s, int* i);
    bool add_opt (const char c, const string& s, unsigned int* ui);
    bool add_opt (const char c, const string& s, long* l);
    bool add_opt (const char c, const string& s, unsigned long* ul);
    bool add_opt (const char c, const string& s, double* d);
    bool add_opt (const char c, const string& s, float* f);
    bool add_opt (const char c, const string& s, OPTS_FUNC);
    bool add_opt (const char c, const string& s, OPTS_FUNC_ONE);

    bool rm_opt (const char, const string&);

    bool parse_args (const char* argv[]);
    const char* get_opt_error () const;

    static void str_to_argv (const string& src_, 
                             int& argc_, char**& argv_);

    static void free_argv (char**& argv_);

    void dump () const;

protected:
    virtual void pos_arg (const char* arg_);
};
	  

4.4.2. USAGE

CmdLineOpts processes both short and long options.

A short option consists of a '-' character followed by a single case sensitive alphanumeric character.

A long option consists of two dashes, '--', followed by a string made up of letters, numbers, and hyphens.

Either type of option may be followed by an argument. A space or an equal sign, '=', separates a long option from an argument. Short option may or may not be separated by a space from its argument.

If an option is not allowed to have an argument, here it is denoted as a binary flag. Binary flags could be combined together in one command line option.

For example:

shell>  clops -m               // short binary flag option
shell>  clops -p               // another short binary flag option
shell>  clops -mp              // two binary flags combined in one option
shell>  clops --memory-usage   // long binary flag option
shell>  clops -d 5             // short option with an argument
shell>  clops -d5              // short option with an argument, not separated by the space.
shell>  clops --debug-level 5  // long option with an argument
shell>  clops --debug-level=5  // equivalent to above
	  

At last, the list of positional arguments might follow.

shell>  clops --memory-usage -d 5 test_file
	  

Here, --memory-usage is a binary flag and its value will be changed to the opposite of what it was initialized to prior to calling parse_args(), -d 5 is a short option with argument 5, and test_file is the first positional argument.

To add an option, use one of the add_opt () member functions:

bool add_opt (const char c, const string& s, string* str);
bool add_opt (const char c, const string& s, int* i);
bool add_opt (const char c, const string& s, unsigned int* ui);
bool add_opt (const char c, const string& s, long* l);
bool add_opt (const char c, const string& s, unsigned long* ul);
bool add_opt (const char c, const string& s double* d);
bool add_opt (const char c, const string& s float* f);
	  

The first argument is the short option name, the second is the long option name, and the third argument is the pointer to a variable that will hold the argument value. The variable itself most likely to be a data member of a class derived from CmdLineOpts.

For example:

class MyOptions : public CmdLineOpts
{
     MyOptions ();
     u_int debug_level;
};

MyOptions::
MyOptions ()
{
     if (!f.add_opt ('d', "debug-level", &debug_level)) {
          cerr << "Error : " << f.get_opt_error ();
          exit (1);
     }
}

int main (int argc, char* argv[])
{
     MyOptions myopt;

     if (!myopt.parse_args (argv)) {
          cerr << "Error parsing arguments"
	           << myopt.get_opt_error ();
          return (1);
     }
}
	  

Adding binary flag option is different from the rest due to the fact that early C++ compilers didn't have bool defined as a C++ keyword. To add binary flag option, use following function.

		
bool add_flag_opt (const char c, const string& s, bool* b);
	  

Besides int, u_int, long, u_long, double, float, string and bool data types, add_opt() accepts void static function with no arguments and void static function with an argument of STL string reference.

typedef void (* OPTS_FUNC) (void);
typedef void (* OPTS_FUNC_ONE) (const string& s);
	  

If set this way, function with no arguments will be called when corresponding binary flag option has being parsed. And the function with one argument will be called when the associative option with argument has been parsed, passing the value as the argument.

An option can be deleted from option set with call to

bool rm_opt (const char c, const string& s);
	  

It is used if, for example, derived class doesn't support certain default options.

It is not necessary to define both short and long option names. Either one will do, though, defining both is more appropriate for the sake of completeness.

To process command line arguments, member function parse_args() is used.

bool parse_args (const char* argv[]);
	  

The argument is the argv pointer to the array of char pointers of main(). The argument is not modified in any way or shape. If parsing was not successful, the function will return false, and descriptive error message can be obtained with get_opt_error() member function.

Upon encounter and parsing of each positional parameter, the pos_arg() callback function is called with the argument the position parameter parsed. In order to effectively use it, overload this member function.

virtual void pos_arg (const char* arg_);
	  

// USAGE: MyServer <ping_timeout> <data_file>

class MyServer : public GenServer
{
    // Positional arguments
    //
    string   m_data_file_name;
    double   m_ping_timeout;

    unsigned short m_pos_args_count; 

public:
    MyServer () : m_data_file_name (strenv(DEFAULT_MSNAME)),
                   m_ping_timeout(0),
                   m_pos_args_count(0) 
    { /* empty */ }

private:
    virtual void pos_arg (const char* arg_);
};

// Processing positional arguments

void
MyServer::
pos_arg (const char* arg_)
{
    switch (m_pos_arg_count) {
        case 0: 
            errno = 0;
            m_flush_timeout = strtod (arg_, NULL);
            Assert_exit (errno == 0);
            m_pos_arg_count++;
            break;

        case 1:
            m_data_file_name = arg_;
            m_pos_arg_count++;
            break;
   
        default:
            cerr << "Unexpected number of arguments!\n";
            stopServer();
    }
}
		

A static function str_to_argv() creates argv-like array of pointers to options from STL string.

void str_to_argv (char**& argv_);
	  

The memory is allocated on a heap, and must be freed with free_argv() member function call, or manually by traversing the dynamic array of char* pointers returned by the call to the function. It's prototype is:

void free_argv (char**& argv_);
	  

Please, see the glops_test.cpp for a detailed usage example.