Command line argument parser for MITK applications, based on the CTK command line parser. More...

#include <mitkCommandLineParser.h>

Collaboration diagram for mitkCommandLineParser:

Public Types
enum	Type { String , Bool , StringList , Int , Float , Directory , File , Image }
	Supported argument value types. More...

enum	Channel { None , Input , Output }
	I/O channel classification for arguments. More...

typedef std::vector< std::string >	StringContainerType
	Container type for string lists, used for argument values and unparsed arguments. More...

Public Member Functions
	mitkCommandLineParser ()
	Construct a parser with default settings. More...

	~mitkCommandLineParser ()
	Destructor. More...

std::map< std::string, us::Any >	parseArguments (const StringContainerType &arguments, bool *ok=nullptr)
	Parse a given list of command line arguments. More...

std::map< std::string, us::Any >	parseArguments (int argc, char *argv, bool ok=nullptr)
	Convenient overload to parse arguments from argc/argv. More...

std::string	errorString () const
	Get a detailed error description if a call to parseArguments() failed. More...

const StringContainerType &	unparsedArguments () const
	Get all unparsed arguments. More...

bool	argumentAdded (const std::string &argument) const
	Check if a given argument has been registered. More...

bool	argumentParsed (const std::string &argument) const
	Check if a given argument has been parsed successfully. More...

void	addArgument (const std::string &longarg, const std::string &shortarg, Type type, const std::string &argLabel, const std::string &argHelp=std::string(), const us::Any &defaultValue=us::Any(), bool optional=true, bool ignoreRest=false, bool deprecated=false, mitkCommandLineParser::Channel channel=mitkCommandLineParser::Channel::None)
	Add a command line argument. More...

void	addDeprecatedArgument (const std::string &longarg, const std::string &shortarg, const std::string &argLabel, const std::string &argHelp)

std::vector< std::map< std::string, us::Any > >	getArgumentList ()

bool	setExactMatchRegularExpression (const std::string &argument, const std::string &expression, const std::string &exactMatchFailedMessage)

std::string::size_type	fieldWidth () const

std::string	helpText () const

void	setArgumentPrefix (const std::string &longPrefix, const std::string &shortPrefix)

void	beginGroup (const std::string &description)

void	endGroup ()

void	setStrictModeEnabled (bool strictMode)

void	generateXmlOutput ()

void	setTitle (std::string title)

void	setContributor (std::string contributor)

void	setCategory (std::string category)

void	setDescription (std::string description)

void	changeParameterGroup (std::string name, std::string tooltip)

Protected Attributes
ctkInternal *	Internal

std::string	Title

std::string	Contributor

std::string	Category

std::string	Description

std::string	ParameterGroupName

std::string	ParameterGroupDescription

Detailed Description

Command line argument parser for MITK applications, based on the CTK command line parser.

Use this class to add information about the command line arguments your program understands and to easily parse them from a given list of strings.

This parser provides the following features:

Add arguments by supplying a long name and/or a short name. Arguments are validated using a regular expression. They can have a default value and a help string.
Deprecated arguments.
Custom regular expressions for argument validation.
Set different argument name prefixes for native platform look and feel.
Create a help text for the command line arguments with support for grouping arguments.

The main difference between the MITK command line parser and the CTK command line parser is that the former does not depend on Qt. Apart from that an image type was added and XML output improved for automatic GUI generation.

std::cout is used for output to keep dependencies to a minimum.

Definition at line 45 of file mitkCommandLineParser.h.

Member Typedef Documentation

◆ StringContainerType

typedef std::vector<std::string> mitkCommandLineParser::StringContainerType

Container type for string lists, used for argument values and unparsed arguments.

Definition at line 75 of file mitkCommandLineParser.h.

Member Enumeration Documentation

◆ Channel

enum mitkCommandLineParser::Channel

I/O channel classification for arguments.

Used in XML output generation for automatic GUI creation.

Enumerator
None	Not an I/O channel.
Input	Argument represents an input resource.
Output	Argument represents an output resource.

Definition at line 66 of file mitkCommandLineParser.h.

◆ Type

enum mitkCommandLineParser::Type

Supported argument value types.

Enumerator
String	A single string value.
Bool	A boolean flag (no parameters, presence means `true`).
StringList	A list of string values.
Int	An integer value.
Float	A floating-point value.
Directory	A directory path.
File	A file path.
Image	An image file path.

Definition at line 50 of file mitkCommandLineParser.h.

Constructor & Destructor Documentation

◆ mitkCommandLineParser()

mitkCommandLineParser::mitkCommandLineParser ( )

Construct a parser with default settings.

By default, no argument prefixes are set and strict mode is disabled.

◆ ~mitkCommandLineParser()

mitkCommandLineParser::~mitkCommandLineParser ( )

Destructor.

Cleans up internal argument description storage.

Member Function Documentation

◆ addArgument()

void mitkCommandLineParser::addArgument	(	const std::string &	longarg,
		const std::string &	shortarg,
		Type	type,
		const std::string &	argLabel,
		const std::string &	argHelp = `std::string()`,
		const us::Any &	defaultValue = `us::Any()`,
		bool	optional = `true`,
		bool	ignoreRest = `false`,
		bool	deprecated = `false`,
		mitkCommandLineParser::Channel	channel = `mitkCommandLineParser::Channel::None`
	)

Add a command line argument.

An argument can have a long name (like –long-argument-name), a short name (like -l), or both. The type of the argument can be specified by using the type parameter. The following types are supported:

Type	# of parameters	Default regex	Example
String	1	.*	–test-string StringParameter
Bool	0	n/a	–enable-something
StringList	-1	.*	–test-list string1 string2
Int	1	-?[0-9]+	–test-int -5

The regular expressions are used to validate the parameters of command line arguments. You can restrict the valid set of parameters by calling setExactMatchRegularExpression() for your argument.

Optionally, a help string and a default value can be provided for the argument. If the us::Any type of the default value does not match type, an exception is thrown. Arguments with default values are always returned by parseArguments().

If the long or short argument has already been added, or if both are empty strings, the method call has no effect.

Parameters

[in]	longarg	The long argument name (without prefix).
[in]	shortarg	The short argument name (without prefix).
[in]	type	The argument value type.
[in]	argLabel	The label of this argument for auto-generated interfaces.
[in]	argHelp	A help string describing the argument.
[in]	defaultValue	A default value for the argument.
[in]	optional	Whether the argument is optional (`true` by default).
[in]	ignoreRest	If `true`, all arguments after this one will be ignored.
[in]	deprecated	If `true`, marks the argument as deprecated.
[in]	channel	The I/O channel classification for XML output.

Exceptions

std::logic_error If the type of defaultValue does not match type.

See also: setExactMatchRegularExpression(), addDeprecatedArgument()

◆ addDeprecatedArgument()

void mitkCommandLineParser::addDeprecatedArgument	(	const std::string &	longarg,
		const std::string &	shortarg,
		const std::string &	argLabel,
		const std::string &	argHelp
	)

Adds a deprecated command line argument. If a deprecated argument is provided on the command line, argHelp is displayed in the console and processing continues with the next argument.

Deprecated arguments are grouped separately at the end of the help text returned by helpText().

Parameters

longarg	The long argument name.
shortarg	The short argument name.
argLabel
argHelp	A help string describing alternatives to the deprecated argument.

◆ argumentAdded()

bool mitkCommandLineParser::argumentAdded ( const std::string & argument ) const

Check if a given argument has been registered.

Parameters

[in] argument The long or short argument name to check.

Returns: true if the argument was added via addArgument(), false otherwise.

See also: addArgument()

◆ argumentParsed()

bool mitkCommandLineParser::argumentParsed ( const std::string & argument ) const

Check if a given argument has been parsed successfully.

Parameters

[in] argument The long or short argument name to check.

Returns: true if the argument was parsed in the last call to parseArguments(), false otherwise.

See also: parseArguments()

◆ beginGroup()

void mitkCommandLineParser::beginGroup ( const std::string & description )

Begins a new group for documenting arguments. All newly added arguments via addArgument() will be put in the new group. You can close the current group by calling endGroup() or be opening a new group.

Note that groups cannot be nested and all arguments which do not belong to a group will be listed at the top of the text created by helpText().

Parameters

description The description of the group

◆ changeParameterGroup()

void mitkCommandLineParser::changeParameterGroup	(	std::string	name,
		std::string	tooltip
	)

Is used to group several Parameters in one groupbox in the auto generated interface. Default name is "Parameters", with the tooltip: "Groupbox containing parameters."

To change the group of several arguments, call this method before the arguments are added.

Parameters

name	The name of the groupbox.
tooltip	The tooltip of the groupbox.

◆ endGroup()

void mitkCommandLineParser::endGroup ( )

Ends the current group.

See also: beginGroup(const std::string&)

◆ errorString()

std::string mitkCommandLineParser::errorString ( ) const

Get a detailed error description if a call to parseArguments() failed.

Returns: The error description, or an empty string if no error occurred.

See also: parseArguments()

◆ fieldWidth()

std::string::size_type mitkCommandLineParser::fieldWidth ( ) const

The field width for the argument names without the help text.

Returns: The argument names field width in the help text.

◆ generateXmlOutput()

void mitkCommandLineParser::generateXmlOutput ( )

Is used to generate an XML output for any commandline program.

◆ getArgumentList()

std::vector< std::map<std::string, us::Any> > mitkCommandLineParser::getArgumentList ( )

Returns the vector of current Command line Parameter

◆ helpText()

std::string mitkCommandLineParser::helpText ( ) const

Creates a help text containing properly formatted argument names and help strings provided by calls to addArgument(). The arguments can be grouped by using beginGroup() and endGroup().

Returns: The formatted help text.

◆ parseArguments() [1/2]

std::map<std::string, us::Any> mitkCommandLineParser::parseArguments	(	const StringContainerType &	arguments,
		bool *	ok = `nullptr`
	)

Parse a given list of command line arguments.

This method parses a list of string elements considering the known arguments added by calls to addArgument(). If any one of the argument values does not match the corresponding regular expression, ok is set to false and an empty map object is returned.

The keys in the returned map object correspond to the long argument string, if it is not empty. Otherwise, the short argument string is used as key. The us::Any values can safely be converted to the type specified in the addArgument() method call.

If the special argument –xml is encountered, XML output is generated and an empty map is returned. If –version is encountered, the MITK revision information is printed.

Parameters

[in]	arguments	A StringContainerType containing command line arguments.
[out]	ok	If not `nullptr`, set to `true` if parsing succeeded, `false` otherwise.

Returns: A map object mapping argument names to us::Any values.

◆ parseArguments() [2/2]

std::map<std::string, us::Any> mitkCommandLineParser::parseArguments	(	int	argc,
		char **	argv,
		bool *	ok = `nullptr`
	)

Convenient overload to parse arguments from argc/argv.

Converts argc and argv to a StringContainerType and delegates to parseArguments(const StringContainerType&, bool*).

Parameters

[in]	argc	The argument count from main().
[in]	argv	The argument array from main().
[out]	ok	If not `nullptr`, set to `true` if parsing succeeded, `false` otherwise.

Returns: A map object mapping argument names to us::Any values.

See also: parseArguments(const StringContainerType&, bool*)

◆ setArgumentPrefix()

void mitkCommandLineParser::setArgumentPrefix	(	const std::string &	longPrefix,
		const std::string &	shortPrefix
	)

Sets the argument prefix for long and short argument names. This can be used to create native command line arguments without changing the calls to addArgument(). For example on Unix-based systems, long argument names start with "--" and short names with "-", while on Windows argument names always start with "/".

Note that all methods in mitkCommandLineParser which take an argument name expect the name as it was supplied to addArgument.

Example usage:

ctkCommandLineParser parser;
parser.setArgumentPrefix("--", "-");
parser.addArgument("long-argument", "l", us::Any::String);
StringContainerType args;
args << "program name" << "--long-argument Hi";
parser.parseArguments(args);

Parameters

longPrefix	The prefix for long argument names.
shortPrefix	The prefix for short argument names.

◆ setCategory()

void mitkCommandLineParser::setCategory ( std::string category )

Is used to categorize the apps in the commandline module.

Parameters

category The category of the app.

◆ setContributor()

void mitkCommandLineParser::setContributor ( std::string contributor )

Is used to set the contributor for the help view in the auto generated interface.

Parameters

contributor Contributor of the app.

◆ setDescription()

void mitkCommandLineParser::setDescription ( std::string description )

Is used as the help text in the auto generated interface.

Parameters

description A short description for the app.

◆ setExactMatchRegularExpression()

bool mitkCommandLineParser::setExactMatchRegularExpression	(	const std::string &	argument,
		const std::string &	expression,
		const std::string &	exactMatchFailedMessage
	)

Sets a custom regular expression for validating argument parameters. The method errorString() can be used the get the last error description.

Parameters

argument	The previously added long or short argument name.
expression	A regular expression which the argument parameters must match.
exactMatchFailedMessage	An error message explaining why the parameter did not match.

Returns: true if the argument was found and the regular expression was set, false otherwise.

See also: errorString()

◆ setStrictModeEnabled()

void mitkCommandLineParser::setStrictModeEnabled ( bool strictMode )

Can be used to teach the parser to stop parsing the arguments and return False when an unknown argument is encountered. By default StrictMode is disabled.

See also: parseArguments(const StringContainerType &, bool*)

◆ setTitle()

void mitkCommandLineParser::setTitle ( std::string title )

Is used to set the title of the auto generated interface.

Parameters

title The title of the app.

◆ unparsedArguments()

const StringContainerType& mitkCommandLineParser::unparsedArguments ( ) const

Get all unparsed arguments.

Returns all arguments for which no long or short name has been registered via a call to addArgument().

Returns: A reference to the list of unparsed argument strings.

See also: addArgument()

Member Data Documentation

◆ Category

std::string mitkCommandLineParser::Category

protected

Definition at line 372 of file mitkCommandLineParser.h.

◆ Contributor

std::string mitkCommandLineParser::Contributor

protected

Definition at line 371 of file mitkCommandLineParser.h.

◆ Description

std::string mitkCommandLineParser::Description

protected

Definition at line 373 of file mitkCommandLineParser.h.

◆ Internal

ctkInternal* mitkCommandLineParser::Internal

protected

Definition at line 368 of file mitkCommandLineParser.h.

◆ ParameterGroupDescription

std::string mitkCommandLineParser::ParameterGroupDescription

protected

Definition at line 375 of file mitkCommandLineParser.h.

◆ ParameterGroupName

std::string mitkCommandLineParser::ParameterGroupName

protected

Definition at line 374 of file mitkCommandLineParser.h.

◆ Title

std::string mitkCommandLineParser::Title

protected

Definition at line 370 of file mitkCommandLineParser.h.

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

mitkCommandLineParser.h

Public Types

Public Member Functions

Protected Attributes

Detailed Description

Member Typedef Documentation

◆ StringContainerType

Member Enumeration Documentation

◆ Channel

◆ Type

Constructor & Destructor Documentation

◆ mitkCommandLineParser()

◆ ~mitkCommandLineParser()

Member Function Documentation

◆ addArgument()

◆ addDeprecatedArgument()

◆ argumentAdded()

◆ argumentParsed()

◆ beginGroup()

◆ changeParameterGroup()

◆ endGroup()

◆ errorString()

◆ fieldWidth()

◆ generateXmlOutput()

◆ getArgumentList()

◆ helpText()

◆ parseArguments() [1/2]

◆ parseArguments() [2/2]

◆ setArgumentPrefix()

◆ setCategory()

◆ setContributor()

◆ setDescription()

◆ setExactMatchRegularExpression()

◆ setStrictModeEnabled()

◆ setTitle()

◆ unparsedArguments()

Member Data Documentation

◆ Category

◆ Contributor

◆ Description

◆ Internal

◆ ParameterGroupDescription

◆ ParameterGroupName

◆ Title