Base class for TOPP applications. More...

#include <OpenMS/APPLICATIONS/TOPPBase.h>

Inheritance diagram for TOPPBase:

Collaboration diagram for TOPPBase:

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

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_, 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< ParameterInformation >	paramToParameterInformation_ (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	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, 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, 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, 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, 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, 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 ParameterInformation &	findEntry_ (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	writeLog_ (const String &text) const
	Writes a string to the log file and to std::cout. More...

void	writeDebug_ (const String &text, UInt min_level) const
	Writes a `text` to the log file and to std::cout 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 std::cout 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< ParameterInformation >	parameters_
	Storage location for parameter information. More...

std::map< String, String >	subsections_
	Storage location and description for allowed subsections. More...

std::map< String, String >	subsections_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< Citation >	citations_
	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 ParamValue &	getParam_ (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...

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

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 String &	getIniLocation_ () 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 String &	toolName_ () 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)

ParameterInformation &	getParameterByName_ (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...

bool	writeCTD_ ()
	Write common tool description (CTD) file. 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

name	Tool name.
description	Short description of the tool (one line).
official	If 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.
citations	Add one or more citations if they are associated specifically to this TOPP tool; they will be printed during –help

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

param	Parameters to check
filename	The source file name
location	Exact 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_value	As given via commandline/ini/default
param_name	Name of the parameter (key)
p	All 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_value	As given via commandline/ini/default
param_name	Name of the parameter (key)
p	All 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::UnregisteredParameter is thrown if the parameter was not registered

◆ getDefaultParameters_()

Param getDefaultParameters_ ( ) const

private

Returns the default parameters.

◆ getDocumentationURL()

String getDocumentationURL ( ) const

private

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::UnregisteredParameter	is thrown if the parameter was not registered
Exception::RequiredParameterNotGiven	is if a required parameter is not present
Exception::WrongParameterType	is thrown if the parameter has the wrong type
Exception::InvalidParameter	is 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::UnregisteredParameter	is thrown if the parameter was not registered
Exception::RequiredParameterNotGiven	is if a required parameter is not present
Exception::WrongParameterType	is thrown if the parameter has the wrong type
Exception::InvalidParameter	is 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::UnregisteredParameter	is thrown if the parameter was not registered
Exception::RequiredParameterNotGiven	is if a required parameter is not present
Exception::WrongParameterType	is thrown if the parameter has the wrong type
Exception::InvalidParameter	is 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::UnregisteredParameter	is thrown if the parameter was not registered
Exception::RequiredParameterNotGiven	is if a required parameter is not present
Exception::WrongParameterType	is thrown if the parameter has the wrong type
Exception::InvalidParameter	is 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:

command line
instance section, e.g. "TOPPTool:1:some_key", see getIniLocation_().
common section with tool name, e.g. "common:ToolName:some_key"
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::InvalidParameter is 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

name	The name of the parameter to search.

Exceptions

Exception::UnregisteredParameter is 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::UnregisteredParameter	is thrown if the parameter was not registered
Exception::RequiredParameterNotGiven	is if a required parameter is not present
Exception::WrongParameterType	is thrown if the parameter has the wrong type
Exception::InvalidParameter	is 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::UnregisteredParameter	is thrown if the parameter was not registered
Exception::RequiredParameterNotGiven	is if a required parameter is not present
Exception::WrongParameterType	is thrown if the parameter has the wrong type
Exception::InvalidParameter	is 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

filename	An absolute or relative path+filename
param_name	Name of the parameter the filename value was provided by

Exceptions

Exception::FileNotFound	is thrown if the file is not found
Exception::FileNotReadable	is thrown if the file is not readable
Exception::FileEmpty	is 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, and TOPPGNPSExport.

◆ 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::UnableToCreateFile is 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

entry	The ParamEntry that defines name, default value, description, restrictions, and required-/advancedness (via tags) of the parameter.
argument	Argument description text for the help output.
full_name	Full 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

argc	`argc` variable from command line
argv	`argv` variable from command line
misc	Key to store a StringList of all non-option arguments
unknown	Key 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,
		DoubleList	default_value,
		const String &	description,
		bool	required = `true`,
		bool	advanced = `false`
	)

protected

Registers a list of doubles option.

Parameters

name	Name of the option in the command line and the INI file
argument	Argument description text for the help output
default_value	Default argument
description	Description of the parameter. Indentation of newline is done automatically.
required	If the user has to provide a value i.e. if the value has to differ from the default (checked in get-method)
advanced	If 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

name	Name of the option in the command line and the INI file
argument	Argument description text for the help output
default_value	Default argument
description	Description of the parameter. Indentation of newline is done automatically.
required	If the user has to provide a value i.e. if the value has to differ from the default (checked in get-method)
advanced	If 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

name	Name of the option in the command line and the INI file
argument	Argument description text for the help output
default_value	Default argument
description	Description of the parameter. Indentation of newline is done automatically.
required	If the user has to provide a value i.e. if the value has to differ from the default (verified in getStringOption())
advanced	If true, this parameter is advanced and by default hidden in the GUI.
tags	A 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,
		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

name	Name of the option in the command line and the INI file
argument	Argument description text for the help output
default_value	Default argument
description	Description of the parameter. Indentation of newline is done automatically.
required	If the user has to provide a value i.e. if the value has to differ from the default (checked in get-method)
advanced	If true, this parameter is advanced and by default hidden in the GUI.
tags	A 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,
		IntList	default_value,
		const String &	description,
		bool	required = `true`,
		bool	advanced = `false`
	)

protected

Registers a list of integers option.

Parameters

name	Name of the option in the command line and the INI file
argument	Argument description text for the help output
default_value	Default argument
description	Description of the parameter. Indentation of newline is done automatically.
required	If the user has to provide a value i.e. if the value has to differ from the default (checked in get-method)
advanced	If 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

name	Name of the option in the command line and the INI file
argument	Argument description text for the help output
default_value	Default argument
description	Description of the parameter. Indentation of newline is done automatically.
required	If the user has to provide a value i.e. if the value has to differ from the default (checked in get-method)
advanced	If 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, and TOPPGNPSExport.

◆ 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

name	Name of the option in the command line and the INI file
argument	Argument description text for the help output
default_value	Default argument
description	Description of the parameter. Indentation of newline is done automatically.
required	If the user has to provide a value i.e. if the value has to differ from the default (checked in get-method)
advanced	If true, this parameter is advanced and by default hidden in the GUI.

◆ registerOutputFileList_()

void registerOutputFileList_	(	const String &	name,
		const String &	argument,
		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

name	Name of the option in the command line and the INI file
argument	Argument description text for the help output
default_value	Default argument
description	Description of the parameter. Indentation of newline is done automatically.
required	If the user has to provide a value i.e. if the value has to differ from the default (checked in get-method)
advanced	If 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,
		StringList	default_value,
		const String &	description,
		bool	required = `true`,
		bool	advanced = `false`
	)

protected

Registers a list of strings option.

Parameters

name	Name of the option in the command line and the INI file
argument	Argument description text for the help output
default_value	Default argument
description	Description of the parameter. Indentation of newline is done automatically.
required	If the user has to provide a value i.e. if the value has to differ from the default (checked in get-method)
advanced	If 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

name	Name of the option in the command line and the INI file
argument	Argument description text for the help output
default_value	Default argument
description	Description of the parameter. Indentation of newline is done automatically.
required	If the user has to provide a value i.e. if the value has to differ from the default (checked in get-method)
advanced	If 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::ElementNotFound is 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::ElementNotFound is 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_threads The 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::ElementNotFound is 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::ElementNotFound is 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).

Exceptions

Exception::ElementNotFound	is thrown if the parameter is unset or not a file parameter
Exception::InvalidParameter	is 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::ElementNotFound	is thrown if the parameter is unset or not a string parameter
Exception::InvalidParameter	is 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::ElementNotFound	is thrown if the parameter is unset or not a string parameter
Exception::InvalidParameter	is thrown if the valid strings contain comma characters

◆ toolName_()

const String& toolName_ ( ) const

protected

Returns the tool name.

◆ writeCTD_()

bool writeCTD_ ( )

protected

Write common tool description (CTD) file.

◆ 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 std::cout if the debug level is at least min_level.

◆ writeDebug_() [2/2]

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

protected

Writes a text to the log file and to std::cout if the debug level is at least min_level.

◆ writeLog_()

void writeLog_ ( const String & text ) const

protected

Writes a string to the log file and to std::cout.

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_

ProgressLogger::LogType log_type_

protected

Type of progress logging.

Referenced by TOPPOpenSwathBase::loadSwathFiles_(), TOPPOpenSwathBase::loadTransitionList(), and TOPPOpenSwathBase::performCalibration().

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

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Private Member Functions

Private Attributes

Internal parameter handling

File IO checking methods

Data processing auxiliary functions

Detailed Description

Member Enumeration Documentation

◆ ExitCodes

Constructor & Destructor Documentation

◆ TOPPBase() [1/3]

◆ TOPPBase() [2/3]

◆ TOPPBase() [3/3]

◆ ~TOPPBase()

Member Function Documentation

◆ addDataProcessing_() [1/3]

◆ addDataProcessing_() [2/3]

◆ addDataProcessing_() [3/3]

◆ addEmptyLine_()

◆ addText_()

◆ checkIfIniParametersAreApplicable_()

◆ checkParam_()

◆ enableLogging_()

◆ fileParamValidityCheck_() [1/2]

◆ fileParamValidityCheck_() [2/2]

◆ findEntry_()

◆ getDefaultParameters_()

◆ getDocumentationURL()

◆ getDoubleList_()

◆ getDoubleOption_()

◆ getFlag_()

◆ getIniLocation_()

◆ getIntList_()

◆ getIntOption_()

◆ getParam_() [1/2]

◆ getParam_() [2/2]

◆ getParamArgument_()

◆ getParamAsBool_()

◆ getParamAsDouble_()

◆ getParamAsDoubleList_()

◆ getParamAsInt_()

◆ getParamAsIntList_()

◆ getParamAsString_()

◆ getParamAsStringList_()

◆ getParameterByName_()

◆ getProcessingInfo_() [1/2]

◆ getProcessingInfo_() [2/2]

◆ getStringList_()

◆ getStringOption_()

◆ getSubsection_()

◆ getSubsectionDefaults_() [1/2]

◆ getSubsectionDefaults_() [2/2]

◆ getToolPrefix()

◆ getToolUserDefaults_()

◆ inputFileReadable_()

◆ main()

◆ main_()

◆ outputFileWritable_()

◆ paramEntryToParameterInformation_()

◆ paramToParameterInformation_()

◆ parseCommandLine_()

◆ parseRange_() [1/2]

◆ parseRange_() [2/2]

◆ printUsage_()

◆ registerDoubleList_()

◆ registerDoubleOption_()

◆ registerFlag_()

◆ registerFullParam_()

◆ registerInputFile_()

◆ registerInputFileList_()

◆ registerIntList_()

◆ registerIntOption_()

◆ registerOptionsAndFlags_()

◆ registerOutputFile_()

◆ registerOutputFileList_()

◆ registerParamSubsectionsAsTOPPSubsections_()

◆ registerStringList_()