Command line processing. More...
Command line processing.
Provides a quick and easy way to deal with the arguments coming into an application from the command line. Several useful methods for parsing the command line tokens and generation of detailed usage information are provided for the application.
Command line tokens are separated into three kinds. The zeroth kind is the first command line token which is the name of the program as it was invoked on the command line. This token is stripped of any absolute path information and stored. The first kind are options. Any command line token which begins with a "-" is interpreted as an option. There are several types of options:
Option usage is summarized by the following table.
Type | Description | Usage | Value |
---|---|---|---|
0 | simple flag | -t | .true. |
1 | argument optional | -t or -t [arg] | .true. or [arg] |
2 | argument required | -t <arg> | <arg> |
3 | required w/arg | -t <arg> | <arg> |
The second kind of command line tokens are arguments to the application. These kind of tokens are simply all the tokens not used up in the processing of the zeroth and first kinds of command line tokens. A mechanism for specifying whether these kind of tokens are required or optional is also provided.
#include <ComLine.H>
Public Member Functions | |
ComLineObject () | |
Default constructor. More... | |
ComLineObject (const char *args[]) | |
Constructor. More... | |
ComLineObject (ComLineObject &incom) | |
Copy constructor. More... | |
void | Copy (ComLineObject &incom) |
Copy method. More... | |
int | ProcessCommandLine (const char *args[]) |
One fell swoop processing of command line. More... | |
std::string | GetRawComLine () const |
Raw Command Line Access. More... | |
void | SetRawComLine (const std::string &incl) |
Raw Command Line Access. More... | |
int | ProcessOptions () |
Processes all command line tokens. More... | |
void | Record (const char *args[]) |
Minimal recording of command line. More... | |
void | AddOption (char s, const std::string &l, int=0) |
User interface to describe simple option. More... | |
void | AddOption (char s, const std::string &l, int, const std::string argname) |
User interface to describe option with argument. More... | |
void | AddArgument (const std::string &a, int reqd=0) |
User interface to describe an application argument. More... | |
void | AddArgHelp (const std::string &a, const std::string &help) |
Specify the usage info for application argument. More... | |
void | SetArgName (const std::string opstr, const std::string argname) |
Specify name of an option argument. More... | |
void | SetArgName (char s, const std::string &argname) |
Specify name of an option argument. More... | |
void | AddHelp (char s, const std::string &help) |
Specify usage for an option. More... | |
void | AddHelp (const std::string &l, const std::string &help) |
Specify usage for an option. More... | |
std::string | GetOpStringByType (int mintype, int maxtype) |
Obtains option strings by type. More... | |
std::string | GetHelp (char s) |
Obtain the usage string for an option. More... | |
std::string | GetHelp (const std::string &l) |
Obtain the usage string for an option. More... | |
char | GetShort (const std::string &l) |
Obtain the short one char option from the long word version. More... | |
std::string | GetLong (const char &s) |
Obtain the long word option from the short char version. More... | |
std::string | ShortUsage () |
Generate short usage string. More... | |
std::string | LongUsage () |
Generate long usage string. More... | |
std::string | GetOption (const char &s) |
Get the value of an option. More... | |
std::string | GetOption (const std::string &l) |
Get the value of an option. More... | |
std::string | ErrorReport () |
Error reporting. More... | |
std::string | ProgramName () const |
Program name access. More... | |
std::vector< std::string > | GetArgs () const |
Argument access. More... | |
void | SetDescription (const std::string &desc) |
Set description string. More... | |
void | SetNotes (const std::string ¬es) |
Set notes string. More... | |
void | WriteRC (std::ostream &Ostr) const |
Write an RC string that can be used for config. More... | |
void | ReadRC (const std::string &RCString) |
Read a config from RC string. More... | |
template<typename NumType > | |
void | ProcessRange (NumType &t1, NumType &t2, const std::string stinter) |
Process a range in the format "t1:t2". More... | |
template<typename NumType > | |
void | ResolveOption (NumType &t2, const std::string stinter) |
Resolve an option (i.e. More... | |
virtual void | Initialize (void) |
virtual function for program specific Initialization. More... | |
virtual void | UserInitialize (void) |
virtual function for program specific Initialization. More... | |
virtual | ~ComLineObject () |
Protected Attributes | |
std::string | _description |
application description. More... | |
std::string | _notes |
Notes to be displayed at the end of LongUsage(). More... | |
std::string | _program_name |
the name of the program More... | |
std::string | _line |
unformatted command line More... | |
std::vector< std::string > | _error_messages |
stores error messages More... | |
std::vector< std::string > | _nonops |
stores non-option arguments More... | |
std::map< char, std::string > | _options |
stores the value of each option More... | |
std::map< char, std::string > | _help |
stores the help string for each op More... | |
std::map< char, std::string > | _argname |
stores a name for arguments More... | |
std::map< char, int > | _type |
stores the type of option More... | |
std::vector< std::pair< std::string, int > > | _args |
application arguments; More... | |
std::map< std::string, std::string > | _arghelp |
help string for args More... | |
std::vector< std::string > | _toks |
commandline tokens More... | |
Friends | |
std::ostream & | operator<< (std::ostream &Out, const ComLineObject &cl) |
std::istream & | operator>> (std::istream &In, ComLineObject &cl) |
|
inline |
Default constructor.
Definition at line 102 of file ComLine.H.
Referenced by ComLineObject::ComLineObject().
|
inline |
Constructor.
Typically, args comes directly from argv. One must be careful about environments in which extra arguments are stored in argv. A good example is MPI. MPI_Init(&argc,&argv) should be invoked before any ComLineObject is constructed.
Definition at line 111 of file ComLine.H.
References ComLineObject::ComLineObject(), ComLineObject::Copy(), and ComLineObject::Record().
ComLineObject | ( | ComLineObject & | incom | ) |
Copy constructor.
Definition at line 123 of file ComLine.C.
References ComLineObject::Copy().
|
inlinevirtual |
|
inline |
Specify the usage info for application argument.
This function is provided for the specification of the usage information for application arguments. This is called after the argument has been set by AddArgument(...). The string specified in "help" string is displayed in the output of LongUsage().
Definition at line 197 of file ComLine.H.
References a.
Referenced by DDFComLine::Initialize(), commandline::Initialize(), TestComLine::Initialize(), and ProfaneComLine::Initialize().
|
inline |
User interface to describe an application argument.
This function is provided for the specification of an argument to the application (i.e. a non-option argument), and whether the argument is required for the application to function. The function arguments are the name of the argument, and an integer which is > 0 for required application arguments.
Definition at line 183 of file ComLine.H.
Referenced by DDFComLine::Initialize(), commandline::Initialize(), TestComLine::Initialize(), and ProfaneComLine::Initialize().
|
inline |
Specify usage for an option.
Function is used to set the usage string for an option which is displayed in the output of LongUsage().
Definition at line 227 of file ComLine.H.
Referenced by RTSComLine::Initialize(), DDFComLine::Initialize(), commandline::Initialize(), TestComLine::Initialize(), program_command_line::Initialize(), ProfaneComLine::Initialize(), CheckResultsComLine::Initialize(), and commandline::InitializeDefaults().
|
inline |
Specify usage for an option.
Function is used to set the usage string for an option which is displayed in the output of LongUsage().
Definition at line 234 of file ComLine.H.
References ComLineObject::GetOpStringByType(), and ComLineObject::GetShort().
void AddOption | ( | char | s, |
const std::string & | l, | ||
int | atype = 0 |
||
) |
User interface to describe simple option.
This function is provided for the specification of a simple option. The arguments are the short, single letter option, the long "word" version, and the type of the option. If the option is of the type which may have or requires an argument itself, then the argument will be given the default name, "arg".
Definition at line 295 of file ComLine.C.
References ComLineObject::_argname, ComLineObject::_help, ComLineObject::_options, and ComLineObject::_type.
Referenced by ComLineObject::GetRawComLine(), RTSComLine::Initialize(), commandline::Initialize(), DDFComLine::Initialize(), TestComLine::Initialize(), program_command_line::Initialize(), ProfaneComLine::Initialize(), CheckResultsComLine::Initialize(), and commandline::InitializeDefaults().
void AddOption | ( | char | s, |
const std::string & | l, | ||
int | type, | ||
const std::string | argname | ||
) |
User interface to describe option with argument.
This function is provided for the specification of an option along with a name for it's argument. Argument names are useful for the generation of usage information to the user. The arguments are the short, single letter option, the long "word" version, the type, and the argument name.
Definition at line 306 of file ComLine.C.
References ComLineObject::_argname, ComLineObject::_help, ComLineObject::_options, and ComLineObject::_type.
void Copy | ( | ComLineObject & | incom | ) |
Copy method.
Definition at line 128 of file ComLine.C.
References ComLineObject::_arghelp, ComLineObject::_argname, ComLineObject::_args, ComLineObject::_description, ComLineObject::_error_messages, ComLineObject::_help, ComLineObject::_line, ComLineObject::_nonops, ComLineObject::_notes, ComLineObject::_options, ComLineObject::_program_name, and ComLineObject::_type.
Referenced by ComLineObject::ComLineObject().
std::string ErrorReport | ( | ) |
Error reporting.
Returns a report of the errors encountered in the ProcessOptions() function.
Definition at line 473 of file ComLine.C.
References ComLineObject::_error_messages, ComLineObject::_program_name, and ix::util::DumpContents().
Referenced by ix::DiffDataFiles(), ComLineObject::GetOption(), serialprogram::Initialize(), program< TestObjectType >::Initialize(), parallelprogram::Initialize(), plascom2::ParallelTest(), ix::profiler::Profane(), ix::RunTest(), and plascom2::Test().
|
inline |
Argument access.
Definition at line 314 of file ComLine.H.
References ComLineObject::_nonops.
Referenced by ix::DiffDataFiles(), and ix::profiler::Profane().
|
inline |
|
inline |
Obtain the usage string for an option.
Definition at line 252 of file ComLine.H.
References ComLineObject::GetLong(), ComLineObject::GetShort(), ComLineObject::LongUsage(), and ComLineObject::ShortUsage().
std::string GetLong | ( | const char & | s | ) |
Obtain the long word option from the short char version.
Definition at line 221 of file ComLine.C.
Referenced by ComLineObject::GetHelp(), and ComLineObject::ProcessOptions().
std::string GetOpStringByType | ( | int | mintype, |
int | maxtype | ||
) |
Obtains option strings by type.
Internal utility function for building a string of option characters which are of a certain type.
Definition at line 232 of file ComLine.C.
References ComLineObject::_type.
Referenced by ComLineObject::AddHelp(), and ComLineObject::ShortUsage().
|
inline |
Get the value of an option.
Returns the value of the specified option. If the option has not been set on the command line, then the value will be an empty string.
Definition at line 291 of file ComLine.H.
Referenced by ix::util::CheckResults(), ix::DiffDataFiles(), serialprogram::Initialize(), program< TestObjectType >::Initialize(), parallelprogram::Initialize(), plascom2::ParallelTest(), ComLineObject::ProcessOptions(), ix::profiler::Profane(), ix::RunTest(), and plascom2::Test().
|
inline |
Get the value of an option.
Returns the value of the specified option. If the option has not been set on the command line, then the value will be an empty string.
Definition at line 299 of file ComLine.H.
References ComLineObject::ErrorReport(), and ComLineObject::GetShort().
|
inline |
Raw Command Line Access.
Definition at line 134 of file ComLine.H.
References ComLineObject::AddOption(), ComLineObject::ProcessOptions(), ComLineObject::Record(), and ComLineObject::SetRawComLine().
char GetShort | ( | const std::string & | l | ) |
Obtain the short one char option from the long word version.
Definition at line 284 of file ComLine.C.
Referenced by ComLineObject::AddHelp(), ComLineObject::GetHelp(), ComLineObject::GetOption(), ComLineObject::ProcessOptions(), and ComLineObject::SetArgName().
|
inlinevirtual |
virtual function for program specific Initialization.
Reimplemented in command_line, CheckResultsComLine, ProfaneComLine, program_command_line, TestComLine, TestComLine, DDFComLine, commandline, and RTSComLine.
std::string LongUsage | ( | ) |
Generate long usage string.
Generates a long usage string similar to what one would see in the typical UNIX man-like description. Each option is shown with it's short and long version, along with usage information for each option and argument if such information has been specified with AddHelp, or AddArgHelp, respectively. Note that the format of this usage string follows the convention that optional quantities are enclosed in []'s while required quantities are enclosed in <>'s.
Definition at line 188 of file ComLine.C.
References ComLineObject::_arghelp, ComLineObject::_argname, ComLineObject::_args, ComLineObject::_description, ComLineObject::_help, ComLineObject::_notes, ComLineObject::_type, and ComLineObject::ShortUsage().
Referenced by ix::util::CheckResults(), ix::DiffDataFiles(), ComLineObject::GetHelp(), serialprogram::Initialize(), program< TestObjectType >::Initialize(), parallelprogram::Initialize(), plascom2::ParallelTest(), ix::profiler::Profane(), ix::RunTest(), and plascom2::Test().
|
inline |
One fell swoop processing of command line.
Definition at line 126 of file ComLine.H.
References ComLineObject::ProcessOptions(), and ComLineObject::Record().
int ProcessOptions | ( | ) |
Processes all command line tokens.
This function examines all the command line tokens, sorts them into their respective types, and assigns their values. The number of errors encountered during processing is returned.
Definition at line 330 of file ComLine.C.
References ComLineObject::_argname, ComLineObject::_args, ComLineObject::_error_messages, ComLineObject::_nonops, ComLineObject::_options, ComLineObject::_toks, ComLineObject::_type, ComLineObject::GetLong(), ComLineObject::GetOption(), and ComLineObject::GetShort().
Referenced by ix::util::CheckResults(), ix::DiffDataFiles(), ComLineObject::GetRawComLine(), plascom2::ParallelTest(), ComLineObject::ProcessCommandLine(), ix::profiler::Profane(), ix::RunTest(), and plascom2::Test().
|
inline |
Process a range in the format "t1:t2".
Definition at line 335 of file ComLine.H.
References x.
Referenced by ix::util::CheckResults().
|
inline |
Program name access.
Definition at line 310 of file ComLine.H.
References ComLineObject::_program_name.
Referenced by parallelprogram::Initialize(), and ix::profiler::Profane().
void ReadRC | ( | const std::string & | RCString | ) |
Read a config from RC string.
Definition at line 482 of file ComLine.C.
Referenced by ComLineObject::SetNotes().
void Record | ( | const char * | args[] | ) |
Minimal recording of command line.
This function simply parses the command line to extract the executble name and record the full command line in a string.
Definition at line 316 of file ComLine.C.
References ComLineObject::_line, ComLineObject::_program_name, ComLineObject::_toks, and ix::util::stripdirs().
Referenced by ComLineObject::ComLineObject(), ComLineObject::GetRawComLine(), and ComLineObject::ProcessCommandLine().
|
inline |
|
inline |
Specify name of an option argument.
Function is used to set the argument name for an option if the option can use an argument.
Definition at line 207 of file ComLine.H.
References ComLineObject::GetShort().
|
inline |
|
inline |
Set description string.
Definition at line 318 of file ComLine.H.
Referenced by commandline::Initialize(), and commandline::InitializeDefaults().
|
inline |
Set notes string.
Definition at line 322 of file ComLine.H.
References ComLineObject::ReadRC(), and ComLineObject::WriteRC().
Referenced by commandline::Initialize().
void SetRawComLine | ( | const std::string & | incl | ) |
Raw Command Line Access.
Definition at line 462 of file ComLine.C.
References ComLineObject::_line, and ComLineObject::_program_name.
Referenced by ComLineObject::GetRawComLine().
std::string ShortUsage | ( | ) |
Generate short usage string.
Generates a short usage string similar to what one would see in the typical short command line usage output for a UNIX command. Note that the format of this usage string follows the convention that optional quantities are enclosed in []'s while required quantities are enclosed in <>'s.
Definition at line 244 of file ComLine.C.
References ComLineObject::_argname, ComLineObject::_args, ComLineObject::_program_name, ComLineObject::_type, and ComLineObject::GetOpStringByType().
Referenced by ix::DiffDataFiles(), ComLineObject::GetHelp(), serialprogram::Initialize(), program< TestObjectType >::Initialize(), parallelprogram::Initialize(), ComLineObject::LongUsage(), plascom2::ParallelTest(), ix::profiler::Profane(), ix::RunTest(), and plascom2::Test().
|
inlinevirtual |
void WriteRC | ( | std::ostream & | Ostr | ) | const |
Write an RC string that can be used for config.
Definition at line 481 of file ComLine.C.
Referenced by ComLineObject::SetNotes().
|
friend |
|
friend |
|
protected |
help string for args
Definition at line 95 of file ComLine.H.
Referenced by ComLineObject::Copy(), ComLineObject::LongUsage(), ix::util::operator<<(), and ix::util::operator>>().
|
protected |
stores a name for arguments
Definition at line 89 of file ComLine.H.
Referenced by ComLineObject::AddOption(), ComLineObject::Copy(), ComLineObject::LongUsage(), ix::util::operator<<(), ix::util::operator>>(), ComLineObject::ProcessOptions(), and ComLineObject::ShortUsage().
|
protected |
application arguments;
Definition at line 93 of file ComLine.H.
Referenced by ComLineObject::Copy(), ComLineObject::LongUsage(), ix::util::operator<<(), ComLineObject::ProcessOptions(), and ComLineObject::ShortUsage().
|
protected |
application description.
This description will be dumped as the first section of the output of LongUsage().
Definition at line 73 of file ComLine.H.
Referenced by ComLineObject::Copy(), RTSComLine::Initialize(), DDFComLine::Initialize(), TestComLine::Initialize(), program_command_line::Initialize(), ProfaneComLine::Initialize(), CheckResultsComLine::Initialize(), ComLineObject::LongUsage(), ix::util::operator<<(), and ix::util::operator>>().
|
protected |
stores error messages
Definition at line 81 of file ComLine.H.
Referenced by ComLineObject::Copy(), ComLineObject::ErrorReport(), ix::util::operator>>(), and ComLineObject::ProcessOptions().
|
protected |
stores the help string for each op
Definition at line 87 of file ComLine.H.
Referenced by ComLineObject::AddOption(), ComLineObject::Copy(), ComLineObject::LongUsage(), ix::util::operator<<(), and ix::util::operator>>().
|
protected |
unformatted command line
Definition at line 79 of file ComLine.H.
Referenced by ComLineObject::Copy(), ComLineObject::Record(), and ComLineObject::SetRawComLine().
|
protected |
stores non-option arguments
Definition at line 83 of file ComLine.H.
Referenced by ComLineObject::Copy(), ComLineObject::GetArgs(), and ComLineObject::ProcessOptions().
|
protected |
Notes to be displayed at the end of LongUsage().
Definition at line 75 of file ComLine.H.
Referenced by ComLineObject::Copy(), and ComLineObject::LongUsage().
|
protected |
stores the value of each option
Definition at line 85 of file ComLine.H.
Referenced by ComLineObject::AddOption(), ComLineObject::Copy(), and ComLineObject::ProcessOptions().
|
protected |
the name of the program
Definition at line 77 of file ComLine.H.
Referenced by ComLineObject::Copy(), ComLineObject::ErrorReport(), ComLineObject::ProgramName(), ComLineObject::Record(), ComLineObject::SetRawComLine(), and ComLineObject::ShortUsage().
|
protected |
commandline tokens
Definition at line 97 of file ComLine.H.
Referenced by ComLineObject::ProcessOptions(), and ComLineObject::Record().
|
protected |
stores the type of option
Definition at line 91 of file ComLine.H.
Referenced by ComLineObject::AddOption(), ComLineObject::Copy(), ComLineObject::GetOpStringByType(), ComLineObject::LongUsage(), ix::util::operator<<(), ix::util::operator>>(), ComLineObject::ProcessOptions(), and ComLineObject::ShortUsage().