DCMTK Version 3.7.0 OFFIS DICOM Toolkit

Public Types | Public Member Functions | Static Public Attributes | Protected Member Functions | Private Member Functions | Private Attributes | List of all members
OFCommandLine Class Reference

handles command line arguments. More...

## Public Types
enum | E_ParseStatus { PS_Normal , PS_NoArguments , PS_ExclusiveOption , PS_UnknownOption , PS_MissingValue , PS_MissingParameter , PS_TooManyParameters , PS_CannotOpenCommandFile }
| status of command line parsing More...
enum | E_ValueStatus { VS_Normal , VS_Invalid , VS_NoMore , VS_Empty , VS_Underflow , VS_Overflow }
| status of converting string option value to value field More...
enum | E_ParamValueStatus { PVS_Normal , PVS_Invalid , PVS_CantFind , PVS_Empty , PVS_Underflow , PVS_Overflow }
| status of converting string parameter to value field More...
enum | E_FindOptionMode { FOM_Normal , FOM_First , FOM_Next , FOM_FirstFromLeft , FOM_NextFromLeft }
| mode for findOption() method More...

## Public Member Functions
| OFCommandLine ()
| constructor
virtual | ~OFCommandLine ()
| destructor
void | setOptionChars (const char *chars)
| sets characters used to detect options More...
void | setOptionColumns (const int longCols, const int shortCols)
| sets default width of option columns More...
void | setParamColumn (const int column)
| sets default width of parameter column More...
void | addGeneralOptions (const int longCols=0, const int shortCols=0)
| generates all exclusive options in "general" group (top-level). More...
OFBool | addOption (const char *longOpt, const char *shortOpt, const int valueCount, const char *valueDescr, const char *optDescr, const int flags=0)
| adds an item to the list of valid options (full version) More...
OFBool | addOption (const char *longOpt, const char *shortOpt, const char *optDescr, const int flags=0)
| adds an item to the list of valid options (without additional values) More...
OFBool | addOption (const char *longOpt, const int valueCount, const char *valueDescr, const char *optDescr, const int flags=0)
| adds an item to the list of valid options (without short name) More...
OFBool | addOption (const char *longOpt, const char *optDescr, const int flags=0)
| adds an item to the list of valid options (without short name and additional values) More...
void | addGroup (const char *name, const int longCols=0, const int shortCols=0)
| adds a new group (top-level). More...
void | addSubGroup (const char *name, const int longCols=0, const int shortCols=0)
| adds a new subgroup (beyond group-level). More...
OFBool | addParam (const char *param, const char *descr, const OFCmdParam::E_ParamMode mode=OFCmdParam::PM_Mandatory)
| adds an item to the list of valid parameters (full version) More...
OFBool | addParam (const char *param, const OFCmdParam::E_ParamMode mode=OFCmdParam::PM_Mandatory)
| adds an item to the list of valid parameters (without description) More...
const OFString & | getProgramName () const
| get the name of the program (i.e. More...
int | getArgCount () const
| gets number of command line arguments. More...
OFBool | gotoFirstArg ()
| sets first command line argument as the current one. More...
OFBool | gotoNextArg ()
| sets next command line argument as the current one. More...
OFBool | getCurrentArg (const char *&arg)
| gets current command line argument as a C string This is the argument which is currently parsed or has been selected as the current one by gotoXXXArg(). More...
OFBool | getCurrentArg (OFCmdString &arg)
| gets current command line argument as a C++ string. More...
int | getParamCount () const
| gets number of parameters in the parsed command line. More...
int | getMinParamCount () const
| gets minimum number of parameters which should be accepted. More...
int | getMaxParamCount () const
| gets maximum number of parameters which should be accepted. More...
OFBool | hasExclusiveOption () const
| checks whether the parsed command line contains any "exclusive" option which does not require any mandatory parameter. More...
OFBool | getWideCharMode () const
| checks whether the wide character version of parseLine() has been used. More...
OFBool | findParam (const int pos)
| checks whether specified parameter exists in the command line. More...
E_ParamValueStatus | getParam (const int pos, OFCmdSignedInt &value)
| gets value of specified parameter as signed integer. More...
E_ParamValueStatus | getParamAndCheckMin (const int pos, OFCmdSignedInt &value, const OFCmdSignedInt low, const OFExplicitBool incl=OFTrue)
| get value of specified parameter as signed integer and checks for given boundary More...
E_ParamValueStatus | getParamAndCheckMinMax (const int pos, OFCmdSignedInt &value, const OFCmdSignedInt low, const OFCmdSignedInt high)
| gets value of specified parameter as signed integer and checks for given boundaries More...
E_ParamValueStatus | getParam (const int pos, OFCmdUnsignedInt &value)
| gets value of specified parameter as unsigned integer. More...
E_ParamValueStatus | getParamAndCheckMin (const int pos, OFCmdUnsignedInt &value, const OFCmdUnsignedInt low, const OFExplicitBool incl=OFTrue)
| gets value of specified parameter as unsigned integer and checks for given boundary. More...
E_ParamValueStatus | getParamAndCheckMinMax (const int pos, OFCmdUnsignedInt &value, const OFCmdUnsignedInt low, const OFCmdUnsignedInt high)
| gets value of specified parameter as unsigned integer and checks for given boundaries. More...
E_ParamValueStatus | getParam (const int pos, OFCmdFloat &value)
| gets value of specified parameter as floating point. More...
E_ParamValueStatus | getParamAndCheckMin (const int pos, OFCmdFloat &value, const OFCmdFloat low, const OFExplicitBool incl=OFTrue)
| gets value of specified parameter as floating point and checks for given boundary More...
E_ParamValueStatus | getParamAndCheckMinMax (const int pos, OFCmdFloat &value, const OFCmdFloat low, const OFCmdFloat high)
| gets value of specified parameter as floating point and checks for given boundaries More...
E_ParamValueStatus | getParam (const int pos, const char *&value)
| gets value of specified parameter as C string. More...
E_ParamValueStatus | getParam (const int pos, OFCmdString &value)
| gets value of specified parameter as C++ string. More...
E_ParamValueStatus | getParam (const int pos, OFFilename &filename)
| gets value of specified parameter as an instance of OFFilename. More...
OFBool | findOption (const char *longOpt, const signed int pos=0, const E_FindOptionMode mode=FOM_Normal)
| checks whether specified option exists in the command line. More...
OFBool | gotoFirstOption ()
| sets first command line option as the current one. More...
OFBool | gotoNextOption ()
| sets next command line option as the current one. More...
OFBool | getCurrentOption (const char *&opt)
| returns current option as a C string. More...
OFBool | getCurrentOption (OFCmdString &opt)
| returns current option as a C++ string. More...
void | beginOptionBlock ()
| starts an option block which can be used to support mutually exclusive options.
void | endOptionBlock ()
| ends an option block which can be used to support mutually exclusive options.
E_ValueStatus | getValue (OFCmdSignedInt &value)
| returns next argument as a signed integer value More...
E_ValueStatus | getValueAndCheckMin (OFCmdSignedInt &value, const OFCmdSignedInt low, const OFExplicitBool incl=OFTrue)
| returns next argument as a signed integer value and checks for given boundary More...
E_ValueStatus | getValueAndCheckMinMax (OFCmdSignedInt &value, const OFCmdSignedInt low, const OFCmdSignedInt high)
| returns next argument as a signed integer value and checks for given boundaries More...
E_ValueStatus | getValue (OFCmdUnsignedInt &value)
| returns next argument as an unsigned integer value More...
E_ValueStatus | getValueAndCheckMin (OFCmdUnsignedInt &value, const OFCmdUnsignedInt low, const OFExplicitBool incl=OFTrue)
| returns next argument as an unsigned integer value and checks for given boundary More...
E_ValueStatus | getValueAndCheckMinMax (OFCmdUnsignedInt &value, const OFCmdUnsignedInt low, const OFCmdUnsignedInt high)
| returns next argument as an unsigned integer value and checks for given boundaries More...
E_ValueStatus | getValue (OFCmdFloat &value)
| returns next argument as a floating point value More...
E_ValueStatus | getValueAndCheckMin (OFCmdFloat &value, const OFCmdFloat low, const OFExplicitBool incl=OFTrue)
| returns next argument as a floating point value and checks for given boundary More...
E_ValueStatus | getValueAndCheckMinMax (OFCmdFloat &value, const OFCmdFloat low, const OFCmdFloat high)
| returns next argument as a floating point value and checks for given boundaries More...
E_ValueStatus | getValue (const char *&value)
| returns next argument as a C string More...
E_ValueStatus | getValue (OFCmdString &value)
| returns next argument as a C++ string More...
E_ValueStatus | getValue (OFFilename &filename)
| returns next argument as an instance of OFFilename. More...
E_ParseStatus | parseLine (int argCount, char *argValue[], const int flags=0, const int startPos=1)
| parses specified command line arguments (argc, argv). More...
E_ParseStatus | parseLine (int argCount, wchar_t *argValue[], const int flags=0, const int startPos=1)
| parses specified command line arguments (argc, argv). More...
void | getSyntaxString (OFString &syntaxStr) const
| returns command line syntax as a C++ string (single text line). More...
void | getOptionString (OFString &optionStr) const
| returns description of all options as a C++ string (multiple text lines). More...
void | getParamString (OFString &paramStr) const
| returns description of all parameters as a C++ string (multiple text lines). More...
void | getStatusString (const E_ParseStatus status, OFString &statusStr)
| returns status of parseLine() as a C++ string More...
void | getStatusString (const E_ParamValueStatus status, OFString &statusStr)
| returns status of getParam() as a C++ string More...
void | getStatusString (const E_ValueStatus status, OFString &statusStr)
| returns status of getValue() as a C++ string More...

## Static Public Attributes
static const int | PF_ExpandWildcards
| parsing flag to expand wildcard under Windows. More...
static const int | PF_NoCommandFiles
| disable support for command files ("@filename") containing additional arguments
static const int | AF_Exclusive
| exclusive option that overrides any other option (e.g. "--help")
static const int | AF_Internal
| internal option that is not shown in the syntax usage output
static const int | AF_NoWarning
| do not output a warning message if option has never been checked. More...

## Protected Member Functions
OFBool | checkOption (const OFString &option, const OFBool mode=OFTrue) const
| checks whether given option is valid (starting with an option char and not followed by a number)
OFBool | findParam (const int pos, OFListIterator(OFCmdParamPos *) &pos_iter)
| finds specified parameter and sets given iterator to this position
const OFCmdOption * | findCmdOption (const OFString &option) const
| finds specified option and returns reference to its describing structure
void | storeParameter (const OFString &param, const int directOption=0)
| stores the specified parameter in the argument/parameter list
E_ParseStatus | parseArgumentList (OFList< OFString > &argList, const int flags)
| parse the given argument list and check it for known options/parameters
E_ParseStatus | parseCommandFile (const char *argValue, OFList< OFString > &argList)
| check whether 'argValue' points to command file and parse content if so
E_ParseStatus | parseCommandFile (const wchar_t *argValue, const OFString &strValue, OFList< OFString > &argList)
| check whether 'argValue' points to command file and parse content if so. More...
int | packColumnValues (int longCols, int shortCols) const
| packs the two 16 bit values into one 32 bit value
void | unpackColumnValues (const int value, unsigned int &longCols, unsigned int &shortCols) const
| unpacks two 16 bit values from one 32 bit value
E_ParseStatus | checkParamCount ()
| checks whether number of parameters in parsed command line is within the range of min/max (see below)
OFBool | getLastArg (OFString &arg)
| returns last command line argument as a C++ string
OFBool | getMissingParam (OFString &param)
| returns name of parameter which is missed in the parsed command line (used for error output)

## Private Member Functions
| OFListIterator (OFString) ArgumentIterator
| current position in argument list
| OFListIterator (OFCmdParamPos *) ParamPosIterator
| current position in param position list (iterator)
| OFListIterator (OFListIterator_OFString) OptionPosIterator
| current position in option position list
| OFListIterator (OFListIterator_OFString) OptionBlockIterator
| current position in option position list (used for option blocks)
| OFCommandLine (const OFCommandLine &obj)
| private undefined copy constructor
OFCommandLine & | operator= (const OFCommandLine &obj)
| private undefined assignment operator

## Private Attributes
OFString | ProgramName
| program name, i.e. the value of argv[0]
OFList< OFCmdOption * > | ValidOptionList
| list of valid/defined command line options
OFList< OFCmdParam * > | ValidParamList
| list of valid/defined command line parameters
OFList< OFString > | ArgumentList
| list of command line arguments (after parsing)
OFList< OFCmdParamPos * > | ParamPosList
| list of parameter positions within argument list
int | ParamPosNumber
| current position in param position list (numeric value)
OFList< OFListIterator_OFString > | OptionPosList
| list of option positions within argument list
OFBool | OptionBlockMode
| OFTrue if option block is active, OFFalse otherwise.
OFString | OptionChars
| C++ string consisting of all valid characters introducing an option.
OFBool | ExclusiveOption
| OFTrue if an "exclusive" option is used in the command line, OFFalse otherwise.
OFBool | WideCharMode
| OFTrue if wide character version of parseLine() has been used, OFFalse otherwise.
int | LongColumn
| width of column for long option names
int | ShortColumn
| width of column for short option names
int | ParamColumn
| width of column for parameter names
int | MinParamCount
| minimum number of parameters which should be accepted
int | MaxParamCount
| maximum number of parameter which should be accepted
OFCmdParam::E_ParamMode | LastParamMode
| mode of last added parameter (used for debug checking)

## Detailed Description

handles command line arguments.

This class is the interface to this module. All methods which can be used from outside are defined here.

## Member Enumeration Documentation

## ◆ E_FindOptionMode

enum OFCommandLine::E_FindOptionMode

mode for findOption() method

Enumerator
FOM_Normal | normal find
FOM_First | find first option
FOM_Next | find next option
FOM_FirstFromLeft | find first option (from left to right)
FOM_NextFromLeft | find next option (from left to right)

## ◆ E_ParamValueStatus

enum OFCommandLine::E_ParamValueStatus

status of converting string parameter to value field

Enumerator
PVS_Normal | normal, no errors
PVS_Invalid | argument contains invalid char(s)
PVS_CantFind | specified parameter doesn't exist
PVS_Empty | empty string argument
PVS_Underflow | converted value falls below minimum
PVS_Overflow | converted value exceeds maximum

## ◆ E_ParseStatus

enum OFCommandLine::E_ParseStatus

status of command line parsing

Enumerator
PS_Normal | normal, no errors
PS_NoArguments | no arguments to be parsed
PS_ExclusiveOption | exclusive option used
PS_UnknownOption | unknown option detected
PS_MissingValue | missing value(s) for an option
PS_MissingParameter | missing parameter
PS_TooManyParameters | too many parameters
PS_CannotOpenCommandFile | cannot open command file

## ◆ E_ValueStatus

enum OFCommandLine::E_ValueStatus

status of converting string option value to value field

Enumerator
VS_Normal | normal, no errors
VS_Invalid | argument contains invalid char(s)
VS_NoMore | no more arguments to be converted
VS_Empty | empty string argument
VS_Underflow | converted value falls below minimum
VS_Overflow | converted value exceeds maximum

## Member Function Documentation

## ◆ addGeneralOptions()

void OFCommandLine::addGeneralOptions | ( | const int | longCols = `0`,
|  | const int | shortCols = `0`
| ) |  |

generates all exclusive options in "general" group (top-level).

The following options belong to this group:

- –help (-h): prints the help text and exits
- –version: prints version information and exit

Parameters

  longCols | minimum width of the long option column
  shortCols | minimum width of the short option column

## ◆ addGroup()

void OFCommandLine::addGroup | ( | const char * | name,
|  | const int | longCols = `0`,
|  | const int | shortCols = `0`
| ) |  |

adds a new group (top-level).

all following options belong to this group

Parameters

  name | name of the group
  longCols | minimum width of the long option column
  shortCols | minimum width of the short option column

## ◆ addOption() [1/4]

OFBool OFCommandLine::addOption | ( | const char * | longOpt,
|  | const char * | optDescr,
|  | const int | flags = `0`
| ) |  |

adds an item to the list of valid options (without short name and additional values)

Parameters

  longOpt | long option name
  optDescr | description of command line option (use '\n' for line break)
  flags | optional flags (see AF_xxx below)

Returns
  OFTrue if successfully added

## ◆ addOption() [2/4]

OFBool OFCommandLine::addOption | ( | const char * | longOpt,
|  | const char * | shortOpt,
|  | const char * | optDescr,
|  | const int | flags = `0`
| ) |  |

adds an item to the list of valid options (without additional values)

Parameters

  longOpt | long option name
  shortOpt | short option name
  optDescr | description of command line option (use '\n' for line break)
  flags | optional flags (see AF_xxx below)

Returns
  OFTrue if successfully added

## ◆ addOption() [3/4]

OFBool OFCommandLine::addOption | ( | const char * | longOpt,
|  | const char * | shortOpt,
|  | const int | valueCount,
|  | const char * | valueDescr,
|  | const char * | optDescr,
|  | const int | flags = `0`
| ) |  |

adds an item to the list of valid options (full version)

Parameters

  longOpt | long option name
  shortOpt | short option name
  valueCount | number of additional values
  valueDescr | description of optional values
  optDescr | description of command line option (use '\n' for line break)
  flags | optional flags (see AF_xxx below)

Returns
  OFTrue if successfully added

## ◆ addOption() [4/4]

OFBool OFCommandLine::addOption | ( | const char * | longOpt,
|  | const int | valueCount,
|  | const char * | valueDescr,
|  | const char * | optDescr,
|  | const int | flags = `0`
| ) |  |

adds an item to the list of valid options (without short name)

Parameters

  longOpt | long option name
  valueCount | number of additional values
  valueDescr | description of optional values
  optDescr | description of command line option (use '\n' for line break)
  flags | optional flags (see AF_xxx below)

Returns
  OFTrue if successfully added

## ◆ addParam() [1/2]

OFBool OFCommandLine::addParam | ( | const char * | param,
|  | const char * | descr,
|  | const OFCmdParam::E_ParamMode | mode = `OFCmdParam::PM_Mandatory`
| ) |  |

adds an item to the list of valid parameters (full version)

Parameters

  param | parameter name
  descr | parameter description (use '\n' for line break)
  mode | parameter's cardinality (see above)

Returns
  OFTrue if successful, OFFalse otherwise

## ◆ addParam() [2/2]

OFBool OFCommandLine::addParam | ( | const char * | param,
|  | const OFCmdParam::E_ParamMode | mode = `OFCmdParam::PM_Mandatory`
| ) |  |

adds an item to the list of valid parameters (without description)

Parameters

  param | parameter name
  mode | parameter's cardinality (see above)

Returns
  OFTrue if successful, OFFalse otherwise

## ◆ addSubGroup()

void OFCommandLine::addSubGroup | ( | const char * | name,
|  | const int | longCols = `0`,
|  | const int | shortCols = `0`
| ) |  |

adds a new subgroup (beyond group-level).

all following options belong to this subgroup

Parameters

  name | name of the subgroup
  longCols | minimum width of the long option column
  shortCols | minimum width of the short option column

## ◆ findOption()

OFBool OFCommandLine::findOption | ( | const char * | longOpt,
|  | const signed int | pos = `0`,
|  | const E_FindOptionMode | mode = `FOM_Normal`
| ) |  |

checks whether specified option exists in the command line.

The search process starts from the last command line argument (which is a direct predecessor of the optional defined reference parameter 'pos') and goes to the first one.

Parameters

  longOpt | name of option (in long format) to be checked
  pos | position of reference parameter (default: all parameters; if value is negative option must be a direct predecessor of the specified reference parameter '-pos', no further search processes will be performed; if search direction is left to right this parameter is ignored, also option blocks are not supported in this case)
  mode | find option mode (used to support option blocks and reverse search direction)

Returns
  OFTrue if option exists, OFFalse otherwise

## ◆ findParam()

OFBool OFCommandLine::findParam | ( | const int | pos | ) |

checks whether specified parameter exists in the command line.

Parameters

  pos | position of parameter to be checked (1..n)

Returns
  OFTrue if parameter exists, false otherwise

## ◆ getArgCount()

int OFCommandLine::getArgCount | ( |  | ) | const
| inline

gets number of command line arguments.

(options and parameters)

Returns
  number of command line arguments

## ◆ getCurrentArg() [1/2]

OFBool OFCommandLine::getCurrentArg | ( | const char *& | arg | ) |

gets current command line argument as a C string This is the argument which is currently parsed or has been selected as the current one by gotoXXXArg().

Parameters

  arg | reference to C string where argument should be stored

Returns
  OFTrue if successful, OFFalse otherwise

## ◆ getCurrentArg() [2/2]

OFBool OFCommandLine::getCurrentArg | ( | OFCmdString & | arg | ) |

gets current command line argument as a C++ string.

This is the argument which is currently parsed or has been selected as the current one by gotoXXXArg().

Parameters

  arg | reference to C++ string where argument should be stored

Returns
  OFTrue if successful, OFFalse otherwise

## ◆ getCurrentOption() [1/2]

OFBool OFCommandLine::getCurrentOption | ( | const char *& | opt | ) |

returns current option as a C string.

This is the option which has currently been parsed (e.g. used for error output) or which has been selected as the current one by gotoXXXOption().

Parameters

  opt | reference to C string where option should be stored

Returns
  OFTrue if there is a current option, OFFalse otherwise

## ◆ getCurrentOption() [2/2]

OFBool OFCommandLine::getCurrentOption | ( | OFCmdString & | opt | ) |

returns current option as a C++ string.

This is the option which has currently been parsed (e.g. used for error output) or which has been selected as the current one by gotoXXXOption().

Parameters

  opt | reference to C++ string where option should be stored

Returns
  OFTrue if there is a current option, OFFalse otherwise

## ◆ getMaxParamCount()

int OFCommandLine::getMaxParamCount | ( |  | ) | const
| inline

gets maximum number of parameters which should be accepted.

Returns
  number of parameters

## ◆ getMinParamCount()

int OFCommandLine::getMinParamCount | ( |  | ) | const
| inline

gets minimum number of parameters which should be accepted.

Returns
  number of parameters

## ◆ getOptionString()

void OFCommandLine::getOptionString | ( | OFString & | optionStr | ) | const

returns description of all options as a C++ string (multiple text lines).

Text consists of group headings, short and long option names, option descriptions and additional option values.

Parameters

  optionStr | reference to C++ string where the text should be stored

## ◆ getParam() [1/6]

E_ParamValueStatus OFCommandLine::getParam | ( | const int | pos,
|  | const char *& | value
| ) |  |

gets value of specified parameter as C string.

Parameters

  pos | position of parameter (1..n)
  value | reference to variable where the value should be stored

Returns
  status of get/conversion, PVS_Normal if successful (use getStatusString() for error string)

## ◆ getParam() [2/6]

E_ParamValueStatus OFCommandLine::getParam | ( | const int | pos,
|  | OFCmdFloat & | value
| ) |  |

gets value of specified parameter as floating point.

Parameters

  pos | position of parameter (1..n)
  value | reference to variable where the value should be stored

Returns
  status of get/conversion, PVS_Normal if successful (use getStatusString() for error string)

## ◆ getParam() [3/6]

E_ParamValueStatus OFCommandLine::getParam | ( | const int | pos,
|  | OFCmdSignedInt & | value
| ) |  |

gets value of specified parameter as signed integer.

Parameters

  pos | position of parameter (1..n)
  value | reference to variable where the value should be stored

Returns
  status of get/conversion, PVS_Normal if successful (use getStatusString() for error string)

## ◆ getParam() [4/6]

E_ParamValueStatus OFCommandLine::getParam | ( | const int | pos,
|  | OFCmdString & | value
| ) |  |

gets value of specified parameter as C++ string.

Parameters

  pos | position of parameter (1..n)
  value | reference to variable where the value should be stored

Returns
  status of get/conversion, PVS_Normal if successful (use getStatusString() for error string)

## ◆ getParam() [5/6]

E_ParamValueStatus OFCommandLine::getParam | ( | const int | pos,
|  | OFCmdUnsignedInt & | value
| ) |  |

gets value of specified parameter as unsigned integer.

NB: If command line argument specifies a negative value the result depends on the signed->unsigned conversion implemented in sscanf() !!

Parameters

  pos | position of parameter (1..n)
  value | reference to variable where the value should be stored

Returns
  status of get/conversion, PVS_Normal if successful (use getStatusString() for error string)

## ◆ getParam() [6/6]

E_ParamValueStatus OFCommandLine::getParam | ( | const int | pos,
|  | OFFilename & | filename
| ) |  |

gets value of specified parameter as an instance of OFFilename.

Please note that on Windows systems the returned filename might also contain a wide character version (UTF-16) as an alternative representation. See getWideCharMode().

Parameters

  pos | position of parameter (1..n)
  filename | reference to variable where the value should be stored

Returns
  status of get/conversion, PVS_Normal if successful (use getStatusString() for error string)

## ◆ getParamAndCheckMin() [1/3]

E_ParamValueStatus OFCommandLine::getParamAndCheckMin | ( | const int | pos,
|  | OFCmdFloat & | value,
|  | const OFCmdFloat | low,
|  | const OFExplicitBool | incl = `OFTrue`
| ) |  |

gets value of specified parameter as floating point and checks for given boundary

Parameters

  pos | position of parameter (1..n)
  value | reference to variable where the value should be stored
  low | minimum boundary for value (used for range check)
  incl | if OFTrue 'low' value is valid (included), otherwise invalid

Returns
  status of get/conversion, PVS_Normal if successful (use getStatusString() for error string)

## ◆ getParamAndCheckMin() [2/3]

E_ParamValueStatus OFCommandLine::getParamAndCheckMin | ( | const int | pos,
|  | OFCmdSignedInt & | value,
|  | const OFCmdSignedInt | low,
|  | const OFExplicitBool | incl = `OFTrue`
| ) |  |

get value of specified parameter as signed integer and checks for given boundary

Parameters

  pos | position of parameter (1..n)
  value | reference to variable where the value should be stored
  low | minimum boundary for value (used for range check)
  incl | if OFTrue 'low' value is valid (included), otherwise invalid

Returns
  status of get/conversion, PVS_Normal if successful (use getStatusString() for error string)

## ◆ getParamAndCheckMin() [3/3]

E_ParamValueStatus OFCommandLine::getParamAndCheckMin | ( | const int | pos,
|  | OFCmdUnsignedInt & | value,
|  | const OFCmdUnsignedInt | low,
|  | const OFExplicitBool | incl = `OFTrue`
| ) |  |

gets value of specified parameter as unsigned integer and checks for given boundary.

NB: If command line argument specifies a negative value the result depends on the signed->unsigned conversion implemented in sscanf() !!

Parameters

  pos | position of parameter (1..n)
  value | reference to variable where the value should be stored
  low | minimum boundary for value (used for range check)
  incl | if OFTrue 'low' value is valid (included), otherwise invalid

Returns
  status of get/conversion, PVS_Normal if successful (use getStatusString() for error string)

## ◆ getParamAndCheckMinMax() [1/3]

E_ParamValueStatus OFCommandLine::getParamAndCheckMinMax | ( | const int | pos,
|  | OFCmdFloat & | value,
|  | const OFCmdFloat | low,
|  | const OFCmdFloat | high
| ) |  |

gets value of specified parameter as floating point and checks for given boundaries

Parameters

  pos | position of parameter (1..n)
  value | reference to variable where the value should be stored
  low | minimum boundary for value (used for range check, boundary included)
  high | maximum boundary for value (ditto)

Returns
  status of get/conversion, PVS_Normal if successful (use getStatusString() for error string)

## ◆ getParamAndCheckMinMax() [2/3]

E_ParamValueStatus OFCommandLine::getParamAndCheckMinMax | ( | const int | pos,
|  | OFCmdSignedInt & | value,
|  | const OFCmdSignedInt | low,
|  | const OFCmdSignedInt | high
| ) |  |

gets value of specified parameter as signed integer and checks for given boundaries

Parameters

  pos | position of parameter (1..n)
  value | reference to variable where the value should be stored
  low | minimum boundary for value (used for range check, boundary included)
  high | maximum boundary for value (ditto)

Returns
  status of get/conversion, PVS_Normal if successful (use getStatusString() for error string)

## ◆ getParamAndCheckMinMax() [3/3]

E_ParamValueStatus OFCommandLine::getParamAndCheckMinMax | ( | const int | pos,
|  | OFCmdUnsignedInt & | value,
|  | const OFCmdUnsignedInt | low,
|  | const OFCmdUnsignedInt | high
| ) |  |

gets value of specified parameter as unsigned integer and checks for given boundaries.

NB: If command line argument specifies a negative value the result depends on the signed->unsigned conversion implemented in sscanf() !!

Parameters

  pos | position of parameter (1..n)
  value | reference to variable where the value should be stored
  low | minimum boundary for value (used for range check, boundary included)
  high | maximum boundary for value (ditto)

Returns
  status of get/conversion, PVS_Normal if successful (use getStatusString() for error string)

## ◆ getParamCount()

int OFCommandLine::getParamCount | ( |  | ) | const
| inline

gets number of parameters in the parsed command line.

A parameter is an argument which is no option (e.g. a filename).

Returns
  number of parameters

Referenced by OFTestManager::buildTestsToRun().

## ◆ getParamString()

void OFCommandLine::getParamString | ( | OFString & | paramStr | ) | const

returns description of all parameters as a C++ string (multiple text lines).

Text consists of heading "parameters:" and parameter names and descriptions.

Parameters

  paramStr | reference to C++ string where the text should be stored

## ◆ getProgramName()

const OFString& OFCommandLine::getProgramName | ( |  | ) | const
| inline

get the name of the program (i.e.

the value of argv[0])

Returns
  name of the program

## ◆ getStatusString() [1/3]

void OFCommandLine::getStatusString | ( | const E_ParamValueStatus | status,
|  | OFString & | statusStr
| ) |  |

returns status of getParam() as a C++ string

Parameters

  status | value returned by method getParam()
  statusStr | reference to C++string where the text should be stored

## ◆ getStatusString() [2/3]

void OFCommandLine::getStatusString | ( | const E_ParseStatus | status,
|  | OFString & | statusStr
| ) |  |

returns status of parseLine() as a C++ string

Parameters

  status | value returned by method parseLine()
  statusStr | reference to C++string where the text should be stored

## ◆ getStatusString() [3/3]

void OFCommandLine::getStatusString | ( | const E_ValueStatus | status,
|  | OFString & | statusStr
| ) |  |

returns status of getValue() as a C++ string

Parameters

  status | value returned by method getValue()
  statusStr | reference to C++string where the text should be stored

## ◆ getSyntaxString()

void OFCommandLine::getSyntaxString | ( | OFString & | syntaxStr | ) | const

returns command line syntax as a C++ string (single text line).

Text consists of "[options]" (if defined by addOption()) and all parameters defined by addParam().

Parameters

  syntaxStr | reference to C++ string where the text should be stored

## ◆ getValue() [1/6]

E_ValueStatus OFCommandLine::getValue | ( | const char *& | value | ) |

returns next argument as a C string

Parameters

  value | reference to C string variable where the value should be stored

Returns
  status of get/conversion, VS_Normal if successful (use getStatusString() for error string)

## ◆ getValue() [2/6]

E_ValueStatus OFCommandLine::getValue | ( | OFCmdFloat & | value | ) |

returns next argument as a floating point value

Parameters

  value | reference to floating point variable where the value should be stored

Returns
  status of get/conversion, VS_Normal if successful (use getStatusString() for error string)

## ◆ getValue() [3/6]

E_ValueStatus OFCommandLine::getValue | ( | OFCmdSignedInt & | value | ) |

returns next argument as a signed integer value

Parameters

  value | reference to signed integer variable where the value should be stored

Returns
  status of get/conversion, VS_Normal if successful (use getStatusString() for error string)

## ◆ getValue() [4/6]

E_ValueStatus OFCommandLine::getValue | ( | OFCmdString & | value | ) |

returns next argument as a C++ string

Parameters

  value | reference to C++ string variable where the value should be stored

Returns
  status of get/conversion, VS_Normal if successful (use getStatusString() for error string)

## ◆ getValue() [5/6]

E_ValueStatus OFCommandLine::getValue | ( | OFCmdUnsignedInt & | value | ) |

returns next argument as an unsigned integer value

Parameters

  value | reference to unsigned integer variable where the value should be stored

Returns
  status of get/conversion, VS_Normal if successful (use getStatusString() for error string)

## ◆ getValue() [6/6]

E_ValueStatus OFCommandLine::getValue | ( | OFFilename & | filename | ) |

returns next argument as an instance of OFFilename.

Please note that on Windows systems the returned filename might also contain a wide character version (UTF-16) as an alternative representation. See getWideCharMode().

Parameters

  filename | reference to variable where the value should be stored

Returns
  status of get/conversion, VS_Normal if successful (use getStatusString() for error string)

## ◆ getValueAndCheckMin() [1/3]

E_ValueStatus OFCommandLine::getValueAndCheckMin | ( | OFCmdFloat & | value,
|  | const OFCmdFloat | low,
|  | const OFExplicitBool | incl = `OFTrue`
| ) |  |

returns next argument as a floating point value and checks for given boundary

Parameters

  value | reference to floating point variable where the value should be stored
  low | minimum boundary for value (used for range check)
  incl | if OFTrue 'low' value is valid (included), otherwise invalid

Returns
  status of get/conversion, VS_Normal if successful (use getStatusString() for error string)

## ◆ getValueAndCheckMin() [2/3]

E_ValueStatus OFCommandLine::getValueAndCheckMin | ( | OFCmdSignedInt & | value,
|  | const OFCmdSignedInt | low,
|  | const OFExplicitBool | incl = `OFTrue`
| ) |  |

returns next argument as a signed integer value and checks for given boundary

Parameters

  value | reference to signed integer variable where the value should be stored
  low | minimum boundary for value (used for range check)
  incl | if OFTrue 'low' value is valid (included), otherwise invalid

Returns
  status of get/conversion, VS_Normal if successful (use getStatusString() for error string)

## ◆ getValueAndCheckMin() [3/3]

E_ValueStatus OFCommandLine::getValueAndCheckMin | ( | OFCmdUnsignedInt & | value,
|  | const OFCmdUnsignedInt | low,
|  | const OFExplicitBool | incl = `OFTrue`
| ) |  |

returns next argument as an unsigned integer value and checks for given boundary

Parameters

  value | reference to unsigned integer variable where the value should be stored
  low | minimum boundary for value (used for range check)
  incl | if OFTrue 'low' value is valid (included), otherwise invalid

Returns
  status of get/conversion, VS_Normal if successful (use getStatusString() for error string)

## ◆ getValueAndCheckMinMax() [1/3]

E_ValueStatus OFCommandLine::getValueAndCheckMinMax | ( | OFCmdFloat & | value,
|  | const OFCmdFloat | low,
|  | const OFCmdFloat | high
| ) |  |

returns next argument as a floating point value and checks for given boundaries

Parameters

  value | reference to floating point variable where the value should be stored
  low | minimum boundary for value (used for range check, boundary included)
  high | maximum boundary for value (ditto)

Returns
  status of get/conversion, VS_Normal if successful (use getStatusString() for error string)

## ◆ getValueAndCheckMinMax() [2/3]

E_ValueStatus OFCommandLine::getValueAndCheckMinMax | ( | OFCmdSignedInt & | value,
|  | const OFCmdSignedInt | low,
|  | const OFCmdSignedInt | high
| ) |  |

returns next argument as a signed integer value and checks for given boundaries

Parameters

  value | reference to signed integer variable where the value should be stored
  low | minimum boundary for value (used for range check, boundary included)
  high | maximum boundary for value (ditto)

Returns
  status of get/conversion, VS_Normal if successful (use getStatusString() for error string)

## ◆ getValueAndCheckMinMax() [3/3]

E_ValueStatus OFCommandLine::getValueAndCheckMinMax | ( | OFCmdUnsignedInt & | value,
|  | const OFCmdUnsignedInt | low,
|  | const OFCmdUnsignedInt | high
| ) |  |

returns next argument as an unsigned integer value and checks for given boundaries

Parameters

  value | reference to unsigned integer variable where the value should be stored
  low | minimum boundary for value (used for range check, boundary included)
  high | maximum boundary for value (ditto)

Returns
  status of get/conversion, VS_Normal if successful (use getStatusString() for error string)

## ◆ getWideCharMode()

OFBool OFCommandLine::getWideCharMode | ( |  | ) | const
| inline

checks whether the wide character version of parseLine() has been used.

Support for wide character encoding is Windows-specific (i.e. UTF-16) because other operating systems use UTF-8 for Unicode support.

Returns
  OFTrue if wide char version of parseLine() has been used, OFFalse otherwise

## ◆ gotoFirstArg()

OFBool OFCommandLine::gotoFirstArg | ( |  | ) |

sets first command line argument as the current one.

Useful for iterating over all arguments.

Returns
  OFTrue if successful, OFFalse otherwise

## ◆ gotoFirstOption()

OFBool OFCommandLine::gotoFirstOption | ( |  | ) |

sets first command line option as the current one.

Useful for iterating over all options.

Returns
  OFTrue if successful, OFFalse otherwise

## ◆ gotoNextArg()

OFBool OFCommandLine::gotoNextArg | ( |  | ) |

sets next command line argument as the current one.

Useful for iterating over all arguments.

Returns
  OFTrue if successful, OFFalse otherwise

## ◆ gotoNextOption()

OFBool OFCommandLine::gotoNextOption | ( |  | ) |

sets next command line option as the current one.

Useful for iterating over all options.

Returns
  OFTrue if successful, OFFalse otherwise

## ◆ hasExclusiveOption()

OFBool OFCommandLine::hasExclusiveOption | ( |  | ) | const
| inline

checks whether the parsed command line contains any "exclusive" option which does not require any mandatory parameter.

Examples for typical exclusive options are "--help" and "--version".

Returns
  OFTrue if an exclusive option is used, OFFalse otherwise

## ◆ parseCommandFile()

E_ParseStatus OFCommandLine::parseCommandFile | ( | const wchar_t * | argValue,
|  | const OFString & | strValue,
|  | OFList< OFString > & | argList
| ) |  |
| protected

check whether 'argValue' points to command file and parse content if so.

This is a Windows-specific version supporting wide char encoding (UTF-16).

Remarks
  this method is only available if OS is windows (not mingw) and MSC6 is not used for building.

## ◆ parseLine() [1/2]

E_ParseStatus OFCommandLine::parseLine | ( | int | argCount,
|  | char * | argValue[],
|  | const int | flags = `0`,
|  | const int | startPos = `1`
| ) |  |

parses specified command line arguments (argc, argv).

Sets 'WideCharMode' to OFFalse. Additionally, create internal structures for evaluation and return status indicating any errors that occurred during the parse process.

Parameters

  argCount | number of command line arguments stored in argValue
  argValue | array where the command line arguments are stored
  flags | optional flags affecting the parse process (see PF_xxx below)
  startPos | index of first argument which should be parsed (starting from 0, default: 1)

Returns
  status of parse process, PS_Normal if successful (use getStatusString() for error string). If an exclusive option is used, the status code PS_ExclusiveOption is returned.

## ◆ parseLine() [2/2]

E_ParseStatus OFCommandLine::parseLine | ( | int | argCount,
|  | wchar_t * | argValue[],
|  | const int | flags = `0`,
|  | const int | startPos = `1`
| ) |  |

parses specified command line arguments (argc, argv).

Sets 'WideCharMode' to OFTrue. This is a Windows-specific version supporting the wide character encoding (UTF-16). Internally, all character strings are stored in UTF-8, because this Unicode encoding is supported by DICOM. However, there are getValue() and getParam() methods that allow for accessing filenames with wide character encoding (UTF-16). Additionally, create internal structures for evaluation and return status indicating any errors that occurred during the parse process.

Remarks
  this method is only available if OS is windows (not mingw) and MSC6 is not used for building.

Parameters

  argCount | number of command line arguments stored in argValue
  argValue | array where the command line arguments are stored
  flags | optional flags affecting the parse process (see PF_xxx below)
  startPos | index of first argument which should be parsed (starting from 0, default: 1)

Returns
  status of parse process, PS_Normal if successful (use getStatusString() for error string). If an exclusive option is used, the status code PS_ExclusiveOption is returned.

## ◆ setOptionChars()

void OFCommandLine::setOptionChars | ( | const char * | chars | ) |

sets characters used to detect options

Parameters

  chars | string containing all valid option characters (default: "+-")

## ◆ setOptionColumns()

void OFCommandLine::setOptionColumns | ( | const int | longCols,
|  | const int | shortCols
| ) |  |

sets default width of option columns

Parameters

  longCols | minimum width of the long option column
  shortCols | minimum width of the short option column

## ◆ setParamColumn()

void OFCommandLine::setParamColumn | ( | const int | column | ) |

sets default width of parameter column

Parameters

  column | minimum width of the long option column

## Member Data Documentation

## ◆ AF_NoWarning

const int OFCommandLine::AF_NoWarning
| static

do not output a warning message if option has never been checked.

(useful if option is only checked depending on another option)

## ◆ PF_ExpandWildcards

const int OFCommandLine::PF_ExpandWildcards
| static

parsing flag to expand wildcard under Windows.

(not used anymore, only available for reasons of backward compatibility; link 'setargv.obj' to your program if you need wildcard expansion.)

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

- ofstd/include/dcmtk/ofstd/ofcmdln.h

Generated on Mon Dec 15 2025 for DCMTK Version 3.7.0 by Doxygen 1.9.1