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:
- an unrecognizable option or flag was encountered.
- the argument to an option could not be parsed. This means that an exception is thrown, if the type of the argument doesn't match the type of the variable bound to the argument. This is determined by using the
<<
operator. - too many or too few arguments are given.
- several options are put into one group. The rule is, that there can only be one option per group, as each option requires an argument. If
-f
is an option that requires a filename (most likely a string
), and -n
also is an option, then the following command line will make commandoptions
throw an exception: $ my_program -fn filename
- an option is used without an argument.
- a single dash is found without a trailing character. Also, if two dashes are found without the name of a long option or long flag. This means that
commandoptions
currently doesn't follow the GNU style, which treats everything following two consecutive dashes arguments.
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: 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: 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: The program should now terminate with a non-zero exitcode to indicate that an error has occured: 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
1.2.12 written by Dimitri van Heesch,
© 1997-2001