arg.h File Reference

This file contains the definition of a class which can be used to parse the command line of a program and to set variables according to the command-line arguments. More...

#include <iostream>
#include <iomanip>
#include <cstring>
#include <sstream>
#include <cctype>
#include <ctime>

Classes
class	capd::auxil::argflags
	This is a helper class which defines specific flags indicating various types of command-line arguments and the state of interpreting them. More...
class	capd::auxil::argelement
	This is a helper class which defines common properties of a command-line argument bound with any type of a variable. More...
class	capd::auxil::argunit< type >
	This is a helper class which defines one command-line argument which is bound with some specific variable. It is an extension of the "argelement" class defined in terms of a template whose parameter is the type of the variable which is to be set based on the value provided in the command line. More...
class	capd::auxil::arguments
	The objects of this class gather the expected command-line arguments and decode them. It is recommended that you use the various functions called "arg" to enqueue the arguments into the list of arguments. When the list is complete, one just calls the "analyze" method of the class. Detailed instructions are gathered in the "arg.txt" file. The program "argtest.cpp" and most CHomP programs very well illustrate how to use various features of this class. More...

Namespaces
	capd
	capd::auxil

Functions
std::ostream &	capd::auxil::operator<< (std::ostream &out, const argelement &p)
template<class type >
int	capd::auxil::readfromstring (char *str, type &t)
	A template for reading a variable from a string. Returns 0 on success, -1 on failure. More...
int	capd::auxil::readfromstring (char *str, char *&t)
	A specialization of the above template for interpreting a string as a string (no processing is necessary). More...
int	capd::auxil::readfromstring (char *str, const char *&t)
	A specialization of the above template for interpreting a string as a const string (no processing is necessary). More...
int	capd::auxil::readfromstring (char *str, bool &t)
	A specialization of the above template for reading a bool type. More...
template<class type >
void	capd::auxil::arg (arguments &a, const char *name, type &value)
	Adds a command line argument. The actual argument name consists of the dash and its name provided to the function. If name == 0, then the value of this argument is read directly from the command line without any preceding string. The value variable is filled in by the value read from the command line string using the operator >>. More...
template<class type >
void	capd::auxil::arg (arguments &a, const char *name, type &value, type defaultvalue)
	Adds a command line argument with a default value. The name must be nonempty. If the name of the argument appears but its value is not specified, then the default value is used instead. More...
void	capd::auxil::arg (arguments &a, const char *name, char *&value, const char *defaultvalue)
	A specialization of the above for C-style strings. More...
template<class type >
void	capd::auxil::arg (arguments &a, const char *name, type *value, int &count, int size)
	Adds a command line argument whose repeated occurrences fill in consecutive elements of the given array. The counter indicates the position in the array. The given size of the array will not be exceeded. More...
template<class type >
void	capd::auxil::arg (arguments &a, const char *name, type *value, int &count, int size, type defaultvalue)
	A version of the above with a default value of the arguments. More...
template<class type >
void	capd::auxil::argoblig (arguments &arg, const char *name, type &value)
	Defines an obligatory command line argument. If this argument does not appear, then an error is displayed and error code is returned by the analysis procedure. More...
template<class type >
void	capd::auxil::argoblig (arguments &arg, const char *name, type &value, type defaultvalue)
	A version of the above with the default value provided. More...
void	capd::auxil::argoblig (arguments &arg, const char *name, char *&value, const char *defaultvalue)
	A version of the above for reading an array of argument values. More...
template<class type >
void	capd::auxil::argbreak (arguments &arg, const char *name, type &value)
	Adds an argument whose appearence interrupts the analysis of the command line and makes the analyzing function return the value of 1. This is useful for arguments whose appearence should make the program ignore all the remaining arguments, e.g., to display help information. More...
template<class type >
void	capd::auxil::argbreak (arguments &arg, const char *name, type &value, type defaultvalue)
	A version of the above with the default value provided. More...
void	capd::auxil::argbreak (arguments &arg, const char *name, char *&value, const char *defaultvalue)
	A version of the above for the C-style string. More...
void	capd::auxil::argbreak (arguments &arg, const char *name)
	A version of the above which ignores the value of the argument. More...
template<class type >
void	capd::auxil::argswitch (arguments &arg, const char *name, type &value, const type &defaultvalue)
	Defines a command line argument which is a switch, that is, there is no value given for it in the command line. The appearence of this argument sets the predefined default value to the given variable. More...
void	capd::auxil::argswitch (arguments &arg, const char *name, char *&value, const char *defaultvalue)
	A version of the above for the C-style string. More...
void	capd::auxil::argswitch (arguments &arg, const char *name)
	Defines an ignored switch (no value is set when this argument appears). More...
void	capd::auxil::arghelp (arguments &a)
	Adds the typical arguments which should make the program display help information. If help is requested, the command line analysis is interrupted, and the procedure returns the value 1. More...
std::string	capd::auxil::commandline (int argc, char *argv[])
	Returns the entire command line as a single string. More...
const char *	capd::auxil::currenttime (void)
	Retrieves the current time as a pointer to a C-style string. More...

Detailed Description

This file contains the definition of a class which can be used to parse the command line of a program and to set variables according to the command-line arguments.

The way of using the features defined in this header file is very simple and intuitive.

First, one must define in one's program an object of the type "arguments" which will collect and process the command line.

Then one should use some of the several functions "arg", "argswitch", and "arghelp" to bind various arguments with specific variables. For example, 'arg (argObject, "i", increase, 1);' makes the program react to the switch "-i" appearing in the command line and sets the value of the variable "increase" to what follows "-i", either without space, or after a space, but if no value is provided then the default value "1" is used.

At the end of arguments' definitions, it is recommended to use the function "arghelp (argObject);" to add the arguments typical for the user asking the program to display help information (like "--help"), but this step is not obligatory.

After all the arguments have been defined, one might also call the function "argstreamprepare (argObject);" (which is actually a macro) to set up some additional arguments related to the streams of the class "outputstream" defined in "chomp/system/textfile.h". In particular, this call adds the useful feature that if the user adds the argument "--log filename" to the command-line then all the output displayed to the screen (directed to "sout") is additionally logged to the given file.

Eventually, one should call the method "analyze" of the arguments object, e.g. "int argresult = argObject. analyze (argc, argv);", followed by another macro "argstreamset ();" which sets the streams defined with the macro "argstreamprepare".

The returned value "argresult" indicates what happened during the processing of the command line arguments: 0 means "all good", 1 means "help requested", and a negative value means "some error(s) occurred".

Author

Pawel Pilarczyk