A base class for `keyword value' command line parameters. More...

#include <CoinParam.hpp>

Collaboration diagram for CoinParam:

Public Types
Subtypes
enum	CoinParamType { coinParamInvalid = 0, coinParamAct, coinParamInt, coinParamDbl, coinParamStr, coinParamKwd }
	Enumeration for the types of parameters supported by CoinParam. More...

typedef int(*	CoinParamFunc )(CoinParam *param)
	Type declaration for push and pull functions. More...

Public Member Functions
Constructors and Destructors
Be careful how you specify parameters for the constructors! Some compilers are entirely too willing to convert almost anything to bool.
	CoinParam ()
	Default constructor. More...

	CoinParam (std::string name, std::string help, double lower, double upper, double dflt=0.0, bool display=true)
	Constructor for a parameter with a double value. More...

	CoinParam (std::string name, std::string help, int lower, int upper, int dflt=0, bool display=true)
	Constructor for a parameter with an integer value. More...

	CoinParam (std::string name, std::string help, std::string firstValue, int dflt, bool display=true)
	Constructor for a parameter with keyword values. More...

	CoinParam (std::string name, std::string help, std::string dflt, bool display=true)
	Constructor for a string parameter. More...

	CoinParam (std::string name, std::string help, bool display=true)
	Constructor for an action parameter. More...

	CoinParam (const CoinParam &orig)
	Copy constructor. More...

virtual CoinParam *	clone ()
	Clone. More...

CoinParam &	operator= (const CoinParam &rhs)
	Assignment. More...

virtual	~CoinParam ()
	Destructor. More...

Methods to query and manipulate the value(s) of a parameter
void	appendKwd (std::string kwd)
	Add an additional value-keyword to a keyword parameter. More...

int	kwdIndex (std::string kwd) const
	Return the integer associated with the specified value-keyword. More...

std::string	kwdVal () const
	Return the value-keyword that is the current value of the keyword parameter. More...

void	setKwdVal (int value, bool printIt=false)
	Set the value of the keyword parameter using the integer associated with a value-keyword. More...

void	setKwdVal (const std::string value)
	Set the value of the keyword parameter using a value-keyword string. More...

void	printKwds () const
	Prints the set of value-keywords defined for this keyword parameter. More...

void	setStrVal (std::string value)
	Set the value of a string parameter. More...

std::string	strVal () const
	Get the value of a string parameter. More...

void	setDblVal (double value)
	Set the value of a double parameter. More...

double	dblVal () const
	Get the value of a double parameter. More...

void	setIntVal (int value)
	Set the value of a integer parameter. More...

int	intVal () const
	Get the value of a integer parameter. More...

void	setShortHelp (const std::string help)
	Add a short help string to a parameter. More...

std::string	shortHelp () const
	Retrieve the short help string. More...

void	setLongHelp (const std::string help)
	Add a long help message to a parameter. More...

std::string	longHelp () const
	Retrieve the long help message. More...

void	printLongHelp () const
	Print long help. More...

Methods to query and manipulate a parameter object
CoinParamType	type () const
	Return the type of the parameter. More...

void	setType (CoinParamType type)
	Set the type of the parameter. More...

std::string	name () const
	Return the parameter keyword (name) string. More...

void	setName (std::string name)
	Set the parameter keyword (name) string. More...

int	matches (std::string input) const
	Check if the specified string matches the parameter keyword (name) string. More...

std::string	matchName () const
	Return the parameter keyword (name) string formatted to show the minimum match length. More...

void	setDisplay (bool display)
	Set visibility of parameter. More...

bool	display () const
	Get visibility of parameter. More...

CoinParamFunc	pushFunc ()
	Get push function. More...

void	setPushFunc (CoinParamFunc func)
	Set push function. More...

CoinParamFunc	pullFunc ()
	Get pull function. More...

void	setPullFunc (CoinParamFunc func)
	Set pull function. More...

Private Member Functions
Private methods
void	processName ()
	Process a name for efficient matching. More...

Private Attributes
Private parameter data
CoinParamType	type_
	Parameter type (see CoinParamType) More...

std::string	name_
	Parameter name. More...

size_t	lengthName_
	Length of parameter name. More...

size_t	lengthMatch_
	Minimum length required to declare a match for the parameter name. More...

double	lowerDblValue_
	Lower bound on value for a double parameter. More...

double	upperDblValue_
	Upper bound on value for a double parameter. More...

double	dblValue_
	Double parameter - current value. More...

int	lowerIntValue_
	Lower bound on value for an integer parameter. More...

int	upperIntValue_
	Upper bound on value for an integer parameter. More...

int	intValue_
	Integer parameter - current value. More...

std::string	strValue_
	String parameter - current value. More...

std::vector< std::string >	definedKwds_
	Set of valid value-keywords for a keyword parameter. More...

int	currentKwd_
	Current value for a keyword parameter (index into definedKwds_) More...

CoinParamFunc	pushFunc_
	Push function. More...

CoinParamFunc	pullFunc_
	Pull function. More...

std::string	shortHelp_
	Short help. More...

std::string	longHelp_
	Long help. More...

bool	display_
	Display when processing lists of parameters? More...

Related Functions
(Note that these are not member functions.)
typedef std::vector< CoinParam * >	CoinParamVec
	A type for a parameter vector. More...

std::ostream &	operator<< (std::ostream &s, const CoinParam &param)
	A stream output function for a CoinParam object. More...

void	setInputSrc (FILE *src)
	Take command input from the file specified by src. More...

bool	isCommandLine ()
	Returns true if command line parameters are being processed. More...

bool	isInteractive ()
	Returns true if parameters are being obtained from stdin. More...

std::string	getStringField (int argc, const char argv[], int valid)
	Attempt to read a string from the input. More...

int	getIntField (int argc, const char argv[], int valid)
	Attempt to read an integer from the input. More...

double	getDoubleField (int argc, const char argv[], int valid)
	Attempt to read a real (double) from the input. More...

int	matchParam (const CoinParamVec &paramVec, std::string name, int &matchNdx, int &shortCnt)
	Scan a parameter vector for parameters whose keyword (name) string matches `name` using minimal match rules. More...

std::string	getCommand (int argc, const char argv[], const std::string prompt, std::string pfx=0)
	Get the next command keyword (name) More...

int	lookupParam (std::string name, CoinParamVec &paramVec, int matchCnt=0, int shortCnt=0, int *queryCnt=0)
	Look up the command keyword (name) in the parameter vector. Print help if requested. More...

void	printIt (const char *msg)
	Utility to print a long message as filled lines of text. More...

void	shortOrHelpOne (CoinParamVec &paramVec, int matchNdx, std::string name, int numQuery)
	Utility routine to print help given a short match or explicit request for help. More...

void	shortOrHelpMany (CoinParamVec &paramVec, std::string name, int numQuery)
	Utility routine to print help given multiple matches. More...

void	printGenericHelp ()
	Print a generic `how to use the command interface' help message. More...

void	printHelp (CoinParamVec &paramVec, int firstParam, int lastParam, std::string prefix, bool shortHelp, bool longHelp, bool hidden)
	Utility routine to print help messages for one or more parameters. More...

Detailed Description

A base class for `keyword value' command line parameters.

The underlying paradigm is that a parameter specifies an action to be performed on a target object. The base class provides two function pointers, a `push' function and a `pull' function. By convention, a push function will set some value in the target object or perform some action using the target object. A `pull' function will retrieve some value from the target object. This is only a convention, however; CoinParam and associated utilities make no use of these functions and have no hardcoded notion of how they should be used.

The action to be performed, and the target object, will be specific to a particular application. It is expected that users will derive application-specific parameter classes from this base class. A derived class will typically add fields and methods to set/get a code for the action to be performed (often, an enum class) and the target object (often, a pointer or reference).

Facilities provided by the base class and associated utility routines include:

Support for common parameter types with numeric, string, or keyword values.
Support for short and long help messages.
Pointers to `push' and `pull' functions as described above.
Command line parsing and keyword matching.

All utility routines are declared in the CoinParamUtils namespace.

The base class recognises five types of parameters: actions (which require no value); numeric parameters with integer or real (double) values; keyword parameters, where the value is one of a defined set of value-keywords; and string parameters (where the value is a string). The base class supports the definition of a valid range, a default value, and short and long help messages for a parameter.

As defined by the CoinParamFunc typedef, push and pull functions should take a single parameter, a pointer to a CoinParam. Typically this object will actually be a derived class as described above, and the implementation function will have access to all capabilities of CoinParam and of the derived class.

When specified as command line parameters, the expected syntax is `-keyword value' or `-keyword=value'. You can also use the Gnu double-dash style, `–keyword'. Spaces around the `=' will not work.

The keyword (name) for a parameter can be defined with an `!' to mark the minimal match point. For example, allow!ableGap will be considered matched by the strings `allow', `allowa', `allowab', etc. Similarly, the value-keyword strings for keyword parameters can be defined with `!' to mark the minimal match point. Matching of keywords and value-keywords is not case sensitive.

Definition at line 75 of file CoinParam.hpp.

Member Typedef Documentation

typedef int(* CoinParam::CoinParamFunc)(CoinParam *param)

Type declaration for push and pull functions.

By convention, a return code of 0 indicates execution without error, >0 indicates nonfatal error, and <0 indicates fatal error. This is only convention, however; the base class makes no use of the push and pull functions and has no hardcoded interpretation of the return code.

Definition at line 107 of file CoinParam.hpp.

Member Enumeration Documentation

enum CoinParam::CoinParamType

Enumeration for the types of parameters supported by CoinParam.

CoinParam provides support for several types of parameters:

Action parameters, which require no value.
Integer and double numeric parameters, with upper and lower bounds.
String parameters that take an arbitrary string value.
Keyword parameters that take a defined set of string (value-keyword) values. Value-keywords are associated with integers in the order in which they are added, starting from zero.

Enumerator
coinParamInvalid
coinParamAct
coinParamInt
coinParamDbl
coinParamStr
coinParamKwd

Definition at line 93 of file CoinParam.hpp.

Constructor & Destructor Documentation

CoinParam::CoinParam ( )

Default constructor.

CoinParam::CoinParam	(	std::string	name,
		std::string	help,
		double	lower,
		double	upper,
		double	dflt = `0.0`,
		bool	display = `true`
	)

Constructor for a parameter with a double value.

The default value is 0.0. Be careful to clearly indicate that lower and upper are real (double) values to distinguish this constructor from the constructor for an integer parameter.

CoinParam::CoinParam	(	std::string	name,
		std::string	help,
		int	lower,
		int	upper,
		int	dflt = `0`,
		bool	display = `true`
	)

Constructor for a parameter with an integer value.

The default value is 0.

CoinParam::CoinParam	(	std::string	name,
		std::string	help,
		std::string	firstValue,
		int	dflt,
		bool	display = `true`
	)

Constructor for a parameter with keyword values.

The string supplied as firstValue becomes the first value-keyword. Additional value-keywords can be added using appendKwd(). It's necessary to specify both the first value-keyword (firstValue) and the default value-keyword index (dflt) in order to distinguish this constructor from the constructors for string and action parameters.

Value-keywords are associated with an integer, starting with zero and increasing as each keyword is added. The value-keyword given as firstValue will be associated with the integer zero. The integer supplied for dflt can be any value, as long as it will be valid once all value-keywords have been added.

CoinParam::CoinParam	(	std::string	name,
		std::string	help,
		std::string	dflt,
		bool	display = `true`
	)

Constructor for a string parameter.

For some compilers, the default value (dflt) must be specified explicitly with type std::string to distinguish the constructor for a string parameter from the constructor for an action parameter. For example, use std::string("default") instead of simply "default", or use a variable of type std::string.

CoinParam::CoinParam	(	std::string	name,
		std::string	help,
		bool	display = `true`
	)

Constructor for an action parameter.

CoinParam::CoinParam ( const CoinParam & orig )

Copy constructor.

virtual CoinParam::~CoinParam ( )

virtual

Destructor.

Member Function Documentation

virtual CoinParam* CoinParam::clone ( )

virtual

Clone.

CoinParam& CoinParam::operator= ( const CoinParam & rhs )

Assignment.

void CoinParam::appendKwd ( std::string kwd )

Add an additional value-keyword to a keyword parameter.

int CoinParam::kwdIndex ( std::string kwd ) const

Return the integer associated with the specified value-keyword.

Returns -1 if no value-keywords match the specified string.

std::string CoinParam::kwdVal ( ) const

Return the value-keyword that is the current value of the keyword parameter.

void CoinParam::setKwdVal	(	int	value,
		bool	printIt = `false`
	)

Set the value of the keyword parameter using the integer associated with a value-keyword.

If printIt is true, the corresponding value-keyword string will be echoed to std::cout.

void CoinParam::setKwdVal ( const std::string value )

Set the value of the keyword parameter using a value-keyword string.

The given string will be tested against the set of value-keywords for the parameter using the shortest match rules.

void CoinParam::printKwds ( ) const

Prints the set of value-keywords defined for this keyword parameter.

void CoinParam::setStrVal ( std::string value )

Set the value of a string parameter.

std::string CoinParam::strVal ( ) const

Get the value of a string parameter.

void CoinParam::setDblVal ( double value )

Set the value of a double parameter.

double CoinParam::dblVal ( ) const

Get the value of a double parameter.

void CoinParam::setIntVal ( int value )

Set the value of a integer parameter.

int CoinParam::intVal ( ) const

Get the value of a integer parameter.

void CoinParam::setShortHelp ( const std::string help )

inline

Add a short help string to a parameter.

Definition at line 256 of file CoinParam.hpp.

std::string CoinParam::shortHelp ( ) const

inline

Retrieve the short help string.

Definition at line 260 of file CoinParam.hpp.

void CoinParam::setLongHelp ( const std::string help )

inline

Add a long help message to a parameter.

See printLongHelp() for a description of how messages are broken into lines.

Definition at line 267 of file CoinParam.hpp.

std::string CoinParam::longHelp ( ) const

inline

Retrieve the long help message.

Definition at line 271 of file CoinParam.hpp.

void CoinParam::printLongHelp ( ) const

Print long help.

Prints the long help string, plus the valid range and/or keywords if appropriate. The routine makes a best effort to break the message into lines appropriate for an 80-character line. Explicit line breaks in the message will be observed. The short help string will be used if long help is not available.

CoinParamType CoinParam::type ( ) const

inline

Return the type of the parameter.

Definition at line 290 of file CoinParam.hpp.

void CoinParam::setType ( CoinParamType type )

inline

Set the type of the parameter.

Definition at line 294 of file CoinParam.hpp.

std::string CoinParam::name ( ) const

inline

Return the parameter keyword (name) string.

Definition at line 298 of file CoinParam.hpp.

void CoinParam::setName ( std::string name )

inline

Set the parameter keyword (name) string.

Definition at line 302 of file CoinParam.hpp.

int CoinParam::matches ( std::string input ) const

Check if the specified string matches the parameter keyword (name) string.

Returns 1 if the string matches and meets the minimum match length, 2 if the string matches but doesn't meet the minimum match length, and 0 if the string doesn't match. Matches are not case-sensitive.

std::string CoinParam::matchName ( ) const

Return the parameter keyword (name) string formatted to show the minimum match length.

For example, if the parameter name was defined as allow!ableGap, the string returned by matchName would be allow(ableGap).

void CoinParam::setDisplay ( bool display )

inline

Set visibility of parameter.

Intended to control whether the parameter is shown when a list of parameters is processed. Used by CoinParamUtils::printHelp when printing help messages for a list of parameters.

Definition at line 331 of file CoinParam.hpp.

bool CoinParam::display ( ) const

inline

Get visibility of parameter.

Definition at line 335 of file CoinParam.hpp.

CoinParamFunc CoinParam::pushFunc ( )

inline

Get push function.

Definition at line 339 of file CoinParam.hpp.

void CoinParam::setPushFunc ( CoinParamFunc func )

inline

Set push function.

Definition at line 343 of file CoinParam.hpp.

CoinParamFunc CoinParam::pullFunc ( )

inline

Get pull function.

Definition at line 347 of file CoinParam.hpp.

void CoinParam::setPullFunc ( CoinParamFunc func )

inline

Set pull function.

Definition at line 351 of file CoinParam.hpp.

void CoinParam::processName ( )

private

Process a name for efficient matching.

Friends And Related Function Documentation

typedef std::vector< CoinParam * > CoinParamVec

Definition at line 428 of file CoinParam.hpp.

std::ostream & operator<<	(	std::ostream &	s,
		const CoinParam &	param
	)

void setInputSrc ( FILE * src )

Use stdin for src to specify interactive prompting for commands.

bool isCommandLine ( )

bool isInteractive ( )

std::string getStringField	(	int	argc,
		const char *	argv[],
		int *	valid
	)

argc and argv are used only if isCommandLine() would return true. If valid is supplied, it will be set to 0 if a string is parsed without error, 2 if no field is present.

int getIntField	(	int	argc,
		const char *	argv[],
		int *	valid
	)

argc and argv are used only if isCommandLine() would return true. If valid is supplied, it will be set to 0 if an integer is parsed without error, 1 if there's a parse error, and 2 if no field is present.

double getDoubleField	(	int	argc,
		const char *	argv[],
		int *	valid
	)

argc and argv are used only if isCommandLine() would return true. If valid is supplied, it will be set to 0 if a real number is parsed without error, 1 if there's a parse error, and 2 if no field is present.

int matchParam	(	const CoinParamVec &	paramVec,
		std::string	name,
		int &	matchNdx,
		int &	shortCnt
	)

matchNdx is set to the index of the last parameter that meets the minimal match criteria (but note there should be at most one matching parameter if the parameter vector is properly configured). shortCnt is set to the number of short matches (should be zero for a properly configured parameter vector if a minimal match is found). The return value is the number of matches satisfying the minimal match requirement (should be 0 or 1 in a properly configured vector).

std::string getCommand	(	int	argc,
		const char *	argv[],
		const std::string	prompt,
		std::string *	pfx = `0`
	)

To be precise, return the next field from the current command input source, after a bit of processing. In command line mode (isCommandLine() returns true) the next field will normally be of the form `-keyword' or `–keyword' (i.e., a parameter keyword), and the string returned would be `keyword'. In interactive mode (isInteractive() returns true), the user will be prompted if necessary. It is assumed that the user knows not to use the `-' or `–' prefixes unless specifying parameters on the command line.

There are a number of special cases if we're in command line mode. The order of processing of the raw string goes like this:

A stand-alone `-' is forced to `stdin'.
A stand-alone '–' is returned as a word; interpretation is up to the client.
A prefix of '-' or '–' is stripped from the string.

If the result is the string `stdin', command processing shifts to interactive mode and the user is immediately prompted for a new command.

Whatever results from the above sequence is returned to the user as the return value of the function. An empty string indicates end of input.

prompt will be used only if it's necessary to prompt the user in interactive mode.

int lookupParam	(	std::string	name,
		CoinParamVec &	paramVec,
		int *	matchCnt = `0`,
		int *	shortCnt = `0`,
		int *	queryCnt = `0`
	)

In the most straightforward use, name is a string without `?', and the value returned is the index in paramVec of the single parameter that matched name. One or more '?' characters at the end of name is a query for information. The routine prints short (one '?') or long (more than one '?') help messages for a query. Help is also printed in the case where the name is ambiguous (some of the matches did not meet the minimal match length requirement).

Note that multiple matches meeting the minimal match requirement is a configuration error. The mimimal match length for the parameters involved is too short.

If provided as parameters, on return

matchCnt will be set to the number of matches meeting the minimal match requirement
shortCnt will be set to the number of matches that did not meet the miminal match requirement
queryCnt will be set to the number of '?' characters at the end of the name

The return values are:

>0: index in paramVec of the single unique match for name
-1: a query was detected (one or more '?' characters at the end of name
-2: one or more short matches, not a query
-3: no matches, not a query
-4: multiple matches meeting the minimal match requirement (configuration error)

void printIt ( const char * msg )

The routine makes a best effort to break lines without exceeding the standard 80 character line length. Explicit newlines in msg will be obeyed.

void shortOrHelpOne	(	CoinParamVec &	paramVec,
		int	matchNdx,
		std::string	name,
		int	numQuery
	)

The two really are related, in that a query (a string that ends with one or more `?' characters) will often result in a short match. The routine expects that name matches a single parameter, and does not look for multiple matches.

If called with matchNdx < 0, the routine will look up name in paramVec and print the full name from the parameter. If called with matchNdx > 0, it just prints the name from the specified parameter. If the name is a query, short (one '?') or long (more than one '?') help is printed.

void shortOrHelpMany	(	CoinParamVec &	paramVec,
		std::string	name,
		int	numQuery
	)

If the name is not a query, or asks for short help (i.e., contains zero or one '?' characters), the list of matching names is printed. If the name asks for long help (contains two or more '?' characters), short help is printed for each matching name.

void printGenericHelp ( )

The message is hard coded to match the behaviour of the parsing utilities.

void printHelp	(	CoinParamVec &	paramVec,
		int	firstParam,
		int	lastParam,
		std::string	prefix,
		bool	shortHelp,
		bool	longHelp,
		bool	hidden
	)

Intended as a utility to implement explicit `help' commands. Help will be printed for all parameters in paramVec from firstParam to lastParam, inclusive. If shortHelp is true, short help messages will be printed. If longHelp is true, long help messages are printed. shortHelp overrules longHelp. If neither is true, only command keywords are printed. prefix is printed before each line; it's an imperfect attempt at indentation.

Member Data Documentation

CoinParamType CoinParam::type_

private

Parameter type (see CoinParamType)

Definition at line 367 of file CoinParam.hpp.

std::string CoinParam::name_

private

Parameter name.

Definition at line 370 of file CoinParam.hpp.

size_t CoinParam::lengthName_

private

Length of parameter name.

Definition at line 373 of file CoinParam.hpp.

size_t CoinParam::lengthMatch_

private

Minimum length required to declare a match for the parameter name.

Definition at line 378 of file CoinParam.hpp.

double CoinParam::lowerDblValue_

private

Lower bound on value for a double parameter.

Definition at line 381 of file CoinParam.hpp.

double CoinParam::upperDblValue_

private

Upper bound on value for a double parameter.

Definition at line 384 of file CoinParam.hpp.

double CoinParam::dblValue_

private

Double parameter - current value.

Definition at line 387 of file CoinParam.hpp.

int CoinParam::lowerIntValue_

private

Lower bound on value for an integer parameter.

Definition at line 390 of file CoinParam.hpp.

int CoinParam::upperIntValue_

private

Upper bound on value for an integer parameter.

Definition at line 393 of file CoinParam.hpp.

int CoinParam::intValue_

private

Integer parameter - current value.

Definition at line 396 of file CoinParam.hpp.

std::string CoinParam::strValue_

private

String parameter - current value.

Definition at line 399 of file CoinParam.hpp.

std::vector< std::string > CoinParam::definedKwds_

private

Set of valid value-keywords for a keyword parameter.

Definition at line 402 of file CoinParam.hpp.

int CoinParam::currentKwd_

private

Current value for a keyword parameter (index into definedKwds_)

Definition at line 406 of file CoinParam.hpp.

CoinParamFunc CoinParam::pushFunc_

private

Push function.

Definition at line 409 of file CoinParam.hpp.

CoinParamFunc CoinParam::pullFunc_

private

Pull function.

Definition at line 412 of file CoinParam.hpp.

std::string CoinParam::shortHelp_

private

Short help.

Definition at line 415 of file CoinParam.hpp.

std::string CoinParam::longHelp_

private

Long help.

Definition at line 418 of file CoinParam.hpp.

bool CoinParam::display_

private

Display when processing lists of parameters?

Definition at line 421 of file CoinParam.hpp.

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

/tmp/DyLP-1.10.4/CoinUtils/src/CoinParam.hpp

Public Types

Public Member Functions

Private Member Functions

Private Attributes

Related Functions

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation