OpenMS
TOPPBase Class Referenceabstract

Base class for TOPP applications. More...

#include <OpenMS/APPLICATIONS/TOPPBase.h>

Inheritance diagram for TOPPBase:
[legend]
Collaboration diagram for TOPPBase:
[legend]

Public Types

enum  ExitCodes {
  EXECUTION_OK , INPUT_FILE_NOT_FOUND , INPUT_FILE_NOT_READABLE , INPUT_FILE_CORRUPT ,
  INPUT_FILE_EMPTY , CANNOT_WRITE_OUTPUT_FILE , ILLEGAL_PARAMETERS , MISSING_PARAMETERS ,
  UNKNOWN_ERROR , EXTERNAL_PROGRAM_ERROR , PARSE_ERROR , INCOMPATIBLE_INPUT_DATA ,
  INTERNAL_ERROR , UNEXPECTED_RESULT
}
 Exit codes. More...
 

Public Member Functions

 TOPPBase ()=delete
 No default constructor. More...
 
 TOPPBase (const TOPPBase &)=delete
 No default copy constructor. More...
 
 TOPPBase (const String &name, const String &description, bool official=true, const std::vector< Citation > &citations={}, bool toolhandler_test=true)
 Constructor. More...
 
virtual ~TOPPBase ()
 Destructor. More...
 
ExitCodes main (int argc, const char **argv)
 Main routine of all TOPP applications. More...
 
String getToolPrefix () const
 Returns the prefix used to identify the tool. More...
 
String getDocumentationURL () const
 Returns a link to the documentation of the tool (accessible on our servers and only after inclusion in the nightly branch or a release). More...
 

Static Public Member Functions

static void setMaxNumberOfThreads (int num_threads)
 Sets the maximal number of usable threads. More...
 

Protected Member Functions

Parameter handling

Use the methods registerStringOption_, registerInputFile_, registerOutputFile_, registerOutputPrefix_, registerDoubleOption_, registerIntOption_ and registerFlag_ in order to register parameters in registerOptionsAndFlags_.

To access the values of registered parameters in the main_ method use methods getStringOption_ (also for input and output files), getDoubleOption_, getIntOption_,getStringList_(also for input and output file lists),getIntList_,getDoubleList_, and getFlag_.

The values of certain options can be restricted using: setMinInt_, setMaxInt_, setMinFloat_, setMaxFloat_, setValidStrings_ and setValidFormats_.

In order to format the help output, the method addEmptyLine_ can be used.

virtual void registerOptionsAndFlags_ ()=0
 Sets the valid command line options (with argument) and flags (without argument). More...
 
String getParamArgument_ (const Param::ParamEntry &entry) const
 Utility function that determines a suitable argument value for the given Param::ParamEntry. More...
 
std::vector< ParameterInformationparamToParameterInformation_ (const Param &param) const
 Translates the given parameter object into a vector of ParameterInformation, that can be utilized for cl parsing. More...
 
ParameterInformation paramEntryToParameterInformation_ (const Param::ParamEntry &entry, const String &argument="", const String &full_name="") const
 Transforms a ParamEntry object to command line parameter (ParameterInformation). More...
 
void registerParamSubsectionsAsTOPPSubsections_ (const Param &param)
 
void registerFullParam_ (const Param &param)
 Register command line parameters for all entries in a Param object. More...
 
void registerStringOption_ (const String &name, const String &argument, const String &default_value, const String &description, bool required=true, bool advanced=false)
 Registers a string option. More...
 
void setValidStrings_ (const String &name, const std::vector< String > &strings)
 Sets the valid strings for a string option or a whole string list. More...
 
void setValidStrings_ (const String &name, const std::string vstrings[], int count)
 Sets the valid strings for a string option or a whole string list. More...
 
void registerInputFile_ (const String &name, const String &argument, const String &default_value, const String &description, bool required=true, bool advanced=false, const StringList &tags=StringList())
 Registers an input file option. More...
 
void registerOutputFile_ (const String &name, const String &argument, const String &default_value, const String &description, bool required=true, bool advanced=false)
 Registers an output file option. More...
 
void registerOutputPrefix_ (const String &name, const String &argument, const String &default_value, const String &description, bool required=true, bool advanced=false)
 Registers an output file prefix used for tools with multiple file output. More...
 
void setValidFormats_ (const String &name, const std::vector< String > &formats, const bool force_OpenMS_format=true)
 Sets the formats for a input/output file option or for all members of an input/output file lists. More...
 
void registerDoubleOption_ (const String &name, const String &argument, double default_value, const String &description, bool required=true, bool advanced=false)
 Registers a double option. More...
 
void setMinInt_ (const String &name, Int min)
 Sets the minimum value for the integer parameter(can be a list of integers,too) name. More...
 
void setMaxInt_ (const String &name, Int max)
 Sets the maximum value for the integer parameter(can be a list of integers,too) name. More...
 
void setMinFloat_ (const String &name, double min)
 Sets the minimum value for the floating point parameter(can be a list of floating points,too) name. More...
 
void setMaxFloat_ (const String &name, double max)
 Sets the maximum value for the floating point parameter(can be a list of floating points,too) name. More...
 
void registerIntOption_ (const String &name, const String &argument, Int default_value, const String &description, bool required=true, bool advanced=false)
 Registers an integer option. More...
 
void registerIntList_ (const String &name, const String &argument, const IntList &default_value, const String &description, bool required=true, bool advanced=false)
 Registers a list of integers option. More...
 
void registerDoubleList_ (const String &name, const String &argument, const DoubleList &default_value, const String &description, bool required=true, bool advanced=false)
 Registers a list of doubles option. More...
 
void registerStringList_ (const String &name, const String &argument, const StringList &default_value, const String &description, bool required=true, bool advanced=false)
 Registers a list of strings option. More...
 
void registerInputFileList_ (const String &name, const String &argument, const StringList &default_value, const String &description, bool required=true, bool advanced=false, const StringList &tags=StringList())
 Registers a list of input files option. More...
 
void registerOutputFileList_ (const String &name, const String &argument, const StringList &default_value, const String &description, bool required=true, bool advanced=false)
 Registers a list of output files option. More...
 
void registerFlag_ (const String &name, const String &description, bool advanced=false)
 Registers a flag. More...
 
void registerSubsection_ (const String &name, const String &description)
 Registers an allowed subsection in the INI file (usually from OpenMS algorithms). More...
 
void registerTOPPSubsection_ (const String &name, const String &description)
 Registers an allowed subsection in the INI file originating from the TOPP tool itself. More...
 
void addEmptyLine_ ()
 Adds an empty line between registered variables in the documentation. More...
 
String getStringOption_ (const String &name) const
 Returns the value of a previously registered string option. More...
 
double getDoubleOption_ (const String &name) const
 Returns the value of a previously registered double option. More...
 
Int getIntOption_ (const String &name) const
 Returns the value of a previously registered integer option. More...
 
StringList getStringList_ (const String &name) const
 Returns the value of a previously registered StringList. More...
 
IntList getIntList_ (const String &name) const
 Returns the value of a previously registered IntList. More...
 
DoubleList getDoubleList_ (const String &name) const
 Returns the value of a previously registered DoubleList. More...
 
bool getFlag_ (const String &name) const
 Returns the value of a previously registered flag. More...
 
const ParameterInformationfindEntry_ (const String &name) const
 Finds the entry in the parameters_ array that has the name name. More...
 
Param const & getParam_ () const
 Return all parameters relevant to this TOPP tool. More...
 
void checkParam_ (const Param &param, const String &filename, const String &location) const
 Checks top-level entries of param according to the information during registration. More...
 
void fileParamValidityCheck_ (const StringList &param_value, const String &param_name, const ParameterInformation &p) const
 checks if files of an input file list exist More...
 
void fileParamValidityCheck_ (String &param_value, const String &param_name, const ParameterInformation &p) const
 checks if an input file exists (respecting the flags) More...
 
void checkIfIniParametersAreApplicable_ (const Param &ini_params)
 Checks if the parameters of the provided ini file are applicable to this tool. More...
 
void printUsage_ ()
 Prints the tool-specific command line options and appends the common options. More...
 
virtual ExitCodes main_ (int argc, const char **argv)=0
 The actual "main" method. main_() is invoked by main(). More...
 
Debug and Log output
void writeLogInfo_ (const String &text) const
 Writes a string to the log file and to OPENMS_LOG_INFO. More...
 
void writeLogWarn_ (const String &text) const
 Writes a string to the log file and to OPENMS_LOG_WARN. More...
 
void writeLogError_ (const String &text) const
 Writes a string to the log file and to OPENMS_LOG_ERROR. More...
 
void writeDebug_ (const String &text, UInt min_level) const
 Writes a string to the log file and to OPENMS_LOG_DEBUG if the debug level is at least min_level. More...
 
void writeDebug_ (const String &text, const Param &param, UInt min_level) const
 Writes a String followed by a Param to the log file and to OPENMS_LOG_DEBUG if the debug level is at least min_level. More...
 
External processes (TODO consider creating another AdapterBase class)
ExitCodes runExternalProcess_ (const QString &executable, const QStringList &arguments, const QString &workdir="") const
 Runs an external process via ExternalProcess and prints its stderr output on failure or if debug_level > 4. More...
 
ExitCodes runExternalProcess_ (const QString &executable, const QStringList &arguments, String &proc_stdout, String &proc_stderr, const QString &workdir="") const
 

Private Member Functions

void enableLogging_ () const
 Ensures that at least some default logging destination is opened for writing in append mode. More...
 
virtual Param getSubsectionDefaults_ (const String &section) const
 This method should return the default parameters for subsections. More...
 
Param getSubsectionDefaults_ () const
 Returns a single Param object containing all subsection parameters. More...
 
Param parseCommandLine_ (const int argc, const char **argv, const String &misc="misc", const String &unknown="unknown")
 Parses command line arguments using parameter definitions from TOPPBase. More...
 

Private Attributes

String const tool_name_
 Tool name. This is assigned once and for all in the constructor. More...
 
String const tool_description_
 Tool description. This is assigned once and for all in the constructor. More...
 
Int const instance_number_
 Instance number. More...
 
String const ini_location_
 Location in the ini file where to look for parameters. More...
 
Param param_
 All parameters relevant to this invocation of the program. More...
 
Param param_inifile_
 All parameters specified in the ini file. More...
 
Param param_cmdline_
 Parameters from command line. More...
 
Param param_instance_
 Parameters from instance section. More...
 
Param param_common_tool_
 Parameters from common section with tool name. More...
 
Param param_common_
 Parameters from common section without tool name. More...
 
std::ofstream log_
 Log file stream. Use the writeLog_() and writeDebug_() methods to access it. More...
 
std::vector< ParameterInformationparameters_
 Storage location for parameter information. More...
 
std::map< String, Stringsubsections_
 Storage location and description for allowed subsections. More...
 
std::map< String, Stringsubsections_TOPP_
 Storage location and description for allowed subsections from TOPP tool's command-line parameters. More...
 

Internal parameter handling

String version_
 Version string (if empty, the OpenMS/TOPP version is printed) More...
 
String verboseVersion_
 Version string including additional revision/date time information. Note: This differs from version_ only if not provided by the user. More...
 
bool official_
 Flag indicating if this an official TOPP tool. More...
 
std::vector< Citationcitations_
 Papers, specific for this tool (will be shown in '–help') More...
 
bool toolhandler_test_
 Enable the ToolHandler tests. More...
 
String getParamAsString_ (const String &key, const String &default_value="") const
 Return the value of parameter key as a string or default_value if this value is not set. More...
 
Int getParamAsInt_ (const String &key, Int default_value=0) const
 Return the value of parameter key as an integer or default_value if this value is not set. More...
 
double getParamAsDouble_ (const String &key, double default_value=0) const
 Return the value of parameter key as a double or default_value if this value is not set. More...
 
StringList getParamAsStringList_ (const String &key, const StringList &default_value) const
 Return the value of parameter key as a StringList or default_value if this value is not set. More...
 
IntList getParamAsIntList_ (const String &key, const IntList &default_value) const
 Return the value of parameter key as a IntList or default_value if this value is not set. More...
 
DoubleList getParamAsDoubleList_ (const String &key, const DoubleList &default_value) const
 Return the value of parameter key as a DoubleList or default_value if this value is not set. More...
 
bool getParamAsBool_ (const String &key) const
 Return the value of flag parameter key as bool. More...
 
const ParamValuegetParam_ (const String &key) const
 Return the value key of parameters as DataValue. ParamValue::EMPTY indicates that a parameter was not found. More...
 
String getSubsection_ (const String &name) const
 Get the part of a parameter name that makes up the subsection. More...
 
Param getDefaultParameters_ () const
 Returns the default parameters. More...
 
Param getToolUserDefaults_ (const String &tool_name) const
 Returns the user defaults for the given tool, if any default parameters are stored in the users home. More...
 
const StringgetIniLocation_ () const
 Returns the location of the ini file where parameters are taken from. E.g. if the command line was TOPPTool -instance 17, then this will be "TOPPTool:17:". Note the ':' at the end. More...
 
const StringtoolName_ () const
 Returns the tool name. More...
 

File IO checking methods

Methods used to check the validity of input and output files in main_.

Checking input and output files is only necessary, if you did register the file as string option, e.g. when only a file prefix is given which is completed in the program.

The exceptions thrown in these methods are caught in the main method of this class. They do not have to be handled in the tool itself!

ProgressLogger::LogType log_type_
 Type of progress logging. More...
 
void inputFileReadable_ (const String &filename, const String &param_name) const
 Checks if an input file exists, is readable and is not empty. More...
 
void outputFileWritable_ (const String &filename, const String &param_name) const
 Checks if an output file is writable. More...
 
bool parseRange_ (const String &text, double &low, double &high) const
 Parses a range string ([a]:[b]) into two variables (doubles) More...
 
bool parseRange_ (const String &text, Int &low, Int &high) const
 Parses a range string ([a]:[b]) into two variables (integers) More...
 

Data processing auxiliary functions

bool test_mode_
 Test mode. More...
 
Int debug_level_
 Debug level set by -debug. More...
 
static String topp_ini_file_
 .TOPP.ini file for storing system default parameters More...
 
static const Citation cite_openms_
 The OpenMS citation. More...
 
void addText_ (const String &text)
 
ParameterInformationgetParameterByName_ (const String &name)
 Returns the parameter identified by the given name. More...
 
void addDataProcessing_ (ConsensusMap &map, const DataProcessing &dp) const
 Data processing setter for consensus maps. More...
 
void addDataProcessing_ (FeatureMap &map, const DataProcessing &dp) const
 Data processing setter for feature maps. More...
 
void addDataProcessing_ (PeakMap &map, const DataProcessing &dp) const
 Data processing setter for peak maps. More...
 
DataProcessing getProcessingInfo_ (DataProcessing::ProcessingAction action) const
 Returns the data processing information. More...
 
DataProcessing getProcessingInfo_ (const std::set< DataProcessing::ProcessingAction > &actions) const
 Returns the data processing information. More...
 
template<typename Writer >
void writeToolDescription_ (Writer &writer, std::string write_type, std::string fileExtension)
 Helper function avoiding repeated code between CTD, JSON and CWL. More...
 

Detailed Description

Base class for TOPP applications.

This base class implements functionality used in most TOPP tools:

  • parameter handling
  • file handling
  • progress logging

If you want to create a new TOPP tool, please take care of the following:

  • derive a new class from this class
  • implement the registerOptionsAndFlags_ and main_ methods
  • add a Doxygen page for the tool and add the page to TOPP.doxygen
  • hide the derived class in the OpenMS documentation by using Doxygen condition macros.
Todo:
: replace writeLog_, writeDebug_ with a logger concept we'd need something like -VLevels [LOGGERS] to specify which loggers shall print something the '-log' flag should clone all output to the log-file (maybe with custom [LOGGERS]), which can either be specified directly or is equal to '-out' (if present) with a ".log" suffix maybe a new LOGGER type (TOPP), which is only usable on TOPP level?

Member Enumeration Documentation

◆ ExitCodes

enum ExitCodes

Exit codes.

Enumerator
EXECUTION_OK 
INPUT_FILE_NOT_FOUND 
INPUT_FILE_NOT_READABLE 
INPUT_FILE_CORRUPT 
INPUT_FILE_EMPTY 
CANNOT_WRITE_OUTPUT_FILE 
ILLEGAL_PARAMETERS 
MISSING_PARAMETERS 
UNKNOWN_ERROR 
EXTERNAL_PROGRAM_ERROR 
PARSE_ERROR 
INCOMPATIBLE_INPUT_DATA 
INTERNAL_ERROR 
UNEXPECTED_RESULT 

Constructor & Destructor Documentation

◆ TOPPBase() [1/3]

TOPPBase ( )
delete

No default constructor.

◆ TOPPBase() [2/3]

TOPPBase ( const TOPPBase )
delete

No default copy constructor.

◆ TOPPBase() [3/3]

TOPPBase ( const String name,
const String description,
bool  official = true,
const std::vector< Citation > &  citations = {},
bool  toolhandler_test = true 
)

Constructor.

Parameters
nameTool name.
descriptionShort description of the tool (one line).
officialIf this is an official TOPP tool contained in the OpenMS/TOPP release. If true the tool name is checked against the list of TOPP tools and a warning printed if missing.
citationsAdd one or more citations if they are associated specifically to this TOPP tool; they will be printed during --help
toolhandler_testCheck if this tool is registered with the ToolHandler (disable for unit tests only)

◆ ~TOPPBase()

virtual ~TOPPBase ( )
virtual

Destructor.

Member Function Documentation

◆ addDataProcessing_() [1/3]

void addDataProcessing_ ( ConsensusMap map,
const DataProcessing dp 
) const
protected

Data processing setter for consensus maps.

◆ addDataProcessing_() [2/3]

void addDataProcessing_ ( FeatureMap map,
const DataProcessing dp 
) const
protected

Data processing setter for feature maps.

◆ addDataProcessing_() [3/3]

void addDataProcessing_ ( PeakMap map,
const DataProcessing dp 
) const
protected

Data processing setter for peak maps.

◆ addEmptyLine_()

void addEmptyLine_ ( )
protected

Adds an empty line between registered variables in the documentation.

◆ addText_()

void addText_ ( const String text)
private

Adds a left aligned text between registered variables in the documentation e.g. for subdividing the documentation. This should not be usable for derived classes, since this formatting is not carried over to INI files and thus INI files might lack important information. Instead, subdivision of parameters should be achieved using TOPPSubsections with appropriate description Currently only used for "Common TOPP options" within TOPPBase.cpp

◆ checkIfIniParametersAreApplicable_()

void checkIfIniParametersAreApplicable_ ( const Param ini_params)
protected

Checks if the parameters of the provided ini file are applicable to this tool.

This method does not abort execution of the tool, but will warn the user through stderr! It is called automatically whenever a ini file is loaded.

◆ checkParam_()

void checkParam_ ( const Param param,
const String filename,
const String location 
) const
protected

Checks top-level entries of param according to the information during registration.

Only top-level entries and allowed subsections are checked. Checking the content of the subsection is the duty of the algorithm it is passed to.

This method does not abort execution of the tool, but will warn the user through stderr! It is called automatically in the main method.

Parameters
paramParameters to check
filenameThe source file name
locationExact location inside the source file

◆ enableLogging_()

void enableLogging_ ( ) const
private

Ensures that at least some default logging destination is opened for writing in append mode.

Note
This might be invoked at various places early in the startup process of the TOPP tool. Thus we cannot consider the ini file here. The final logging destination is determined in main().

◆ fileParamValidityCheck_() [1/2]

void fileParamValidityCheck_ ( const StringList param_value,
const String param_name,
const ParameterInformation p 
) const
protected

checks if files of an input file list exist

Checks if String/Format restrictions are met (or throws InvalidParameter() otherwise).

Parameters
param_valueAs given via commandline/ini/default
param_nameName of the parameter (key)
pAll meta information for this param

◆ fileParamValidityCheck_() [2/2]

void fileParamValidityCheck_ ( String param_value,
const String param_name,
const ParameterInformation p 
) const
protected

checks if an input file exists (respecting the flags)

Checks if String/Format restrictions are met (or throws InvalidParameter() otherwise).

For InputFile(s), it checks if the file is readable/findable. If 'is_executable' is specified as a tag, the filename is searched on PATH and upon success, the full absolute path is returned.

For OutputFile(s), it checks if the file is writeable.

Parameters
param_valueAs given via commandline/ini/default
param_nameName of the parameter (key)
pAll meta information for this param

◆ findEntry_()

const ParameterInformation& findEntry_ ( const String name) const
protected

Finds the entry in the parameters_ array that has the name name.

Exceptions
Exception::UnregisteredParameteris thrown if the parameter was not registered

◆ getDefaultParameters_()

Param getDefaultParameters_ ( ) const
private

Returns the default parameters.

◆ getDocumentationURL()

String getDocumentationURL ( ) const

Returns a link to the documentation of the tool (accessible on our servers and only after inclusion in the nightly branch or a release).

◆ getDoubleList_()

DoubleList getDoubleList_ ( const String name) const
protected

Returns the value of a previously registered DoubleList.

Exceptions
Exception::UnregisteredParameteris thrown if the parameter was not registered
Exception::RequiredParameterNotGivenis if a required parameter is not present
Exception::WrongParameterTypeis thrown if the parameter has the wrong type
Exception::InvalidParameteris thrown if the parameter restrictions are not met

◆ getDoubleOption_()

double getDoubleOption_ ( const String name) const
protected

Returns the value of a previously registered double option.

Exceptions
Exception::UnregisteredParameteris thrown if the parameter was not registered
Exception::RequiredParameterNotGivenis if a required parameter is not present
Exception::WrongParameterTypeis thrown if the parameter has the wrong type
Exception::InvalidParameteris thrown if the parameter restrictions are not met

◆ getFlag_()

bool getFlag_ ( const String name) const
protected

Returns the value of a previously registered flag.

◆ getIniLocation_()

const String& getIniLocation_ ( ) const
inlineprotected

Returns the location of the ini file where parameters are taken from. E.g. if the command line was TOPPTool -instance 17, then this will be "TOPPTool:17:". Note the ':' at the end.

This is assigned during tool startup, depending on the command line but (of course) not depending on ini files.

◆ getIntList_()

IntList getIntList_ ( const String name) const
protected

Returns the value of a previously registered IntList.

Exceptions
Exception::UnregisteredParameteris thrown if the parameter was not registered
Exception::RequiredParameterNotGivenis if a required parameter is not present
Exception::WrongParameterTypeis thrown if the parameter has the wrong type
Exception::InvalidParameteris thrown if the parameter restrictions are not met

◆ getIntOption_()

Int getIntOption_ ( const String name) const
protected

Returns the value of a previously registered integer option.

Exceptions
Exception::UnregisteredParameteris thrown if the parameter was not registered
Exception::RequiredParameterNotGivenis if a required parameter is not present
Exception::WrongParameterTypeis thrown if the parameter has the wrong type
Exception::InvalidParameteris thrown if the parameter restrictions are not met

◆ getParam_() [1/2]

Param const& getParam_ ( ) const
protected

Return all parameters relevant to this TOPP tool.

Returns a Param that contains everything you can get by the getParamAs...() methods.

Referenced by TOPPOpenSwathBase::performCalibration().

◆ getParam_() [2/2]

const ParamValue& getParam_ ( const String key) const
private

Return the value key of parameters as DataValue. ParamValue::EMPTY indicates that a parameter was not found.

Parameters are searched in this order:

  1. command line
  2. instance section, e.g. "TOPPTool:1:some_key", see getIniLocation_().
  3. common section with tool name, e.g. "common:ToolName:some_key"
  4. common section without tool name, e.g. "common:some_key"

where "some_key" == key in the examples.

◆ getParamArgument_()

String getParamArgument_ ( const Param::ParamEntry entry) const
protected

Utility function that determines a suitable argument value for the given Param::ParamEntry.

◆ getParamAsBool_()

bool getParamAsBool_ ( const String key) const
private

Return the value of flag parameter key as bool.

Only the string values 'true' and 'false' are interpreted.

Exceptions
Exception::InvalidParameteris thrown for non-string parameters and string parameters with values other than 'true' and 'false'.
Note
See getParam_(const String&) const for the order in which parameters are searched.

◆ getParamAsDouble_()

double getParamAsDouble_ ( const String key,
double  default_value = 0 
) const
private

Return the value of parameter key as a double or default_value if this value is not set.

Note
See getParam_(const String&) const for the order in which parameters are searched.

◆ getParamAsDoubleList_()

DoubleList getParamAsDoubleList_ ( const String key,
const DoubleList default_value 
) const
private

Return the value of parameter key as a DoubleList or default_value if this value is not set.

Note
See getParam_(const String&) const for the order in which parameters are searched.

◆ getParamAsInt_()

Int getParamAsInt_ ( const String key,
Int  default_value = 0 
) const
private

Return the value of parameter key as an integer or default_value if this value is not set.

Note
See getParam_(const String&) const for the order in which parameters are searched.

◆ getParamAsIntList_()

IntList getParamAsIntList_ ( const String key,
const IntList default_value 
) const
private

Return the value of parameter key as a IntList or default_value if this value is not set.

Note
See getParam_(const String&) const for the order in which parameters are searched.

◆ getParamAsString_()

String getParamAsString_ ( const String key,
const String default_value = "" 
) const
private

Return the value of parameter key as a string or default_value if this value is not set.

Note
See getParam_(const String&) const for the order in which parameters are searched.

◆ getParamAsStringList_()

StringList getParamAsStringList_ ( const String key,
const StringList default_value 
) const
private

Return the value of parameter key as a StringList or default_value if this value is not set.

Note
See getParam_(const String&) const for the order in which parameters are searched.

◆ getParameterByName_()

ParameterInformation& getParameterByName_ ( const String name)
private

Returns the parameter identified by the given name.

Parameters
nameThe name of the parameter to search.
Exceptions
Exception::UnregisteredParameteris thrown if the parameter was not registered
Returns
A reference to the parameter with the given name.

◆ getProcessingInfo_() [1/2]

DataProcessing getProcessingInfo_ ( const std::set< DataProcessing::ProcessingAction > &  actions) const
protected

Returns the data processing information.

◆ getProcessingInfo_() [2/2]

DataProcessing getProcessingInfo_ ( DataProcessing::ProcessingAction  action) const
protected

Returns the data processing information.

Referenced by TOPPOpenSwathBase::prepareChromOutput().

◆ getStringList_()

StringList getStringList_ ( const String name) const
protected

Returns the value of a previously registered StringList.

Exceptions
Exception::UnregisteredParameteris thrown if the parameter was not registered
Exception::RequiredParameterNotGivenis if a required parameter is not present
Exception::WrongParameterTypeis thrown if the parameter has the wrong type
Exception::InvalidParameteris thrown if the parameter restrictions are not met

◆ getStringOption_()

String getStringOption_ ( const String name) const
protected

Returns the value of a previously registered string option.

Exceptions
Exception::UnregisteredParameteris thrown if the parameter was not registered
Exception::RequiredParameterNotGivenis if a required parameter is not present
Exception::WrongParameterTypeis thrown if the parameter has the wrong type
Exception::InvalidParameteris thrown if the parameter restrictions are not met

◆ getSubsection_()

String getSubsection_ ( const String name) const
private

Get the part of a parameter name that makes up the subsection.

The subsection extends until the last colon (":"). If there is no subsection, the empty string is returned.

◆ getSubsectionDefaults_() [1/2]

Param getSubsectionDefaults_ ( ) const
private

Returns a single Param object containing all subsection parameters.

Returns
A single Param object containing all parameters for all registered subsections.
See also
getSubsectionDefaults_(String)

◆ getSubsectionDefaults_() [2/2]

virtual Param getSubsectionDefaults_ ( const String section) const
privatevirtual

This method should return the default parameters for subsections.

It is called once for each registered subsection, when writing the example ini file.

Reimplement this method to set the defaults written in the 'write_ini' method.

Note
Make sure to set the 'advanced' flag of the parameters right in order to hide certain parameters from inexperienced users.

◆ getToolPrefix()

String getToolPrefix ( ) const

Returns the prefix used to identify the tool.

This prefix is later found in the INI file for a TOPP tool. f.e.: "FileConverter:1:"

◆ getToolUserDefaults_()

Param getToolUserDefaults_ ( const String tool_name) const
private

Returns the user defaults for the given tool, if any default parameters are stored in the users home.

◆ inputFileReadable_()

void inputFileReadable_ ( const String filename,
const String param_name 
) const
protected

Checks if an input file exists, is readable and is not empty.

The filename is a URI to the file to be read and param_name gives the name of the parameter , e.g. "in" which specified the filename (this is useful for error messages when the file cannot be read, so the user can immediately see which parameter to change). If no parameter is responsible for the name of the input file, then leave param_name empty.

Parameters
filenameAn absolute or relative path+filename
param_nameName of the parameter the filename value was provided by
Exceptions
Exception::FileNotFoundis thrown if the file is not found
Exception::FileNotReadableis thrown if the file is not readable
Exception::FileEmptyis thrown if the file is empty

◆ main()

ExitCodes main ( int  argc,
const char **  argv 
)

Main routine of all TOPP applications.

Referenced by main().

◆ main_()

virtual ExitCodes main_ ( int  argc,
const char **  argv 
)
protectedpure virtual

The actual "main" method. main_() is invoked by main().

Implemented in NucleicAcidSearchEngine, TOPPGNPSExport, and TOPPFLASHDeconv.

◆ outputFileWritable_()

void outputFileWritable_ ( const String filename,
const String param_name 
) const
protected

Checks if an output file is writable.

The filename is a URI to the file to be written and param_name gives the name of the parameter , e.g. "out" which specified the filename (this is useful for error messages when the file cannot be written, so the user can immediately see which parameter to change). If no parameter is responsible for the name of the output file, then leave param_name empty.

Exceptions
Exception::UnableToCreateFileis thrown if the file cannot be created

◆ paramEntryToParameterInformation_()

ParameterInformation paramEntryToParameterInformation_ ( const Param::ParamEntry entry,
const String argument = "",
const String full_name = "" 
) const
protected

Transforms a ParamEntry object to command line parameter (ParameterInformation).

A ParamEntry of type String is turned into a flag if its default value is "false" and its valid strings are "true" and "false".

Parameters
entryThe ParamEntry that defines name, default value, description, restrictions, and required-/advancedness (via tags) of the parameter.
argumentArgument description text for the help output.
full_nameFull name of the parameter, if different from the name in the ParamEntry (ParamEntry names cannot contain sections)

◆ paramToParameterInformation_()

std::vector<ParameterInformation> paramToParameterInformation_ ( const Param param) const
protected

Translates the given parameter object into a vector of ParameterInformation, that can be utilized for cl parsing.

◆ parseCommandLine_()

Param parseCommandLine_ ( const int  argc,
const char **  argv,
const String misc = "misc",
const String unknown = "unknown" 
)
private

Parses command line arguments using parameter definitions from TOPPBase.

Parses command line arguments according to the current parameter definitions and returns the result as a Param object.

Parameters
argcargc variable from command line
argvargv variable from command line
miscKey to store a StringList of all non-option arguments
unknownKey to store a StringList of all unknown options
Returns
A Param object representing the parameters set on the command line.

◆ parseRange_() [1/2]

bool parseRange_ ( const String text,
double &  low,
double &  high 
) const
protected

Parses a range string ([a]:[b]) into two variables (doubles)

The variables are only overwritten if a value is set for the respective boundary.

Returns
True if a value was set for either of the two boundaries

◆ parseRange_() [2/2]

bool parseRange_ ( const String text,
Int low,
Int high 
) const
protected

Parses a range string ([a]:[b]) into two variables (integers)

The variables are only overwritten if a value is set for the respective boundary.

Returns
True if a value was set for either of the two boundaries

◆ printUsage_()

void printUsage_ ( )
protected

Prints the tool-specific command line options and appends the common options.

◆ registerDoubleList_()

void registerDoubleList_ ( const String name,
const String argument,
const DoubleList default_value,
const String description,
bool  required = true,
bool  advanced = false 
)
protected

Registers a list of doubles option.

Parameters
nameName of the option in the command line and the INI file
argumentArgument description text for the help output
default_valueDefault argument
descriptionDescription of the parameter. Indentation of newline is done automatically.
requiredIf the user has to provide a value i.e. if the value has to differ from the default (checked in get-method)
advancedIf true, this parameter is advanced and by default hidden in the GUI.

◆ registerDoubleOption_()

void registerDoubleOption_ ( const String name,
const String argument,
double  default_value,
const String description,
bool  required = true,
bool  advanced = false 
)
protected

Registers a double option.

Parameters
nameName of the option in the command line and the INI file
argumentArgument description text for the help output
default_valueDefault argument
descriptionDescription of the parameter. Indentation of newline is done automatically.
requiredIf the user has to provide a value i.e. if the value has to differ from the default (checked in get-method)
advancedIf true, this parameter is advanced and by default hidden in the GUI.

◆ registerFlag_()

void registerFlag_ ( const String name,
const String description,
bool  advanced = false 
)
protected

Registers a flag.

◆ registerFullParam_()

void registerFullParam_ ( const Param param)
protected

Register command line parameters for all entries in a Param object.

◆ registerInputFile_()

void registerInputFile_ ( const String name,
const String argument,
const String default_value,
const String description,
bool  required = true,
bool  advanced = false,
const StringList tags = StringList() 
)
protected

Registers an input file option.

Input files behave like string options, but are automatically checked with inputFileReadable_() when the option is accessed in the TOPP tool. This may also enable lookup on the PATH or skipping of the existence-check (see tags).

Parameters
nameName of the option in the command line and the INI file
argumentArgument description text for the help output
default_valueDefault argument
descriptionDescription of the parameter. Indentation of newline is done automatically.
requiredIf the user has to provide a value i.e. if the value has to differ from the default (verified in getStringOption())
advancedIf true, this parameter is advanced and by default hidden in the GUI.
tagsA list of tags, extending/omitting automated checks on the input file (e.g. when its an executable) Valid tags: 'skipexists' - will prevent checking if the given file really exists (useful for partial paths, e.g. in OpenMS/share/... which will be resolved by the TOPP tool internally) 'is_executable' - checks existence of the file first using its actual value, and upon failure also using the PATH environment (and common exe file endings on Windows, e.g. .exe and .bat).

◆ registerInputFileList_()

void registerInputFileList_ ( const String name,
const String argument,
const StringList default_value,
const String description,
bool  required = true,
bool  advanced = false,
const StringList tags = StringList() 
)
protected

Registers a list of input files option.

A list of input files behaves like a StringList, but are automatically checked with inputFileWritable_() when the option is accessed in the TOPP tool.

Parameters
nameName of the option in the command line and the INI file
argumentArgument description text for the help output
default_valueDefault argument
descriptionDescription of the parameter. Indentation of newline is done automatically.
requiredIf the user has to provide a value i.e. if the value has to differ from the default (checked in get-method)
advancedIf true, this parameter is advanced and by default hidden in the GUI.
tagsA list of tags, extending/omitting automated checks on the input file (e.g. when its an executable) Valid tags: 'skipexists' - will prevent checking if the given file really exists (useful for partial paths, e.g. in OpenMS/share/... which will be resolved by the TOPP tool internally) 'is_executable' - checks existence of the file using the PATH environment (and common exe file endings on Windows, e.g. .exe and .bat).

◆ registerIntList_()

void registerIntList_ ( const String name,
const String argument,
const IntList default_value,
const String description,
bool  required = true,
bool  advanced = false 
)
protected

Registers a list of integers option.

Parameters
nameName of the option in the command line and the INI file
argumentArgument description text for the help output
default_valueDefault argument
descriptionDescription of the parameter. Indentation of newline is done automatically.
requiredIf the user has to provide a value i.e. if the value has to differ from the default (checked in get-method)
advancedIf true, this parameter is advanced and by default hidden in the GUI.

◆ registerIntOption_()

void registerIntOption_ ( const String name,
const String argument,
Int  default_value,
const String description,
bool  required = true,
bool  advanced = false 
)
protected

Registers an integer option.

Parameters
nameName of the option in the command line and the INI file
argumentArgument description text for the help output
default_valueDefault argument
descriptionDescription of the parameter. Indentation of newline is done automatically.
requiredIf the user has to provide a value i.e. if the value has to differ from the default (checked in get-method)
advancedIf true, this parameter is advanced and by default hidden in the GUI.

◆ registerOptionsAndFlags_()

virtual void registerOptionsAndFlags_ ( )
protectedpure virtual

Sets the valid command line options (with argument) and flags (without argument).

The options '-ini' '-log' '-instance' '-debug' and the flag '–help' are automatically registered.

Implemented in NucleicAcidSearchEngine, TOPPGNPSExport, and TOPPFLASHDeconv.

◆ registerOutputFile_()

void registerOutputFile_ ( const String name,
const String argument,
const String default_value,
const String description,
bool  required = true,
bool  advanced = false 
)
protected

Registers an output file option.

Output files behave like string options, but are automatically checked with outputFileWritable_() when the option is accessed in the TOPP tool.

Parameters
nameName of the option in the command line and the INI file
argumentArgument description text for the help output
default_valueDefault argument
descriptionDescription of the parameter. Indentation of newline is done automatically.
requiredIf the user has to provide a value i.e. if the value has to differ from the default (checked in get-method)
advancedIf true, this parameter is advanced and by default hidden in the GUI.

◆ registerOutputFileList_()

void registerOutputFileList_ ( const String name,
const String argument,
const StringList default_value,
const String description,
bool  required = true,
bool  advanced = false 
)
protected

Registers a list of output files option.

A list of output files behaves like a StringList, but are automatically checked with outputFileWritable_() when the option is accessed in the TOPP tool.

Parameters
nameName of the option in the command line and the INI file
argumentArgument description text for the help output
default_valueDefault argument
descriptionDescription of the parameter. Indentation of newline is done automatically.
requiredIf the user has to provide a value i.e. if the value has to differ from the default (checked in get-method)
advancedIf true, this parameter is advanced and by default hidden in the GUI.

◆ registerOutputPrefix_()

void registerOutputPrefix_ ( const String name,
const String argument,
const String default_value,
const String description,
bool  required = true,
bool  advanced = false 
)
protected

Registers an output file prefix used for tools with multiple file output.

Tools should follow the convention to name output files PREFIX_[0..N-1].EXTENSION. For example, a tool that splits mzML files into multiple mgf files should create files: splitted_0.mgf, splitted_1.mgf, ... if splitted got passed as prefix.

Note: setting format(s) via setValidFormat_ for an output prefix can be used to export e.g. valid CTD files that contain information on the expected output file types. In theory, it is possible to output different types and list them here but this should be avoided for cleanlyness (prefer multiple separate outputs). This could be left empty in case of an unknown amount of different extensions that are produced but is highly recommended.

Parameters
nameName of the option in the command line and the INI file
argumentArgument description text for the help output
default_valueDefault value (remember, no extension is specified here)
descriptionDescription of the parameter. Indentation of newline is done automatically.
requiredIf the user has to provide a value i.e. if the value has to differ from the default (checked in get-method)
advancedIf true, this parameter is advanced and by default hidden in the GUI.

◆ registerParamSubsectionsAsTOPPSubsections_()

void registerParamSubsectionsAsTOPPSubsections_ ( const Param param)
protected

◆ registerStringList_()

void registerStringList_ ( const String name,
const String argument,
const StringList default_value,
const String description,
bool  required = true,
bool  advanced = false 
)
protected

Registers a list of strings option.

Parameters
nameName of the option in the command line and the INI file
argumentArgument description text for the help output
default_valueDefault argument
descriptionDescription of the parameter. Indentation of newline is done automatically.
requiredIf the user has to provide a value i.e. if the value has to differ from the default (checked in get-method)
advancedIf true, this parameter is advanced and by default hidden in the GUI.

◆ registerStringOption_()

void registerStringOption_ ( const String name,
const String argument,
const String default_value,
const String description,
bool  required = true,
bool  advanced = false 
)
protected

Registers a string option.

Parameters
nameName of the option in the command line and the INI file
argumentArgument description text for the help output
default_valueDefault argument
descriptionDescription of the parameter. Indentation of newline is done automatically.
requiredIf the user has to provide a value i.e. if the value has to differ from the default (checked in get-method)
advancedIf true, this parameter is advanced and by default hidden in the GUI.

◆ registerSubsection_()

void registerSubsection_ ( const String name,
const String description 
)
protected

Registers an allowed subsection in the INI file (usually from OpenMS algorithms).

Use this method to register subsections that are passed to algorithms.

See also
checkParam_

◆ registerTOPPSubsection_()

void registerTOPPSubsection_ ( const String name,
const String description 
)
protected

Registers an allowed subsection in the INI file originating from the TOPP tool itself.

Use this method to register subsections which is created by a commandline param (registered by e.g. registerDoubleOption_() ) and contains a ':' in its name. This is done to distinguish these parameters from normal subsections, which are filled by calling 'getSubsectionDefaults_()'. This is not necessary for here.

See also
checkParam_

◆ runExternalProcess_() [1/2]

ExitCodes runExternalProcess_ ( const QString &  executable,
const QStringList &  arguments,
const QString &  workdir = "" 
) const
protected

Runs an external process via ExternalProcess and prints its stderr output on failure or if debug_level > 4.

◆ runExternalProcess_() [2/2]

ExitCodes runExternalProcess_ ( const QString &  executable,
const QStringList &  arguments,
String proc_stdout,
String proc_stderr,
const QString &  workdir = "" 
) const
protected

Runs an external process via ExternalProcess and prints its stderr output on failure or if debug_level > 4 Additionally returns the process' stdout and stderr

◆ setMaxFloat_()

void setMaxFloat_ ( const String name,
double  max 
)
protected

Sets the maximum value for the floating point parameter(can be a list of floating points,too) name.

Exceptions
Exception::ElementNotFoundis thrown if name is not found or if the parameter type is wrong

◆ setMaxInt_()

void setMaxInt_ ( const String name,
Int  max 
)
protected

Sets the maximum value for the integer parameter(can be a list of integers,too) name.

Exceptions
Exception::ElementNotFoundis thrown if name is not found or if the parameter type is wrong

◆ setMaxNumberOfThreads()

static void setMaxNumberOfThreads ( int  num_threads)
static

Sets the maximal number of usable threads.

Parameters
num_threadsThe number of threads that should be usable.
Note
This method only works if OpenMS is compiled with OpenMP support.

◆ setMinFloat_()

void setMinFloat_ ( const String name,
double  min 
)
protected

Sets the minimum value for the floating point parameter(can be a list of floating points,too) name.

Exceptions
Exception::ElementNotFoundis thrown if name is not found or if the parameter type is wrong

◆ setMinInt_()

void setMinInt_ ( const String name,
Int  min 
)
protected

Sets the minimum value for the integer parameter(can be a list of integers,too) name.

Exceptions
Exception::ElementNotFoundis thrown if name is not found or if the parameter type is wrong

◆ setValidFormats_()

void setValidFormats_ ( const String name,
const std::vector< String > &  formats,
const bool  force_OpenMS_format = true 
)
protected

Sets the formats for a input/output file option or for all members of an input/output file lists.

Setting the formats causes a check for the right file format (input file) or the right file extension (output file). This check is performed only, when the option is accessed in the TOPP tool. When force_OpenMS_format is set, only formats known to OpenMS internally are allowed (default).

Note: Formats for output file prefixes are exported to e.g. CTD but no checks are performed (as they don't contain a file extension)

Exceptions
Exception::ElementNotFoundis thrown if the parameter is unset or not a file parameter
Exception::InvalidParameteris thrown if an unknown format name is used (
See also
FileHandler::Type)

◆ setValidStrings_() [1/2]

void setValidStrings_ ( const String name,
const std::string  vstrings[],
int  count 
)
protected

Sets the valid strings for a string option or a whole string list.

This overload should be used for options which are 1:1 with Enums + their static string representations. E.g. MSNumpressCoder::NamesOfNumpressCompression[]

Exceptions
Exception::ElementNotFoundis thrown if the parameter is unset or not a string parameter
Exception::InvalidParameteris thrown if the valid strings contain comma characters

◆ setValidStrings_() [2/2]

void setValidStrings_ ( const String name,
const std::vector< String > &  strings 
)
protected

Sets the valid strings for a string option or a whole string list.

Exceptions
Exception::ElementNotFoundis thrown if the parameter is unset or not a string parameter
Exception::InvalidParameteris thrown if the valid strings contain comma characters

◆ toolName_()

const String& toolName_ ( ) const
protected

Returns the tool name.

◆ writeDebug_() [1/2]

void writeDebug_ ( const String text,
const Param param,
UInt  min_level 
) const
protected

Writes a String followed by a Param to the log file and to OPENMS_LOG_DEBUG if the debug level is at least min_level.

◆ writeDebug_() [2/2]

void writeDebug_ ( const String text,
UInt  min_level 
) const
protected

Writes a string to the log file and to OPENMS_LOG_DEBUG if the debug level is at least min_level.

◆ writeLogError_()

void writeLogError_ ( const String text) const
protected

Writes a string to the log file and to OPENMS_LOG_ERROR.

◆ writeLogInfo_()

void writeLogInfo_ ( const String text) const
protected

Writes a string to the log file and to OPENMS_LOG_INFO.

◆ writeLogWarn_()

void writeLogWarn_ ( const String text) const
protected

Writes a string to the log file and to OPENMS_LOG_WARN.

◆ writeToolDescription_()

void writeToolDescription_ ( Writer &  writer,
std::string  write_type,
std::string  fileExtension 
)
protected

Helper function avoiding repeated code between CTD, JSON and CWL.

Parameters
writera parameter writer, designed to be of type ParamCTDFile, ParamJSONFile or ParamCWLFile
write_typeThe type of file that is being written, typically write_ctd, write_json or write_cwl.
fileExtensionThe extension of the requested tool description file.

Member Data Documentation

◆ citations_

std::vector<Citation> citations_
protected

Papers, specific for this tool (will be shown in '–help')

◆ cite_openms_

const Citation cite_openms_
staticprotected

The OpenMS citation.

◆ debug_level_

Int debug_level_
protected

Debug level set by -debug.

◆ ini_location_

String const ini_location_
private

Location in the ini file where to look for parameters.

◆ instance_number_

Int const instance_number_
private

Instance number.

◆ log_

std::ofstream log_
mutableprivate

Log file stream. Use the writeLog_() and writeDebug_() methods to access it.

◆ log_type_

◆ official_

bool official_
protected

Flag indicating if this an official TOPP tool.

◆ param_

Param param_
private

All parameters relevant to this invocation of the program.

◆ param_cmdline_

Param param_cmdline_
private

Parameters from command line.

◆ param_common_

Param param_common_
private

Parameters from common section without tool name.

◆ param_common_tool_

Param param_common_tool_
private

Parameters from common section with tool name.

◆ param_inifile_

Param param_inifile_
private

All parameters specified in the ini file.

◆ param_instance_

Param param_instance_
private

Parameters from instance section.

◆ parameters_

std::vector<ParameterInformation> parameters_
private

Storage location for parameter information.

◆ subsections_

std::map<String, String> subsections_
private

Storage location and description for allowed subsections.

◆ subsections_TOPP_

std::map<String, String> subsections_TOPP_
private

Storage location and description for allowed subsections from TOPP tool's command-line parameters.

◆ test_mode_

bool test_mode_
protected

Test mode.

Test mode is enabled using the command line parameter -test .

It disables writing of data, which would corrupt tests:

  • absolute paths (e.g. in consensus maps)
  • processing parameters (input/output files contain absolute paths as well)
  • current date
  • current OpenMS version

◆ tool_description_

String const tool_description_
private

Tool description. This is assigned once and for all in the constructor.

◆ tool_name_

String const tool_name_
private

Tool name. This is assigned once and for all in the constructor.

◆ toolhandler_test_

bool toolhandler_test_
protected

Enable the ToolHandler tests.

◆ topp_ini_file_

String topp_ini_file_
staticprotected

.TOPP.ini file for storing system default parameters

◆ verboseVersion_

String verboseVersion_
protected

Version string including additional revision/date time information. Note: This differs from version_ only if not provided by the user.

◆ version_

String version_
protected

Version string (if empty, the OpenMS/TOPP version is printed)