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 411 of file AppTools.H.

#include <AppTools.H>

Public Member Functions
	comlinehandler ()
	Default constructor. More...

	comlinehandler (const char *args[])
	Constructor. More...

	comlinehandler (comlinehandler &incom)
	Copy constructor. More...

void	Copy (comlinehandler &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	~comlinehandler ()

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 comlinehandler &cl)

std::istream &	operator>> (std::istream &In, comlinehandler &cl)

Inheritance diagram for comlinehandler:

[legend]

Collaboration diagram for comlinehandler:

[legend]

Constructor & Destructor Documentation

◆ comlinehandler() [1/3]

comlinehandler ( )

inline

Default constructor.

Definition at line 451 of file AppTools.H.

◆ comlinehandler() [2/3]

comlinehandler ( 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 comlinehandler is constructed.

Definition at line 460 of file AppTools.H.

◆ comlinehandler() [3/3]

comlinehandler ( comlinehandler & incom )

Copy constructor.

Definition at line 853 of file AppTools.H.

◆ ~comlinehandler()

virtual ~comlinehandler ( )

inlinevirtual

Definition at line 740 of file AppTools.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 546 of file AppTools.H.

References a.

Referenced by SetupOptions().

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 532 of file AppTools.H.

Referenced by SetupOptions().

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 576 of file AppTools.H.

Referenced by SetupOptions().

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 583 of file AppTools.H.

◆ 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 1025 of file AppTools.H.

Referenced by SetupOptions().

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 1036 of file AppTools.H.

◆ Copy()

void Copy ( comlinehandler & incom )

Copy method.

Definition at line 858 of file AppTools.H.

References comlinehandler::_arghelp, comlinehandler::_argname, comlinehandler::_args, comlinehandler::_description, comlinehandler::_error_messages, comlinehandler::_help, comlinehandler::_line, comlinehandler::_nonops, comlinehandler::_notes, comlinehandler::_options, comlinehandler::_program_name, and comlinehandler::_type.

◆ ErrorReport()

std::string ErrorReport ( )

Error reporting.

Returns a report of the errors encountered in the ProcessOptions() function.

Definition at line 1203 of file AppTools.H.

References apptools::DumpContents().

Referenced by main().

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 663 of file AppTools.H.

Referenced by main().

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 597 of file AppTools.H.

◆ GetHelp() [2/2]

std::string GetHelp ( const std::string & l )

inline

Obtain the usage string for an option.

Definition at line 601 of file AppTools.H.

◆ GetLong()

std::string GetLong ( const char & s )

Obtain the long word option from the short char version.

Definition at line 951 of file AppTools.H.

◆ 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 962 of file AppTools.H.

◆ 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 640 of file AppTools.H.

Referenced by main().

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 648 of file AppTools.H.

◆ GetRawComLine()

std::string GetRawComLine ( ) const

inline

Raw Command Line Access.

Definition at line 483 of file AppTools.H.

◆ GetShort()

char GetShort ( const std::string & l )

Obtain the short one char option from the long word version.

Definition at line 1014 of file AppTools.H.

◆ Initialize()

virtual void Initialize ( void )

inlinevirtual

virtual function for program specific Initialization.

Definition at line 734 of file AppTools.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 918 of file AppTools.H.

Referenced by main().

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 475 of file AppTools.H.

◆ 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 1060 of file AppTools.H.

Referenced by main().

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 684 of file AppTools.H.

References x.

◆ ProgramName()

std::string ProgramName ( ) const

inline

Program name access.

Definition at line 659 of file AppTools.H.

◆ ReadRC()

void ReadRC ( const std::string & RCString )

Read a config from RC string.

Definition at line 1212 of file AppTools.H.

◆ 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 1046 of file AppTools.H.

References apptools::stripdirs().

Here is the call 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 716 of file AppTools.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 556 of file AppTools.H.

◆ 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 566 of file AppTools.H.

◆ SetDescription()

void SetDescription ( const std::string & desc )

inline

Set description string.

Definition at line 667 of file AppTools.H.

Referenced by SetupOptions().

Here is the caller graph for this function:

◆ SetNotes()

void SetNotes ( const std::string & notes )

inline

Set notes string.

Definition at line 671 of file AppTools.H.

◆ SetRawComLine()

void SetRawComLine ( const std::string & incl )

Raw Command Line Access.

Definition at line 1192 of file AppTools.H.

◆ 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 974 of file AppTools.H.

Referenced by main().

Here is the caller graph for this function:

◆ UserInitialize()

virtual void UserInitialize ( void )

inlinevirtual

virtual function for program specific Initialization.

Definition at line 738 of file AppTools.H.

◆ WriteRC()

void WriteRC ( std::ostream & Ostr ) const

Write an RC string that can be used for config.

Definition at line 1211 of file AppTools.H.

Friends And Related Function Documentation

◆ operator<<

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

friend

Definition at line 816 of file AppTools.H.

◆ operator>>

std::istream& operator>>	(	std::istream &	In,
		comlinehandler &	cl
	)

friend

Definition at line 744 of file AppTools.H.

Member Data Documentation

◆ _arghelp

std::map<std::string,std::string> _arghelp

protected

help string for args

Definition at line 444 of file AppTools.H.

Referenced by comlinehandler::Copy(), apptools::operator<<(), and apptools::operator>>().

◆ _argname

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

protected

stores a name for arguments

Definition at line 438 of file AppTools.H.

Referenced by comlinehandler::Copy(), apptools::operator<<(), and apptools::operator>>().

◆ _args

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

protected

application arguments;

Definition at line 442 of file AppTools.H.

Referenced by comlinehandler::Copy(), and apptools::operator<<().

◆ _description

std::string _description

protected

application description.

This description will be dumped as the first section of the output of LongUsage().

Definition at line 422 of file AppTools.H.

Referenced by comlinehandler::Copy(), apptools::operator<<(), and apptools::operator>>().

◆ _error_messages

std::vector<std::string> _error_messages

protected

stores error messages

Definition at line 430 of file AppTools.H.

Referenced by comlinehandler::Copy(), and apptools::operator>>().

◆ _help

std::map<char,std::string> _help

protected

stores the help string for each op

Definition at line 436 of file AppTools.H.

Referenced by comlinehandler::Copy(), apptools::operator<<(), and apptools::operator>>().

◆ _line

std::string _line

protected

unformatted command line

Definition at line 428 of file AppTools.H.

Referenced by comlinehandler::Copy().

◆ _nonops

std::vector<std::string> _nonops

protected

stores non-option arguments

Definition at line 432 of file AppTools.H.

Referenced by comlinehandler::Copy().

◆ _notes

std::string _notes

protected

Notes to be displayed at the end of LongUsage().

Definition at line 424 of file AppTools.H.

Referenced by comlinehandler::Copy().

◆ _options

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

protected

stores the value of each option

Definition at line 434 of file AppTools.H.

Referenced by comlinehandler::Copy().

◆ _program_name

std::string _program_name

protected

the name of the program

Definition at line 426 of file AppTools.H.

Referenced by comlinehandler::Copy().

◆ _toks

std::vector<std::string> _toks

protected

commandline tokens

Definition at line 446 of file AppTools.H.

◆ _type

std::map<char,int> _type

protected

stores the type of option

Definition at line 440 of file AppTools.H.

Referenced by comlinehandler::Copy(), apptools::operator<<(), and apptools::operator>>().

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

AppTools.H

Detailed Description

Public Member Functions

Protected Attributes

Friends

Constructor & Destructor Documentation

◆ comlinehandler() [1/3]

◆ comlinehandler() [2/3]

◆ comlinehandler() [3/3]

◆ ~comlinehandler()

Member Function Documentation

◆ AddArgHelp()

◆ AddArgument()

◆ AddHelp() [1/2]

◆ AddHelp() [2/2]

◆ AddOption() [1/2]

◆ AddOption() [2/2]

◆ Copy()

◆ ErrorReport()

◆ GetArgs()

◆ GetHelp() [1/2]

◆ GetHelp() [2/2]

◆ GetLong()

◆ GetOpStringByType()

◆ GetOption() [1/2]

◆ GetOption() [2/2]

◆ GetRawComLine()

◆ GetShort()

◆ Initialize()

◆ LongUsage()

◆ ProcessCommandLine()

◆ ProcessOptions()

◆ ProcessRange()

◆ ProgramName()

◆ ReadRC()

◆ Record()

◆ ResolveOption()

◆ SetArgName() [1/2]

◆ SetArgName() [2/2]

◆ SetDescription()

◆ SetNotes()

◆ SetRawComLine()

◆ ShortUsage()

◆ UserInitialize()

◆ WriteRC()

Friends And Related Function Documentation

◆ operator<<

◆ operator>>

Member Data Documentation

◆ _arghelp

◆ _argname

◆ _args

◆ _description

◆ _error_messages

◆ _help

◆ _line

◆ _nonops

◆ _notes

◆ _options

◆ _program_name

◆ _toks

◆ _type