Main Page   Class Hierarchy   Compound List   File List   Compound Members  

commandoptions Class Reference

A class for parsing command line options. More...

#include <commandoptions.h>

List of all members.

Public Methods

template<typename T> void register_option (T &par, std::string long_name, char short_name, std::string des, std::string arg_name)
 Register an option with a reference to a variable. More...

void register_flag (bool &par, std::string long_name, char short_name, std::string des)
 Register a flag with a reference to a bool variable. More...

template<typename T> void register_argument (T &par, std::string name, std::string des)
 Register a mandatory argument with a reference to a variable. More...

void process_command_line (int argc, const char *argv[])
 Process the arguments, options, and flags on the command line. More...

 ~commandoptions ()
 Cleans dynamically allocated stuff up.


Detailed Description

A class for parsing command line options.

By using this class, you wont have to redo the tedious task of making a command line parser every time you need one.

The command line is parsed and checked for errors. An exception will be thrown in any of these circumstances:

Here is a little program that demonstrates the use of commandoptions:

We start by including the standard IO stream library (which is needed by our program and not by commandoptions ) and the commandoptions header:

    #include <iostream>
    #include "commandoptions"
We can now start our main function and decleare our commandoptions object:
    int main(int argc, const char *argv[]) {
      commandoptions c;
Our little program has a number of variables that the user can control. These variables are declared next:
      bool beep = false;
      int no_of_hits = 3;
      std::string boink_sound = "*boink*";
      std::string ouch_sound = "*ouch*";
      std::string victim;
Now that the variables have been declared and initialised, we can register them with our commandoptions object:
      c.register_flag(beep, "beep", 'b', "Turn on beeping");
      c.register_option(no_of_hits, "hits", 'h', "How many times to hit victim", "NUMBER");
      c.register_option(boink_sound, "", 's', "How hitting victim sounds", "SOUND");
      c.register_option(ouch_sound, "help-cry", '\0', "Victim response", "SOUND");
      c.register_argument(victim, "victim", "");
We can now try to parse the command line. Since this might fail, we use a try block:
      try {
        c.process_command_line(argc, argv);
If the parsing fails, a commandoptions_error object will be thrown, and we will end up in the catch block. The error-object has a commandoptions_error::what method that we use to get an explaination of the error:
      } catch (commandoptions_error &ex) {
        std::cerr << "Error: " << ex.what() << endl;
The program should now terminate with a non-zero exitcode to indicate that an error has occured:
        return 1;
      }
If everything went well, then we can start using the variables we declared previously. They will be updated to reflect the arguments given by the user on the command line. The rest of the code is:
      if (no_of_hits > 0) {
        std::cout << "Now hitting " << victim << ' '
                  << no_of_hits << " times:" << std::endl;
        for (int i = 0; i < no_of_hits; ++i)
          std::cout << boink_sound << ' ' << ouch_sound << std::endl;
      }
      if (beep)
        std::cout << "*beep*" << std::endl;
    }


Member Function Documentation

void commandoptions::process_command_line int    argc,
const char *    argv[]
 

Process the arguments, options, and flags on the command line.

You should call this method after you have registered your arguments, options, and flags with the object.

See also:
register_argument, register_option, and register_flag.

template<typename T>
void commandoptions::register_argument T &    par,
std::string    name,
std::string    des
[inline]
 

Register a mandatory argument with a reference to a variable.

The variable will be updated with the value found on the command line.

Parameters:
par  the variable to update. The variable is tied to the flag, and it will be updated when process_command_line is called. This is done with the help of >> which means that you can make your program accept a vector as an argument, if you have implemented the operator>> method in your vectorclass.
des  the description of the argument. The description will be part of the help displayed when the program in invoed with the --help option. It will be placed after the long and short name, so it should be no longer than one line.

void commandoptions::register_flag bool &    par,
std::string    long_name,
char    short_name,
std::string    des
[inline]
 

Register a flag with a reference to a bool variable.

The variable will be inverted if the flag is found on the command line. This means that you should give the variable a suitable default value before you call process_command_line. If the flag is present more than one time on the command line, it will be parsed as if only occured once.

Parameters:
par  the variable to update. The variable is tied to the flag, and it will be updated when process_command_line is called.
long_name  the long name of the flag. The user can then toggle the flag by invoking the program with --long_name. The long name will be part of the help displayed when the user invokes the program with --help as an option.
short_name  the short name for the flag. This is a single char. The user can then toggle the flag by invoking the program with -short_name. The short name will be part of the help displayed when the program is invoked with the --help option.
des  the description of the flag. The description will be part of the help displayed when the program in invoed with the --help option. It will be placed after the long and short name, so it should be no longer than one line.

template<typename T>
void commandoptions::register_option T &    par,
std::string    long_name,
char    short_name,
std::string    des,
std::string    arg_name
[inline]
 

Register an option with a reference to a variable.

The variable will be updated with the argument on the command line.

Parameters:
par  the variable to update. The variable is tied to the option, and it will be updated when process_command_line is called.
long_name  the long name of the option. The user can then enable the option by invoking the program with --long_name. The long name will be part of the help displayed when the user invokes the program with --help as an option.
short_name  the short name for the option. This is a single char. The user can then enable the option by invoking the program with -short_name. The short name will be part of the help displayed when the program is invoked with the --help option.
des  the description of the option. The description will be part of the help displayed when the program in invoed with the --help option. It will be placed after the long and short name, so it should be no longer than one line.
arg_name  the name of the option. This will be part of the help displayed when the program is invoked with the -h or -? options.


The documentation for this class was generated from the following files:
Generated on Wed Jan 23 17:53:15 2002 for rubik by doxygen1.2.12 written by Dimitri van Heesch, © 1997-2001