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 *	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() [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 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

◆ addOption() [4/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

◆ 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,
		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() [2/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() [3/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() [4/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() [5/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() [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,
		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() [2/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)

◆ getParamAndCheckMin() [3/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)

◆ getParamAndCheckMinMax() [1/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() [2/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)

◆ getParamAndCheckMinMax() [3/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)

◆ 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_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() [2/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() [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 ( 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() [2/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() [3/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() [4/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() [5/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() [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	(	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() [2/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)

◆ getValueAndCheckMin() [3/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)

◆ getValueAndCheckMinMax() [1/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() [2/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)

◆ getValueAndCheckMinMax() [3/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)

◆ 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

Public Types

Public Member Functions

Static Public Attributes

Protected Member Functions

Private Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

◆ E_FindOptionMode

◆ E_ParamValueStatus

◆ E_ParseStatus

◆ E_ValueStatus

Member Function Documentation

◆ addGeneralOptions()

◆ addGroup()

◆ addOption() [1/4]

◆ addOption() [2/4]

◆ addOption() [3/4]

◆ addOption() [4/4]

◆ addParam() [1/2]

◆ addParam() [2/2]

◆ addSubGroup()

◆ findOption()

◆ findParam()

◆ getArgCount()

◆ getCurrentArg() [1/2]

◆ getCurrentArg() [2/2]

◆ getCurrentOption() [1/2]

◆ getCurrentOption() [2/2]

◆ getMaxParamCount()

◆ getMinParamCount()

◆ getOptionString()

◆ getParam() [1/6]

◆ getParam() [2/6]

◆ getParam() [3/6]

◆ getParam() [4/6]

◆ getParam() [5/6]

◆ getParam() [6/6]

◆ getParamAndCheckMin() [1/3]

◆ getParamAndCheckMin() [2/3]

◆ getParamAndCheckMin() [3/3]

◆ getParamAndCheckMinMax() [1/3]

◆ getParamAndCheckMinMax() [2/3]

◆ getParamAndCheckMinMax() [3/3]

◆ getParamCount()

◆ getParamString()

◆ getProgramName()

◆ getStatusString() [1/3]

◆ getStatusString() [2/3]

◆ getStatusString() [3/3]

◆ getSyntaxString()

◆ getValue() [1/6]

◆ getValue() [2/6]

◆ getValue() [3/6]

◆ getValue() [4/6]

◆ getValue() [5/6]

◆ getValue() [6/6]

◆ getValueAndCheckMin() [1/3]

◆ getValueAndCheckMin() [2/3]

◆ getValueAndCheckMin() [3/3]

◆ getValueAndCheckMinMax() [1/3]

◆ getValueAndCheckMinMax() [2/3]

◆ getValueAndCheckMinMax() [3/3]

◆ getWideCharMode()

◆ gotoFirstArg()

◆ gotoFirstOption()

◆ gotoNextArg()

◆ gotoNextOption()

◆ hasExclusiveOption()

◆ parseCommandFile()

◆ parseLine() [1/2]

◆ parseLine() [2/2]

◆ setOptionChars()

◆ setOptionColumns()

◆ setParamColumn()

Member Data Documentation

◆ AF_NoWarning

◆ PF_ExpandWildcards