# CoinParamUtils Namespace Reference

Utility functions for processing CoinParam parameters. More...

## Functions
void | setInputSrc (FILE *src)
| Take command input from the file specified by src.
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).
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.
void | printIt (const char *msg)
| Utility to print a long message as filled lines of text.
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.
void | shortOrHelpMany (CoinParamVec &paramVec, std::string name, int numQuery)
| Utility routine to print help given multiple matches.
void | printGenericHelp ()
| Print a generic `how to use the command interface' help message.
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.

## Detailed Description

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.

## Function Documentation

void CoinParamUtils::setInputSrc | ( | FILE * | src | ) |

Take command input from the file specified by src.

Use stdin for `src` to specify interactive prompting for commands.

bool CoinParamUtils::isCommandLine | ( |  | ) |

Returns true if command line parameters are being processed.

bool CoinParamUtils::isInteractive | ( |  | ) |

Returns true if parameters are being obtained from stdin.

std::string CoinParamUtils::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.

int CoinParamUtils::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.

double CoinParamUtils::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.

int CoinParamUtils::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).

std::string CoinParamUtils::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.

int CoinParamUtils::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.

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 CoinParamUtils::printIt | ( | const char * | msg | ) |

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.

void CoinParamUtils::shortOrHelpOne | ( | CoinParamVec & | paramVec,
|  | int | matchNdx,
|  | 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 CoinParamUtils::shortOrHelpMany | ( | CoinParamVec & | paramVec,
|  | 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.

void CoinParamUtils::printGenericHelp | ( |  | ) |

Print a generic `how to use the command interface' help message.

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

void CoinParamUtils::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.

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.