Command line and parameter parsing

These classes and functions relate to the parsing of the command line and the parameter parsing for plug-ins. More...

## Data Structures

class | CCmdBoolOption
| The command line option that sets a flag to true when given. More...
class | CCmdFlagOption
| Command line option that translates a string to a set of flags. More...
class | CCmdOption
| The base class for all command line options. More...
class | CCmdOptionList
| The class to hold the list of options. More...
class | CCmdStringOption
| The command line option that expects a string. More...
class | CComplexOptionParser
| Parser for complex command line options. More...
class | CDictParameter< T >
| Dictionary parameter. More...
class | CParameter
| The base class for parameters used in complex options. More...
class | CParamList
| A class to hold a list of named parameters. More...
class | CParamOption
| command line option that handles a parameter More...
class | CPropertyFlagHolder
| This class holds a set of properties. More...
class | CSetParameter< T >
| A parameter that can only assume values out of a limited set. More...
class | CTParameter< T >
| Generic type of a complex paramter. More...
class | TCmdOption< T >
| Templated version based on CCmdOptionValue for values that can be converted to and from strings by stream operators. More...
class | TDelayedParameter< T >
| A parameter proxy object with a key to identify it. More...
class | TDictMap< T >
| A mapper from emums to string values. - usefull for names flags. More...
class | TFactoryParameter< F >
| A parameter that get's initialized by a factory to a shared or unique pointer. More...
class | TParameter< T >
| A parameter that can assume any value of the given value type. More...
class | TRepeatableCmdOption< T >
| Templated version based on CCmdOptionValue for values that can be converted to and from strings by stream operators. More...

## Typedefs

typedef std::map< std::string, std::string > | CParsedOptions
typedef std::map< EProgramDescriptionEntry, const char * > | SProgramDescription
| the map that holds a basic program description

## Enumerations

enum class

EParameterBounds : int {
EParameterBounds::bf_none = 0 , EParameterBounds::bf_min = 1 , EParameterBounds::bf_min_open = 3 , EParameterBounds::bf_min_closed = 5 ,
EParameterBounds::bf_min_flags = 7 , EParameterBounds::bf_max = 0x10 , EParameterBounds::bf_max_open = 0x30 , EParameterBounds::bf_max_closed = 0x50 ,
EParameterBounds::bf_max_flags = 0x70 , EParameterBounds::bf_closed_interval = 0x55 , EParameterBounds::bf_open_interval = 0x33
}

| Scalar parameter with an expected value range. More...
enum | EProgramDescriptionEntry { pdi_group = 0 , pdi_short = 1 , pdi_description = 2 , pdi_example_descr = 3 , pdi_example_code = 4 , pdi_author = 5 }
| program description entry identifiers More...

## Functions

PCmdOption | make_opt (bool &value, const char *long_opt, char short_opt, const char *help, CCmdOptionFlags flags=CCmdOptionFlags::none)
| Create an option that represents a flag.
PCmdOption | make_opt (int &value, const CFlagString &map, const char *long_opt, char short_opt, const char *long_help, const char *short_help, CCmdOptionFlags flags=CCmdOptionFlags::none)
| Create a flag lookup option.
PCmdOption | make_opt (std::string &value, const char *long_opt, char short_opt, const char *long_help, CCmdOptionFlags flags=CCmdOptionFlags::none, const CPluginHandlerBase *plugin_hint=NULL)
| Create an option to set a string.
template<typename T>
PCmdOption | make_opt (std::vector< T > &value, const char *long_opt, char short_opt, const char *help, CCmdOptionFlags flags=CCmdOptionFlags::none)
| Create an option to set a vector of values,.
template<typename T>
PCmdOption | make_opt (T &value, const char *long_opt, char short_opt, const char *help, CCmdOptionFlags flags=CCmdOptionFlags::none)
| Create a standard option that sets a value of the give type.
template<typename T>
PCmdOption | make_opt (T &value, const std::set< T > &valid_set, const char *long_opt, char short_opt, const char *help, CCmdOptionFlags flags=CCmdOptionFlags::none)
| Create an oüption that only takes values from a pre-defined set.
template<typename T>
PCmdOption | make_opt (T &value, const TDictMap< T > &map, const char *long_opt, char short_opt, const char *help)
| Create a table lookup option.
template<typename T>
PCmdOption | make_opt (T &value, EParameterBounds bflags, const std::vector< T > &bounds, const char *long_opt, char short_opt, const char *help, CCmdOptionFlags flags=CCmdOptionFlags::none)
| Create an option of a scalar value that can have boundaries.
template<typename T>
PCmdOption | make_opt (typename std::shared_ptr< T > &value, const char *default_value, const char *long_opt, char short_opt, const char *help, CCmdOptionFlags flags=CCmdOptionFlags::none)
| Create a command line option that creates uses a factory to create an object based on the given description.
template<typename T>
PCmdOption | make_opt (typename std::unique_ptr< T > &value, const char *default_value, const char *long_opt, char short_opt, const char *help, CCmdOptionFlags flags=CCmdOptionFlags::none)
| Create a command line option that creates uses a factory to create an object based on the given description.
template<typename T>
CParameter * | make_param (std::shared_ptr< T > &value, const std::string &init, bool required, const char *descr)
| create a factory parameter that initializes to a std::shared_ptr
template<typename T>
CParameter * | make_param (std::unique_ptr< T > &value, const std::string &init, bool required, const char *descr)
| create a factory parameter that initializes to a std::unique_ptr
template<typename T>
PCmdOption | make_repeatable_opt (std::vector< T > &value, const char *long_opt, char short_opt, const char *help, CCmdOptionFlags flags=CCmdOptionFlags::none)
| Create a repeatable option to set a vector of values.

## Detailed Description

These classes and functions relate to the parsing of the command line and the parameter parsing for plug-ins.

## Typedef Documentation

## CParsedOptions

typedef std::map<std::string, std::string> CParsedOptions

a map of parsed options as pairs key:value pairs

Definition at line 38 of file optionparser.hh.

## SProgramDescription

typedef std::map<EProgramDescriptionEntry, const char *> SProgramDescription

the map that holds a basic program description

Map of strings to provied information about the program The following values should be provied: (1) the program section, (2) A short description of the program - this will become the whatis entry in the man page, (3) A long description of the program (4) A text describing an example usage (5) The actual exampel call without the program name. This information is used by the auto-help system to create man-pages and a cross-referenced help of all the programs.

Definition at line 81 of file cmdlineparser.hh.

## Enumeration Type Documentation

## EParameterBounds

enum class EParameterBounds : int

strong

Scalar parameter with an expected value range.

A scalar parameter that supports a bracketing range. If the user tries to set the parameter to a value outside the range, the set method will throw an invalid_argument exception

Scalar parameter with a expected value boundaries

A scalar parameter that supports specifying boundaries. These boundaries can be one-sided or on both sides, and the boundaries can be included in the range or not. If the user tries to set the parameter to a value outside the range, the set method will throw an invalid_argument exception

Enumerator
bf_none |
bf_min |
bf_min_open |
bf_min_closed |
bf_min_flags |
bf_max |
bf_max_open |
bf_max_closed |
bf_max_flags |
bf_closed_interval |
bf_open_interval |

Definition at line 216 of file parameter.hh.

## EProgramDescriptionEntry

enum EProgramDescriptionEntry

program description entry identifiers

These enumerates identify the parts of the program description

Enumerator
pdi_group |
pdi_short |
pdi_description |
pdi_example_descr |
pdi_example_code |
pdi_author |

Definition at line 56 of file cmdlineparser.hh.

## Function Documentation

## make_opt() [1/10]

PCmdOption make_opt | ( | bool & | value,
|  | const char * | long_opt,
|  | char | short_opt,
|  | const char * | help,
|  | CCmdOptionFlags | flags = CCmdOptionFlags::none )

Create an option that represents a flag.

It is always assumed to be not set if the according option is not given at the command line

Parameters

  [out] | value | the boolean that carries the result
  | long_opt | long option name (must not be NULL)
  | short_opt | short option name (or 0)
  | help | help string (must not be NULL)
  | flags | option flags

Returns
  the option warped into a boost::shared_ptr

References none.

## make_opt() [2/10]

PCmdOption make_opt | ( | int & | value,
|  | const CFlagString & | map,
|  | const char * | long_opt,
|  | char | short_opt,
|  | const char * | long_help,
|  | const char * | short_help,
|  | CCmdOptionFlags | flags = CCmdOptionFlags::none )

Create a flag lookup option.

Parameters

  [in,out] | value | at input it holds the default value, at output, if the command line option was givem this value is replaced by the parsed and translated option value,
  | map | the lookup table for the option flags
  | long_opt | long option name (must not be NULL)
  | short_opt | short option name (or 0)
  | long_help | long help string (must not be NULL)
  | short_help | short help string
  | flags | add flags like whether the optionis required to be set

Returns
  the option warped into a boost::shared_ptr

Remarks
  Probably unnecessary

References none.

## make_opt() [3/10]

PCmdOption make_opt | ( | std::string & | value,
|  | const char * | long_opt,
|  | char | short_opt,
|  | const char * | long_help,
|  | CCmdOptionFlags | flags = CCmdOptionFlags::none,
|  | const CPluginHandlerBase * | plugin_hint = NULL )

Create an option to set a string.

Create an option that holds a string

Parameters

  [in,out] | value | at input it holds the default value, at output, if the command line option was givem this value is replaced by the parsed and translated option value,
  | long_opt | long option name (must not be NULL)
  | short_opt | short option name (or 0)
  | long_help | long help string (must not be NULL)
  | flags | add flags like whether the optionis required to be set
  | plugin_hint | if the string will later be used to create an object by using plug-in then pass a pointer to the corresponding plug-in handler to give a hint the help system about this connection.

Returns
  the option warped into a boost::shared_ptr

References none.

## make_opt() [4/10]

template<typename T>

PCmdOption make_opt | ( | std::vector< T > & | value,
|  | const char * | long_opt,
|  | char | short_opt,
|  | const char * | help,
|  | CCmdOptionFlags | flags = CCmdOptionFlags::none )

Create an option to set a vector of values,.

The parameters on the command line will be separated by ',' and without spaces (or protected from the shell by usinh "". If the vetcor comes with a pre-allocated size, then the numer of given values must correspond to this size, Otherwise the size of the vector is deducted from the given command line parameter,.

Template Parameters

  T | type of the value hold by the vector

Parameters

  [in,out] | value | at input: if not empty, number of expected values and their defaults, at output: the values given on the command line
  | long_opt | long option name (must not be NULL)
  | short_opt | short option name (or 0)
  | help | help string (must not be NULL)
  | flags | option flags indicating whether the option is required

Remarks
  be aware that localization of the decimal separator of floating point values is not supported, it is always the full stop ".".

Definition at line 458 of file cmdparamoption.hh.

References none.

## make_opt() [5/10]

template<typename T>

PCmdOption make_opt | ( | T & | value,
|  | const char * | long_opt,
|  | char | short_opt,
|  | const char * | help,
|  | CCmdOptionFlags | flags = CCmdOptionFlags::none )

Create a standard option that sets a value of the give type.

Create a standard option that translates a string given on the command line into a value. The translation back-end is implemented with CTParameter.

Template Parameters

  T | the type of thevalue, it must support to be read from (operator >>) and written (operator << ) to a stream, as the back-end uses these opterator to translate.

Parameters

  [in,out] | value | at input the default value, at output the parsed value if it was given.
  | short_opt | short option name (or 0)
  | long_opt | long option name (must not be NULL)
  | help | long help string (must not be NULL)
  | flags | add flags like whether the optionis required to be set

Returns
  the option warped into a boost::shared_ptr

Definition at line 273 of file cmdlineparser.hh.

References none, and required.

## make_opt() [6/10]

template<typename T>

PCmdOption make_opt | ( | T & | value,
|  | const std::set< T > & | valid_set,
|  | const char * | long_opt,
|  | char | short_opt,
|  | const char * | help,
|  | CCmdOptionFlags | flags = CCmdOptionFlags::none )

Create an oüption that only takes values from a pre-defined set.

Create an option that can only take values from a given set.

Template Parameters

  T | the type of the value to be set

Parameters

  [in,out] | value | at input it holds the default value, at output, if the command line option was givem this value is replaced by the parsed and translated option value,
  | valid_set | the set of allowed values
  | long_opt | long option name (must not be NULL)
  | short_opt | short option name (or 0)
  | help | long help string (must not be NULL)
  | flags | option flags indicating whether the option is required

Returns
  the option warped into a boost::shared_ptr

Definition at line 404 of file cmdlineparser.hh.

References none, and required.

## make_opt() [7/10]

template<typename T>

PCmdOption make_opt | ( | T & | value,
|  | const TDictMap< T > & | map,
|  | const char * | long_opt,
|  | char | short_opt,
|  | const char * | help )

Create a table lookup option.

Create an option that uses a table to translate between the string given on the command line and the actual value.

Template Parameters

  T | the type of the value

Parameters

  [in,out] | value | variable to hold the parsed and translated option value. At entry, the value must be set to a valid dictionary entry.
  | map | the lookup table for the option
  | long_opt | long option name (must not be NULL)
  | short_opt | short option name (or 0)
  | help | help string (must not be NULL)

Returns
  the option warped into a boost::shared_ptr

Definition at line 338 of file cmdlineparser.hh.

## make_opt() [8/10]

template<typename T>

PCmdOption make_opt | ( | T & | value,
|  | EParameterBounds | bflags,
|  | const std::vector< T > & | bounds,
|  | const char * | long_opt,
|  | char | short_opt,
|  | const char * | help,
|  | CCmdOptionFlags | flags = CCmdOptionFlags::none )

Create an option of a scalar value that can have boundaries.

If the given value does not fit into the range an exception will be thrown

Template Parameters

  T | type of the value to be parsed, supported are float, double, long, int, short, unsigned long, unsigned int, unsigned short.

Parameters

  value | value variable to hold the parsed option value - pass in the default value -
  bflags | boundary flags
  bounds | vector containing the boundaries of the allowed parameter range (depends on bflags)
  short_opt | short option name (or 0)
  long_opt | long option name (must not be NULL)
  help | long help string (must not be NULL)
  flags | add flags like whether the optionis required to be set

Returns
  the option warped into a boost::shared_ptr

Definition at line 296 of file cmdlineparser.hh.

References none, and required.

## make_opt() [9/10]

template<typename T>

PCmdOption make_opt | ( | typename std::shared_ptr< T > & | value,
|  | const char * | default_value,
|  | const char * | long_opt,
|  | char | short_opt,
|  | const char * | help,
|  | CCmdOptionFlags | flags = CCmdOptionFlags::none )

Create a command line option that creates uses a factory to create an object based on the given description.

Create a command line option that creates uses a factory to create the value based on the command line arguments given,

Template Parameters

  T | the non-pointer type of the value

Parameters

  [out] | value | at output, if the command line option was givem this value is replaced by the parsed and translated option value. If not given but the default_values was given then this default initializer is used to create the actual value. If no default value was givem and the option is not given at the command line, then the value is not touched.
  | default_value | default value if parameter is not given
  | long_opt | long option name
  | short_opt | short option char, set to 0 of none givn
  | help | the help string for thie option
  | flags | indicates whether theoption is required

Remarks
  although passing in an initialized pointer and and empty default_value would act like the the initializer string was used for the pointer, it is better to pass an empty shared pointer in order to avoid unnecessary initializations of the pointer is later overwritten.

Definition at line 435 of file cmdlineparser.hh.

References none, and required.

## make_opt() [10/10]

template<typename T>

PCmdOption make_opt | ( | typename std::unique_ptr< T > & | value,
|  | const char * | default_value,
|  | const char * | long_opt,
|  | char | short_opt,
|  | const char * | help,
|  | CCmdOptionFlags | flags = CCmdOptionFlags::none )

Create a command line option that creates uses a factory to create an object based on the given description.

Create a command line option that uses a TFactoryPluginHandler to create the actual value hold by a std::unique_ptr.

Template Parameters

  T | the non-pointer type of the value

Parameters

  [out] | value | at output, if the command line option was given this value is replaced by the parsed and translated option value. If not given but the default_values was given then this default initializer is used to create the actual value.
  | default_value | default value if parameter is not given
  | long_opt | long option name
  | short_opt | short option char, set to 0 of none givn
  | help | the help string for thie option
  | flags | option flags indicating whether the option is required

Remarks
  although passing in an initialized pointer and and empty default_value would act like the the initializer string was used for the pointer, it is better to pass an empty shared pointer in order to avoid unnecessary initializations of the pointer is later overwritten.

Definition at line 464 of file cmdlineparser.hh.

References none, and required.

## make_param() [1/2]

template<typename T>

CParameter * make_param | ( | std::shared_ptr< T > & | value,
|  | const std::string & | init,
|  | bool | required,
|  | const char * | descr )

create a factory parameter that initializes to a std::shared_ptr

Creates a TFactoryParameter accurding to the given parameters. The advantage over calling the TactoryParameter cunstructor is, that type deduction is done automatically.

Template Parameters

  the | type of the factory created parameter value

Parameters

  value | the shared_ptr value to be set through this parameter. Best is to pass an empty shared pointer and leave the initialization to the parameter handling
  init | the default initialization string for the parameter, pass "" if there is no default.
  required | set to true if the user must set this parameter
  descr | a help description of the parameter

Definition at line 619 of file parameter.hh.

References required.

## make_param() [2/2]

template<typename T>

CParameter * make_param | ( | std::unique_ptr< T > & | value,
|  | const std::string & | init,
|  | bool | required,
|  | const char * | descr )

create a factory parameter that initializes to a std::unique_ptr

Creates a TFactoryParameter accurding to the given parameters. The advantage over calling the TactoryParameter cunstructor is that type deduction is done automatically.

Template Parameters

  the | type of the factory created parameter value

Parameters

  value | the unique_ptr value to be set through this parameter. Best is to pass an empty unique pointer and leave the initialization to the parameter handling
  init | the default initialization string for the parameter, pass "" if there is no default.
  required | set to true if the user must set this parameter
  descr | a help description of the parameter

Definition at line 640 of file parameter.hh.

References required.

## make_repeatable_opt()

template<typename T>

PCmdOption make_repeatable_opt | ( | std::vector< T > & | value,
|  | const char * | long_opt,
|  | char | short_opt,
|  | const char * | help,
|  | CCmdOptionFlags | flags = CCmdOptionFlags::none )

Create a repeatable option to set a vector of values.

The option can be given more than one time. The values are accumulated in the parameter vector.

Template Parameters

  T | type of the value hold by the vector

Parameters

  [in,out] | value | at input: if not empty, number of expected values and their defaults, at output: the values given on the command line
  | long_opt | long option name (must not be NULL)
  | short_opt | short option name (or 0)
  | help | help string (must not be NULL)
  | flags | option flags indicating whether the option is required

Remarks
  be aware that localization of the decimal separator of floating point values is not used, it is always the full stop ".".

Definition at line 483 of file cmdparamoption.hh.

References none.