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

#include <CoinParam.hpp>

Related Symbols
(Note that these are not member symbols.)
Private parameter data
typedef std::vector< CoinParam * >	CoinParamVec
	A type for a parameter vector.
std::ostream &	operator<< (std::ostream &s, const CoinParam &param)
	A stream output function for a CoinParam object.
void	setInputSrc (FILE *src)
	Utility functions for processing CoinParam parameters.
bool	isCommandLine ()
	Returns true if command line parameters are being processed.
bool	isInteractive ()
	Returns true if parameters are being obtained from stdin.
std::string	getStringField (int argc, const char argv[], int valid)
	Attempt to read a string from the input.
int	getIntField (int argc, const char argv[], int valid)
	Attempt to read an integer from the input.
double	getDoubleField (int argc, const char argv[], int valid)
	Attempt to read a real (double) from the input.
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.
std::string	getCommand (int argc, const char argv[], const std::string prompt, std::string pfx=0)
	Get the next command keyword (name).
void	printIt (const char *msg)
	Look up the command keyword (name) in the parameter vector.
void	shortOrHelpMany (CoinParamVec &paramVec, std::string name, int numQuery)
	Utility routine to print help given a short match or explicit request for help.

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. */

class CoinParam {

public: /*!

◆ CoinParamVec

typedef std::vector< CoinParam * > CoinParamVec

A type for a parameter vector.

Definition at line 428 of file CoinParam.hpp.

◆ operator<<()

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

A stream output function for a CoinParam object.

◆ setInputSrc()

void setInputSrc ( FILE * src )

Utility functions for processing CoinParam parameters.

The functions in CoinParamUtils support command line or interactive parameter processing and a help facility. Consult the `Related Functions' section of the CoinParam class documentation for individual function documentation. */ namespace CoinParamUtils { /*!

Take command input from the file specified by src.

Use stdin for src to specify interactive prompting for commands.

◆ isCommandLine()

bool isCommandLine ( )

Returns true if command line parameters are being processed.

◆ isInteractive()

bool isInteractive ( )

Returns true if parameters are being obtained from stdin.

◆ getStringField()

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

Attempt to read a string from the input.

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.

◆ getIntField()

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

Attempt to read an integer from the input.

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.

◆ getDoubleField()

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

Attempt to read a real (double) from the input.

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.

◆ matchParam()

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.

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

◆ getCommand()

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

Get the next command keyword (name).

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.

◆ printIt()

void printIt ( const char * msg )

Look up the command keyword (name) in the parameter vector.

Print help if requested.

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)

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

/*!

Utility to print a long message as filled lines of text

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

◆ shortOrHelpMany()

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

Utility routine to print help given a short match or explicit request for help.

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 shortOrHelpOne(CoinParamVec &paramVec, int matchNdx, std::string name, int numQuery);

/*!

Utility routine to print help given multiple matches.

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.

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

/builddir/build/BUILD/coin-or-CoinUtils-2.11.13-build/CoinUtils-releases-2.11.13/CoinUtils/src/CoinParam.hpp

Related Symbols