Medical Imaging Interaction Toolkit  2018.4.99-b20efe7f
Medical Imaging Interaction Toolkit
mitkCommandLineParser Class Reference

#include <mitkCommandLineParser.h>

Collaboration diagram for mitkCommandLineParser:

Public Types

enum  Type {
  String, Bool, StringList, Int,
  Float, Directory, File, Image
}
 
enum  Channel { None, Input, Output }
 
typedef std::vector< std::string > StringContainerType
 

Public Member Functions

 mitkCommandLineParser ()
 
 ~mitkCommandLineParser ()
 
std::map< std::string, us::AnyparseArguments (const StringContainerType &arguments, bool *ok=nullptr)
 
std::map< std::string, us::AnyparseArguments (int argc, char **argv, bool *ok=nullptr)
 
std::string errorString () const
 
const StringContainerTypeunparsedArguments () const
 
bool argumentAdded (const std::string &argument) const
 
bool argumentParsed (const std::string &argument) const
 
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)
 
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

The MITK command line parser, 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::out is used for output to keep dependencies to a minimum.

Definition at line 69 of file mitkCommandLineParser.h.

Member Typedef Documentation

◆ StringContainerType

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

Definition at line 91 of file mitkCommandLineParser.h.

Member Enumeration Documentation

◆ Channel

Enumerator
None 
Input 
Output 

Definition at line 84 of file mitkCommandLineParser.h.

◆ Type

Enumerator
String 
Bool 
StringList 
Int 
Float 
Directory 
File 
Image 

Definition at line 72 of file mitkCommandLineParser.h.

Constructor & Destructor Documentation

◆ mitkCommandLineParser()

mitkCommandLineParser::mitkCommandLineParser ( )

Definition at line 383 of file mitkCommandLineParser.cpp.

◆ ~mitkCommandLineParser()

mitkCommandLineParser::~mitkCommandLineParser ( )

Definition at line 395 of file mitkCommandLineParser.cpp.

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 
)

Adds 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 parametersDefault regular expr Example
us::Any::String1.*–test-string StringParameter
us::Any::Bool0does not apply–enable-something
us::Any::StringList-1.*–test-list string1 string2
us::Any::Int1-?[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().

You can also declare an argument deprecated, by setting deprecated to true. Alternatively you can add a deprecated argument by calling addDeprecatedArgument().

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

Parameters
longargThe long argument name.
shortargThe short argument name.
typeThe argument type (see the list above for supported types).
argLabelThe label of this argument, when auto generated interface is used.
argHelpA help string describing the argument.
defaultValueA default value for the argument.
ignoreRestAll arguments after the current one will be ignored.
deprecatedDeclares the argument deprecated.
See also
setExactMatchRegularExpression()
addDeprecatedArgument()
Exceptions
std::logic_errorIf the us::Any type of defaultValue does not match type, a std::logic_error is thrown.

Definition at line 717 of file mitkCommandLineParser.cpp.

Referenced by mitk::GIFNeighbourhoodGreyLevelDifference::AddArguments(), mitk::GIFCooccurenceMatrix::AddArguments(), mitk::GIFLocalIntensity::AddArguments(), mitk::GIFIntensityVolumeHistogramFeatures::AddArguments(), mitk::GIFImageDescriptionFeatures::AddArguments(), mitk::GIFNeighbourhoodGreyToneDifferenceFeatures::AddArguments(), mitk::GIFCurvatureStatistic::AddArguments(), mitk::GIFFirstOrderHistogramStatistics::AddArguments(), mitk::GIFGreyLevelSizeZone::AddArguments(), mitk::GIFGreyLevelRunLength::AddArguments(), mitk::GIFVolumetricDensityStatistics::AddArguments(), mitk::GIFVolumetricStatistics::AddArguments(), mitk::GIFNeighbouringGreyLevelDependenceFeature::AddArguments(), mitk::GIFFirstOrderStatistics::AddArguments(), mitk::GIFFirstOrderNumericStatistics::AddArguments(), mitk::GIFCooccurenceMatrix2::AddArguments(), mitk::GIFGreyLevelDistanceZone::AddArguments(), mitk::cl::GlobalImageFeaturesParameter::AddParameter(), mitk::AbstractGlobalImageFeature::AddQuantifierArguments(), main(), parseInput(), and setupParser().

◆ 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
longargThe long argument name.
shortargThe short argument name.
argHelpA help string describing alternatives to the deprecated argument.

Definition at line 785 of file mitkCommandLineParser.cpp.

◆ argumentAdded()

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

Checks if the given argument has been added via a call to addArgument().

See also
addArgument()
Parameters
argumentThe argument to be checked.
Returns
true if the argument was added, false otherwise.

Definition at line 895 of file mitkCommandLineParser.cpp.

◆ argumentParsed()

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

Checks if the given argument has been parsed successfully by a previous call to parseArguments().

Parameters
argumentThe argument to be checked.
Returns
true if the argument was parsed, false otherwise.

Definition at line 901 of file mitkCommandLineParser.cpp.

◆ 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
descriptionThe description of the group

Definition at line 831 of file mitkCommandLineParser.cpp.

Referenced by main(), parseInput(), and setupParser().

◆ 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
nameThe name of the groupbox.
tooltipThe tooltip of the groupbox.

Definition at line 1052 of file mitkCommandLineParser.cpp.

◆ endGroup()

void mitkCommandLineParser::endGroup ( )

Ends the current group.

See also
beginGroup(const std::string&)

Definition at line 837 of file mitkCommandLineParser.cpp.

Referenced by main(), parseInput(), and setupParser().

◆ errorString()

string mitkCommandLineParser::errorString ( ) const

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

Returns
The error description, empty if no error occured.
See also
parseArguments(const StringContainerType&, bool*)

Definition at line 705 of file mitkCommandLineParser.cpp.

◆ 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.

Definition at line 825 of file mitkCommandLineParser.cpp.

◆ generateXmlOutput()

void mitkCommandLineParser::generateXmlOutput ( )

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

Definition at line 923 of file mitkCommandLineParser.cpp.

References Bool, Directory, File, Float, Image, Int, String, and StringList.

◆ getArgumentList()

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

Returns the vector of current Command line Parameter

Definition at line 794 of file mitkCommandLineParser.cpp.

◆ helpText()

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().

Parameters
charPadThe padding character.
Returns
The formatted help text.

Definition at line 843 of file mitkCommandLineParser.cpp.

Referenced by main().

◆ parseArguments() [1/2]

map< 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.

Parameters
argumentsA StringContainerType containing command line arguments.
okA pointer to a boolean variable. Will be set to true if all regular expressions matched, false otherwise.
Returns
A map object mapping the long argument (if empty, the short one) to a us::Any containing the value.

Definition at line 401 of file mitkCommandLineParser.cpp.

References MITK_REVISION, and MITK_REVISION_NAME.

Referenced by main(), and parseInput().

◆ parseArguments() [2/2]

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

Convenient method allowing to parse a given list of command line arguments.

See also
parseArguments(const StringContainerType &, bool*)

Definition at line 692 of file mitkCommandLineParser.cpp.

◆ 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);
args << "program name" << "--long-argument Hi";
parser.parseArguments(args);
Parameters
longPrefixThe prefix for long argument names.
shortPrefixThe prefix for short argument names.

Definition at line 910 of file mitkCommandLineParser.cpp.

Referenced by main(), parseInput(), and setupParser().

◆ setCategory()

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

Is used to categorize the apps in the commandline module.

Parameters
categoryThe category of the app.

Definition at line 1042 of file mitkCommandLineParser.cpp.

Referenced by main(), parseInput(), and setupParser().

◆ setContributor()

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

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

Parameters
contributorContributor of the app.

Definition at line 1037 of file mitkCommandLineParser.cpp.

Referenced by main(), parseInput(), and setupParser().

◆ setDescription()

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

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

Parameters
descriptionA short description for the app.

Definition at line 1047 of file mitkCommandLineParser.cpp.

Referenced by main(), parseInput(), and setupParser().

◆ 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
argumentThe previously added long or short argument name.
expressionA regular expression which the arugment parameters must match.
exactMatchFailedMessageAn 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*)

Definition at line 917 of file mitkCommandLineParser.cpp.

◆ setTitle()

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

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

Parameters
titleThe title of the app.

Definition at line 1033 of file mitkCommandLineParser.cpp.

Referenced by main(), parseInput(), and setupParser().

◆ unparsedArguments()

const mitkCommandLineParser::StringContainerType & mitkCommandLineParser::unparsedArguments ( ) const

This method returns all unparsed arguments, i.e. all arguments for which no long or short name has been registered via a call to addArgument().

See also
addArgument()
Returns
A list containing unparsed arguments.

Definition at line 711 of file mitkCommandLineParser.cpp.

Member Data Documentation

◆ Category

std::string mitkCommandLineParser::Category
protected

Definition at line 381 of file mitkCommandLineParser.h.

◆ Contributor

std::string mitkCommandLineParser::Contributor
protected

Definition at line 380 of file mitkCommandLineParser.h.

◆ Description

std::string mitkCommandLineParser::Description
protected

Definition at line 382 of file mitkCommandLineParser.h.

◆ Internal

ctkInternal* mitkCommandLineParser::Internal
protected

Definition at line 376 of file mitkCommandLineParser.h.

◆ ParameterGroupDescription

std::string mitkCommandLineParser::ParameterGroupDescription
protected

Definition at line 384 of file mitkCommandLineParser.h.

◆ ParameterGroupName

std::string mitkCommandLineParser::ParameterGroupName
protected

Definition at line 383 of file mitkCommandLineParser.h.

◆ Title

std::string mitkCommandLineParser::Title
protected

Definition at line 379 of file mitkCommandLineParser.h.


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