This class implements a manager for command arguments. More...

Data Structures
class	Manager
	This class implements a simple singleton holding the raw application's command arguments. More...

class	Parameter
	This class defines a named value with long and short name, with default parameter and description. More...

Public Types
template<typename T >
using	ArgumentT = std::basic_string< T >
	Definition of a string with either `char` or `wchar_t`. More...

template<typename T >
using	ArgumentsT = std::vector< ArgumentT< T > >
	Definition of a vector holding strings with either `char` or `wchar_t`. More...

Public Member Functions
	CommandArguments ()
	Creates a new object. More...

	CommandArguments (const std::string &applicationDescription)
	Creates a new object with a description of the application. More...

bool	registerParameter (const std::string &longName, const std::string &shortName=std::string(), const std::string &description=std::string(), const Value &defaultValue=Value())
	Registers a new named parameter which can be parsed as command argument. More...

bool	registerNamelessParameters (std::string &&description)
	Registers nameless parameters for the summary. More...

template<typename TChar >
bool	parse (const TChar *commandLine)
	Parses A given command line. More...

template<typename TChar >
bool	parse (const TChar const arguments, const size_t size, const bool skipFirstArgument=true)
	Parses the several command arguments. More...

bool	parse (const ArgumentsT< char > &separatedArguments)
	Parses the command arguments already separated into individual arguments. More...

bool	parse (const ArgumentsT< wchar_t > &separatedArguments)
	Parses the command arguments already separated into individual arguments. More...

Value	value (const std::string &longName, const bool allowDefaultValue=true, const size_t namelessValueIndex=size_t(-1)) const
	Returns the value of a specific parameter which has been parsed. More...

template<typename T >
T	value (const std::string &longName, const T &invalidValue, const bool allowDefaultValue, const size_t namelessValueIndex=size_t(-1)) const
	Returns the value of a specific parameter which has been parsed. More...

bool	hasValue (const std::string &longName, Value *value=nullptr, const bool allowDefaultValue=true, const size_t namelessValueIndex=size_t(-1)) const
	Checks whether a specific parameter value has been parsed, or whether a default value is defined. More...

template<typename T >
bool	hasValue (const std::string &longName, T &value, const bool allowDefaultValue=true, const size_t namelessValueIndex=size_t(-1)) const
	Checks whether a specific parameter value has been parsed with specific data type, or whether a default value is defined. More...

const std::vector< std::string > &	namelessValues () const
	Returns all nameless values which have been parsed. More...

std::string	makeSummary ()
	Creates a summary of all possible command arguments. More...

template<>
bool	parse (const wchar_t *commandLine)

template<>
bool	hasValue (const std::string &longName, bool &boolValue, const bool allowDefaultValue, const size_t namelessValueIndex) const

template<>
bool	hasValue (const std::string &longName, int32_t &intValue, const bool allowDefaultValue, const size_t namelessValueIndex) const

template<>
bool	hasValue (const std::string &longName, double &doubleValue, const bool allowDefaultValue, const size_t namelessValueIndex) const

template<>
bool	hasValue (const std::string &longName, std::string &stringValue, const bool allowDefaultValue, const size_t namelessValueIndex) const

Static Public Member Functions
template<typename TChar >
static ArgumentsT< TChar >	separateArguments (const TChar *commandLine)
	Parses the command line and returns the individual command elements. More...

Protected Types
typedef std::map< std::string, Parameter >	ParameterMap
	Definition of a map mapping long parameter names to parameter objects. More...

typedef std::unordered_map< std::string, std::string >	ShortToLongMap
	Definition of a map mapping short parameter names to long parameter names. More...

typedef std::unordered_map< std::string, Value >	ValueMap
	Definition of a map mapping long parameter names to values. More...

Protected Member Functions
template<typename TChar >
bool	isLongParameter (const TChar *parameter)
	Returns whether a given string is the start of a long parameter name (whether it starts with "--"). More...

template<typename TChar >
bool	isShortParameter (const TChar *parameter)
	Returns whether a given string is the start of a short parameter name (whether it starts with "--"). More...

Static Protected Member Functions
template<typename TChar >
static TChar	dashCharacter ()
	Returns a dash character. More...

template<typename TChar >
static TChar	quoteCharacter ()
	Returns a quote character. More...

template<typename TChar >
static TChar	spaceCharacter ()
	Returns a space character. More...

template<typename TChar >
static TChar	backslashCharacter ()
	Returns a backslash character. More...

template<>
char	dashCharacter ()

template<>
wchar_t	dashCharacter ()

template<>
char	quoteCharacter ()

template<>
wchar_t	quoteCharacter ()

template<>
char	spaceCharacter ()

template<>
wchar_t	spaceCharacter ()

template<>
char	backslashCharacter ()

template<>
wchar_t	backslashCharacter ()

Protected Attributes
std::string	applicationDescription_
	The description text for the application using these command arguments. More...

ShortToLongMap	shortToLongMap_
	The map mapping short parameter names to long parameter names. More...

ParameterMap	parameterMap_
	The map mapping long parameter names to parameter objects. More...

ValueMap	valueMap_
	The map mapping long parameter names to values. More...

std::vector< std::string >	namelessValues_
	The vector of values without name. More...

std::string	descriptionNamelessParameters_
	Optional description for nameless parameters. More...

Detailed Description

This class implements a manager for command arguments.

Arguments can be configured, parsed, and acquired.

Member Typedef Documentation

◆ ArgumentsT

template<typename T >

using Ocean::CommandArguments::ArgumentsT = std::vector<ArgumentT<T> >

Definition of a vector holding strings with either char or wchar_t.

◆ ArgumentT

template<typename T >

using Ocean::CommandArguments::ArgumentT = std::basic_string<T>

Definition of a string with either char or wchar_t.

◆ ParameterMap

typedef std::map<std::string, Parameter> Ocean::CommandArguments::ParameterMap

protected

Definition of a map mapping long parameter names to parameter objects.

◆ ShortToLongMap

typedef std::unordered_map<std::string, std::string> Ocean::CommandArguments::ShortToLongMap

protected

Definition of a map mapping short parameter names to long parameter names.

◆ ValueMap

typedef std::unordered_map<std::string, Value> Ocean::CommandArguments::ValueMap

protected

Definition of a map mapping long parameter names to values.

Constructor & Destructor Documentation

◆ CommandArguments() [1/2]

Ocean::CommandArguments::CommandArguments ( )

Creates a new object.

◆ CommandArguments() [2/2]

Ocean::CommandArguments::CommandArguments ( const std::string & applicationDescription )

Creates a new object with a description of the application.

Parameters

applicationDescription A description text for the application using these command arguments.

Member Function Documentation

◆ backslashCharacter() [1/3]

template<typename TChar >

static TChar Ocean::CommandArguments::backslashCharacter ( )

inlinestaticprotected

Returns a backslash character.

Returns: Backslash character

Template Parameters

TChar The character type, char or wchar_t

◆ backslashCharacter() [2/3]

template<>

char Ocean::CommandArguments::backslashCharacter ( )

inlinestaticprotected

◆ backslashCharacter() [3/3]

template<>

wchar_t Ocean::CommandArguments::backslashCharacter ( )

inlinestaticprotected

◆ dashCharacter() [1/3]

template<typename TChar >

static TChar Ocean::CommandArguments::dashCharacter ( )

inlinestaticprotected

Returns a dash character.

Returns: Dash character

Template Parameters

TChar The character type, char or wchar_t

◆ dashCharacter() [2/3]

template<>

char Ocean::CommandArguments::dashCharacter ( )

inlinestaticprotected

◆ dashCharacter() [3/3]

template<>

wchar_t Ocean::CommandArguments::dashCharacter ( )

inlinestaticprotected

◆ hasValue() [1/6]

template<>

bool Ocean::CommandArguments::hasValue	(	const std::string &	longName,
		bool &	boolValue,
		const bool	allowDefaultValue,
		const size_t	namelessValueIndex
	)		const

inline

◆ hasValue() [2/6]

template<>

bool Ocean::CommandArguments::hasValue	(	const std::string &	longName,
		double &	doubleValue,
		const bool	allowDefaultValue,
		const size_t	namelessValueIndex
	)		const

inline

◆ hasValue() [3/6]

template<>

bool Ocean::CommandArguments::hasValue	(	const std::string &	longName,
		int32_t &	intValue,
		const bool	allowDefaultValue,
		const size_t	namelessValueIndex
	)		const

inline

◆ hasValue() [4/6]

template<>

bool Ocean::CommandArguments::hasValue	(	const std::string &	longName,
		std::string &	stringValue,
		const bool	allowDefaultValue,
		const size_t	namelessValueIndex
	)		const

inline

◆ hasValue() [5/6]

template<typename T >

bool Ocean::CommandArguments::hasValue	(	const std::string &	longName,
		T &	value,
		const bool	allowDefaultValue = `true`,
		const size_t	namelessValueIndex = `size_t(-1)`
	)		const

Checks whether a specific parameter value has been parsed with specific data type, or whether a default value is defined.

Parameters

longName	The long name of the parameter value to check, must be valid
value	The resulting value of the parameter
allowDefaultValue	True, to allow a default value to count as parsed value; False, to check for actually parsed values only
namelessValueIndex	Optional explicit index of a nameless value which is used in case the named value does not exist, -1 to avoid using a nameless value

Returns: True, if succeeded

Template Parameters

T	The data type of the value, 'Value' by default, can also be one of these specific values 'bool', 'int32_t', 'double' (while integers are accepted as well), 'std::string'

◆ hasValue() [6/6]

bool Ocean::CommandArguments::hasValue	(	const std::string &	longName,
		Value *	value = `nullptr`,
		const bool	allowDefaultValue = `true`,
		const size_t	namelessValueIndex = `size_t(-1)`
	)		const

Checks whether a specific parameter value has been parsed, or whether a default value is defined.

Parameters

longName	The long name of the parameter value to check, must be valid
value	Optional resulting value of the parameter
allowDefaultValue	True, to allow a default value to count as parsed value; False, to check for actually parsed values only
namelessValueIndex	Optional explicit index of a nameless value which is used in case the named value does not exist, -1 to avoid using a nameless value

Returns: True, if succeeded

◆ isLongParameter()

template<typename TChar >

bool Ocean::CommandArguments::isLongParameter ( const TChar * parameter )

protected

Returns whether a given string is the start of a long parameter name (whether it starts with "--").

The string must be zero terminated.

Parameters

parameter The string to be checked, must be valid

Returns: True, if so

Template Parameters

TChar The character type, char or wchar_t

◆ isShortParameter()

template<typename TChar >

bool Ocean::CommandArguments::isShortParameter ( const TChar * parameter )

protected

Returns whether a given string is the start of a short parameter name (whether it starts with "--").

The string must be zero terminated.

Parameters

parameter The string to be checked, must be valid

Returns: True, if so

Template Parameters

TChar The character type, char or wchar_t

◆ makeSummary()

std::string Ocean::CommandArguments::makeSummary ( )

Creates a summary of all possible command arguments.

Returns: The string containing the summary

◆ namelessValues()

const std::vector< std::string > & Ocean::CommandArguments::namelessValues ( ) const

inline

Returns all nameless values which have been parsed.

Returns: The nameless values, in order as they have been parsed, if any

◆ parse() [1/5]

bool Ocean::CommandArguments::parse ( const ArgumentsT< char > & separatedArguments )

Parses the command arguments already separated into individual arguments.

Parameters

separatedArguments The individual arguments to be parsed

Returns: True, if succeeded

◆ parse() [2/5]

bool Ocean::CommandArguments::parse ( const ArgumentsT< wchar_t > & separatedArguments )

Parses the command arguments already separated into individual arguments.

Parameters

separatedArguments The individual arguments to be parsed

Returns: True, if succeeded

◆ parse() [3/5]

template<typename TChar >

bool Ocean::CommandArguments::parse ( const TChar * commandLine )

inline

Parses A given command line.

The entire command line may contain several commands separated by space characters.
Command elements which contain space characters must be surrounded by quotation marks.
However, all surrounding quotation marks will be removed during the parsing process.
The first argument should not be the filename (and path) of the executable.

Parameters

commandLine The command line to be parsed, must be valid

Returns: True, if succeeded

Template Parameters

TChar The character type, char or wchar_t

◆ parse() [4/5]

template<typename TChar >

bool Ocean::CommandArguments::parse	(	const TChar const	arguments,
		const size_t	size,
		const bool	skipFirstArgument = `true`
	)

Parses the several command arguments.

Parameters

arguments	The arguments to be parsed, an be nullptr if `size == 0`
size	The number of arguments, with size [0, infinity)
skipFirstArgument	True, to skip the first argument (as this is commonly the path of the executable); False, to parse the first parameter as well

Returns: True, if succeeded

Template Parameters

TChar The character type, char or wchar_t

◆ parse() [5/5]

template<>

bool Ocean::CommandArguments::parse ( const wchar_t * commandLine )

inline

◆ quoteCharacter() [1/3]

template<typename TChar >

static TChar Ocean::CommandArguments::quoteCharacter ( )

inlinestaticprotected

Returns a quote character.

Returns: Quote character

Template Parameters

TChar The character type, char or wchar_t

◆ quoteCharacter() [2/3]

template<>

char Ocean::CommandArguments::quoteCharacter ( )

inlinestaticprotected

◆ quoteCharacter() [3/3]

template<>

wchar_t Ocean::CommandArguments::quoteCharacter ( )

inlinestaticprotected

◆ registerNamelessParameters()

bool Ocean::CommandArguments::registerNamelessParameters ( std::string && description )

Registers nameless parameters for the summary.

Parameters

description The description for nameless parameters, must not be empty

Returns: True, if succeeded

◆ registerParameter()

bool Ocean::CommandArguments::registerParameter	(	const std::string &	longName,
		const std::string &	shortName = `std::string()`,
		const std::string &	description = `std::string()`,
		const Value &	defaultValue = `Value()`
	)

Registers a new named parameter which can be parsed as command argument.

Parameters

longName	The long name of the parameter, must be valid, must start with a alphabetic character
shortName	Optional short name of the parameter, can be empty, must start with a alphabetic character if defined
description	Optional description of the parameter, can be empty
defaultValue	Optional default value of the parameter, can be invalid

Returns: True, if the named parameter did not exist before

◆ separateArguments()

template<typename TChar >

CommandArguments::ArgumentsT< TChar > Ocean::CommandArguments::separateArguments ( const TChar * commandLine )

static

Parses the command line and returns the individual command elements.

The entire command line may contain several commands separated by space characters.
Command elements which contain space characters must be surrounded by quotation marks.
However, all surrounding quotation marks will be removed during the parsing process.
The first argument should not be the filename (and path) of the executable.

Parameters

commandLine Command line to be parsed

Returns: The separated command arguments

Template Parameters

TChar The character type, char or wchar_t

◆ spaceCharacter() [1/3]

template<typename TChar >

static TChar Ocean::CommandArguments::spaceCharacter ( )

inlinestaticprotected

Returns a space character.

Returns: Space character

Template Parameters

TChar The character type, char or wchar_t

◆ spaceCharacter() [2/3]

template<>

char Ocean::CommandArguments::spaceCharacter ( )

inlinestaticprotected

◆ spaceCharacter() [3/3]

template<>

wchar_t Ocean::CommandArguments::spaceCharacter ( )

inlinestaticprotected

◆ value() [1/2]

Value Ocean::CommandArguments::value	(	const std::string &	longName,
		const bool	allowDefaultValue = `true`,
		const size_t	namelessValueIndex = `size_t(-1)`
	)		const

Returns the value of a specific parameter which has been parsed.

Below an example of how to use this function:

CommandArguments commandArguments;
commandArguments.registerParameter("input", "i", "The input file");
 
const Value inputFile = commandArguments.value<std::string>("input");
if (inputFile.isString())
{
    const std::string inputFileString = inputFile.stringValue();
    // ...
}

Parameters

longName	The long name of the parameter for which the value will be returned, must be valid
allowDefaultValue	True, to return the default value in case no actual value has been parsed; False, to return an invalid value if no actual value has been parsed
namelessValueIndex	Optional explicit index of a nameless value which is used in case the named value does not exist, -1 to avoid using a nameless value

Returns: The value of the parameter, an invalid value if the value has not been parsed

◆ value() [2/2]

template<typename T >

T Ocean::CommandArguments::value	(	const std::string &	longName,
		const T &	invalidValue,
		const bool	allowDefaultValue,
		const size_t	namelessValueIndex = `size_t(-1)`
	)		const

Returns the value of a specific parameter which has been parsed.

Below an example of how to use this function:

CommandArguments commandArguments;
commandArguments.registerParameter("input", "i", "The input file");
commandArguments.registerParameter("factor", "f", "The factor parameter");
 
const std::string inputFile = commandArguments.value<std::string>("input", std::string(), false);
const double factor = commandArguments.value<double>("factor", -1.0, false);

Parameters

longName	The long name of the parameter for which the value will be returned, must be valid
invalidValue	The resulting value in case the parameter was not parsed
allowDefaultValue	True, to return the default value in case no actual value has been parsed; False, to return an invalid value if no actual value has been parsed
namelessValueIndex	Optional explicit index of a nameless value which is used in case the named value does not exist, -1 to avoid using a nameless value

Returns: The value of the parameter, the invalid value if the value has not been parsed

Field Documentation

◆ applicationDescription_

std::string Ocean::CommandArguments::applicationDescription_

protected

The description text for the application using these command arguments.

◆ descriptionNamelessParameters_

std::string Ocean::CommandArguments::descriptionNamelessParameters_

protected

Optional description for nameless parameters.

◆ namelessValues_

std::vector<std::string> Ocean::CommandArguments::namelessValues_

protected

The vector of values without name.

◆ parameterMap_

ParameterMap Ocean::CommandArguments::parameterMap_

protected

The map mapping long parameter names to parameter objects.

◆ shortToLongMap_

ShortToLongMap Ocean::CommandArguments::shortToLongMap_

protected

The map mapping short parameter names to long parameter names.

◆ valueMap_

ValueMap Ocean::CommandArguments::valueMap_

protected

The map mapping long parameter names to values.

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

CommandArguments.h

Data Structures

Public Types

Public Member Functions

Static Public Member Functions

Protected Types

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Member Typedef Documentation

◆ ArgumentsT

◆ ArgumentT

◆ ParameterMap

◆ ShortToLongMap

◆ ValueMap

Constructor & Destructor Documentation

◆ CommandArguments() [1/2]

◆ CommandArguments() [2/2]

Member Function Documentation

◆ backslashCharacter() [1/3]

◆ backslashCharacter() [2/3]

◆ backslashCharacter() [3/3]

◆ dashCharacter() [1/3]

◆ dashCharacter() [2/3]

◆ dashCharacter() [3/3]

◆ hasValue() [1/6]

◆ hasValue() [2/6]

◆ hasValue() [3/6]

◆ hasValue() [4/6]

◆ hasValue() [5/6]

◆ hasValue() [6/6]

◆ isLongParameter()

◆ isShortParameter()

◆ makeSummary()

◆ namelessValues()

◆ parse() [1/5]

◆ parse() [2/5]

◆ parse() [3/5]

◆ parse() [4/5]

◆ parse() [5/5]

◆ quoteCharacter() [1/3]

◆ quoteCharacter() [2/3]

◆ quoteCharacter() [3/3]

◆ registerNamelessParameters()

◆ registerParameter()

◆ separateArguments()

◆ spaceCharacter() [1/3]

◆ spaceCharacter() [2/3]

◆ spaceCharacter() [3/3]

◆ value() [1/2]

◆ value() [2/2]

Field Documentation

◆ applicationDescription_

◆ descriptionNamelessParameters_

◆ namelessValues_

◆ parameterMap_

◆ shortToLongMap_

◆ valueMap_