PlasCom2  1.0
XPACC Multi-physics simluation application
ComLineObject Class Reference

Command line processing. More...

Detailed Description

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:

  • Type 0) A simple flag.
  • Type 1) May accept an option argument. An option argument is the command line token immediatly following the option token.
  • Type 2) Requires an option argument.
  • Type 3) Non-optional option. Application requires this option to function.

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.

Definition at line 62 of file ComLine.H.

#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 &notes)
 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)
 
Inheritance diagram for ComLineObject:
Collaboration diagram for ComLineObject:

Constructor & Destructor Documentation

◆ ComLineObject() [1/3]

ComLineObject ( )
inline

Default constructor.

Definition at line 102 of file ComLine.H.

Referenced by ComLineObject::ComLineObject().

Here is the caller graph for this function:

◆ ComLineObject() [2/3]

ComLineObject ( const char *  args[])
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().

Here is the call graph for this function:

◆ ComLineObject() [3/3]

Copy constructor.

Definition at line 123 of file ComLine.C.

References ComLineObject::Copy().

Here is the call graph for this function:

◆ ~ComLineObject()

virtual ~ComLineObject ( )
inlinevirtual

Definition at line 391 of file ComLine.H.

Member Function Documentation

◆ AddArgHelp()

void AddArgHelp ( const std::string &  a,
const std::string &  help 
)
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().

Here is the caller graph for this function:

◆ AddArgument()

void AddArgument ( const std::string &  a,
int  reqd = 0 
)
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().

Here is the caller graph for this function:

◆ AddHelp() [1/2]

void AddHelp ( char  s,
const std::string &  help 
)
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().

Here is the caller graph for this function:

◆ AddHelp() [2/2]

void AddHelp ( const std::string &  l,
const std::string &  help 
)
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().

Here is the call graph for this function:

◆ AddOption() [1/2]

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().

Here is the caller graph for this function:

◆ AddOption() [2/2]

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.

◆ Copy()

◆ ErrorReport()

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().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ GetArgs()

std::vector<std::string> GetArgs ( ) const
inline

Argument access.

Definition at line 314 of file ComLine.H.

References ComLineObject::_nonops.

Referenced by ix::DiffDataFiles(), and ix::profiler::Profane().

Here is the caller graph for this function:

◆ GetHelp() [1/2]

std::string GetHelp ( char  s)
inline

Obtain the usage string for an option.

Definition at line 248 of file ComLine.H.

◆ GetHelp() [2/2]

std::string GetHelp ( const std::string &  l)
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().

Here is the call graph for this function:

◆ GetLong()

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().

Here is the caller graph for this function:

◆ GetOpStringByType()

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().

Here is the caller graph for this function:

◆ GetOption() [1/2]

std::string GetOption ( const char &  s)
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().

Here is the caller graph for this function:

◆ GetOption() [2/2]

std::string GetOption ( const std::string &  l)
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().

Here is the call graph for this function:

◆ GetRawComLine()

std::string GetRawComLine ( ) const
inline

Raw Command Line Access.

Definition at line 134 of file ComLine.H.

References ComLineObject::AddOption(), ComLineObject::ProcessOptions(), ComLineObject::Record(), and ComLineObject::SetRawComLine().

Here is the call graph for this function:

◆ GetShort()

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().

Here is the caller graph for this function:

◆ Initialize()

virtual void Initialize ( void  )
inlinevirtual

virtual function for program specific Initialization.

Reimplemented in command_line, CheckResultsComLine, ProfaneComLine, program_command_line, TestComLine, TestComLine, DDFComLine, commandline, and RTSComLine.

Definition at line 385 of file ComLine.H.

◆ LongUsage()

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().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ ProcessCommandLine()

int ProcessCommandLine ( const char *  args[])
inline

One fell swoop processing of command line.

Definition at line 126 of file ComLine.H.

References ComLineObject::ProcessOptions(), and ComLineObject::Record().

Here is the call graph for this function:

◆ ProcessOptions()

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().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ ProcessRange()

void ProcessRange ( NumType &  t1,
NumType &  t2,
const std::string  stinter 
)
inline

Process a range in the format "t1:t2".

Definition at line 335 of file ComLine.H.

References x.

Referenced by ix::util::CheckResults().

Here is the caller graph for this function:

◆ ProgramName()

std::string ProgramName ( ) const
inline

Program name access.

Definition at line 310 of file ComLine.H.

References ComLineObject::_program_name.

Referenced by parallelprogram::Initialize(), and ix::profiler::Profane().

Here is the caller graph for this function:

◆ ReadRC()

void ReadRC ( const std::string &  RCString)

Read a config from RC string.

Definition at line 482 of file ComLine.C.

Referenced by ComLineObject::SetNotes().

Here is the caller graph for this function:

◆ Record()

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().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ ResolveOption()

void ResolveOption ( NumType &  t2,
const std::string  stinter 
)
inline

Resolve an option (i.e.

obtain it's "value").

Definition at line 367 of file ComLine.H.

◆ SetArgName() [1/2]

void SetArgName ( const std::string  opstr,
const std::string  argname 
)
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().

Here is the call graph for this function:

◆ SetArgName() [2/2]

void SetArgName ( char  s,
const std::string &  argname 
)
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 217 of file ComLine.H.

◆ SetDescription()

void SetDescription ( const std::string &  desc)
inline

Set description string.

Definition at line 318 of file ComLine.H.

Referenced by commandline::Initialize(), and commandline::InitializeDefaults().

Here is the caller graph for this function:

◆ SetNotes()

void SetNotes ( const std::string &  notes)
inline

Set notes string.

Definition at line 322 of file ComLine.H.

References ComLineObject::ReadRC(), and ComLineObject::WriteRC().

Referenced by commandline::Initialize().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ SetRawComLine()

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().

Here is the caller graph for this function:

◆ ShortUsage()

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().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ UserInitialize()

virtual void UserInitialize ( void  )
inlinevirtual

virtual function for program specific Initialization.

Definition at line 389 of file ComLine.H.

◆ WriteRC()

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().

Here is the caller graph for this function:

Friends And Related Function Documentation

◆ operator<<

std::ostream& operator<< ( std::ostream &  Out,
const ComLineObject cl 
)
friend

Definition at line 86 of file ComLine.C.

◆ operator>>

std::istream& operator>> ( std::istream &  In,
ComLineObject cl 
)
friend

Definition at line 14 of file ComLine.C.

Member Data Documentation

◆ _arghelp

std::map<std::string,std::string> _arghelp
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>>().

◆ _argname

std::map<char,std::string> _argname
protected

◆ _args

std::vector<std::pair<std::string,int> > _args
protected

◆ _description

std::string _description
protected

◆ _error_messages

std::vector<std::string> _error_messages
protected

stores error messages

Definition at line 81 of file ComLine.H.

Referenced by ComLineObject::Copy(), ComLineObject::ErrorReport(), ix::util::operator>>(), and ComLineObject::ProcessOptions().

◆ _help

std::map<char,std::string> _help
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>>().

◆ _line

std::string _line
protected

unformatted command line

Definition at line 79 of file ComLine.H.

Referenced by ComLineObject::Copy(), ComLineObject::Record(), and ComLineObject::SetRawComLine().

◆ _nonops

std::vector<std::string> _nonops
protected

stores non-option arguments

Definition at line 83 of file ComLine.H.

Referenced by ComLineObject::Copy(), ComLineObject::GetArgs(), and ComLineObject::ProcessOptions().

◆ _notes

std::string _notes
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().

◆ _options

std::map<char,std::string> _options
protected

stores the value of each option

Definition at line 85 of file ComLine.H.

Referenced by ComLineObject::AddOption(), ComLineObject::Copy(), and ComLineObject::ProcessOptions().

◆ _program_name

std::string _program_name
protected

◆ _toks

std::vector<std::string> _toks
protected

commandline tokens

Definition at line 97 of file ComLine.H.

Referenced by ComLineObject::ProcessOptions(), and ComLineObject::Record().

◆ _type


The documentation for this class was generated from the following files: