Base class for TOPP applications. More...

#include <OpenMS/APPLICATIONS/TOPPBase.h>

Inheritance 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 (const String &name, const String &description, bool official=true, bool id_tag_support=false, bool require_args=true, const String &version="")
	Constructor.
virtual	~TOPPBase ()
	Destructor.
ExitCodes	main (int argc, const char **argv)
	Main routine of all TOPP applications.
Static Public Member Functions
static void	setMaxNumberOfThreads (int num_threads)
	Sets the maximal number of usable threads.
Protected Member Functions
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.
const String &	toolName_ () const
	Returns the tool name.
String	breakString_ (const String &input, const Size line_len, const Size indentation, const Size max_lines) const
	make a string console friendly
void	readConsoleSize_ ()
	read console settings for output shaping
void	printUsage_ ()
	Prints the tool-specific command line options and appends the common options.
virtual ExitCodes	main_ (int argc, const char **argv)=0
	The actual "main" method. main_() is invoked by main().
void	parseRange_ (const String &text, double &low, double &high) const
	Helper function that parses a range string ([a]:[b]) into two variables.
void	parseRange_ (const String &text, Int &low, Int &high) const
	Helper function that parses a range string ([a]:[b]) into two variables.
const DocumentIDTagger &	getDocumentIDTagger_ () const
	get DocumentIDTagger to assign DocumentIDs to maps
bool	writeCTD_ ()
	Write common tool description (CTD) file.
ExitCodes	writeWSDL_ (const String &filename)
	Write WSDL file and validate it. Returns EXECUTION_OK or INTERNAL_ERROR (if validation failed).
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).
void	registerParamEntry_ (const Param::ParamEntry &entry, const String &argument="", const String &full_name="")
	Registers a command line parameter derived from a ParamEntry object.
void	registerFullParam_ (const Param &param)
	Register command line parameters for all entries in a Param object.
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.
void	setValidStrings_ (const String &name, const std::vector< String > &strings)
	Sets the valid strings for a string option or a whole string list.
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.
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.
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.
void	registerDoubleOption_ (const String &name, const String &argument, double default_value, const String &description, bool required=true, bool advanced=false)
	Registers a double option.
void	setMinInt_ (const String &name, Int min)
	Sets the minimum value for the integer parameter(can be a list of integers,too) `name`.
void	setMaxInt_ (const String &name, Int max)
	Sets the maximum value for the integer parameter(can be a list of integers,too) `name`.
void	setMinFloat_ (const String &name, DoubleReal min)
	Sets the minimum value for the floating point parameter(can be a list of floating points,too) `name`.
void	setMaxFloat_ (const String &name, DoubleReal max)
	Sets the maximum value for the floating point parameter(can be a list of floating points,too) `name`.
void	registerIntOption_ (const String &name, const String &argument, Int default_value, const String &description, bool required=true, bool advanced=false)
	Registers an integer option.
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.
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.
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.
void	registerInputFileList_ (const String &name, const String &argument, StringList default_value, const String &description, bool required=true, bool advanced=false)
	Registers a list of input files option.
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.
void	registerFlag_ (const String &name, const String &description, bool advanced=false)
	Registers a flag.
void	registerSubsection_ (const String &name, const String &description)
	Registers an allowed subsection in the INI file (usually from OpenMS algorithms).
void	registerTOPPSubsection_ (const String &name, const String &description)
	Registers an allowed subsection in the INI file originating from the TOPP tool itself.
void	addEmptyLine_ ()
	Adds an empty line between registered variables in the documentation.
String	getStringOption_ (const String &name) const
	Returns the value of a previously registered string option.
DoubleReal	getDoubleOption_ (const String &name) const
	Returns the value of a previously registered double option.
Int	getIntOption_ (const String &name) const
	Returns the value of a previously registered integer option.
StringList	getStringList_ (const String &name) const
	Returns the value of a previously registered StringList.
IntList	getIntList_ (const String &name) const
	Returns the value of a previously registered IntList.
DoubleList	getDoubleList_ (const String &name) const
	Returns the value of a previously registered DoubleList.
bool	getFlag_ (const String &name) const
	Returns the value of a previously registered flag.
const ParameterInformation &	findEntry_ (const String &name) const
	Finds the entry in the parameters_ array that has the name `name`.
Param const &	getParam_ () const
	Return all parameters relevant to this TOPP tool.
void	checkParam_ (const Param &param, const String &filename, const String &location) const
	Checks top-level entries of `param` according to the information during registration.
void	checkIfIniParametersAreApplicable_ (const Param &ini_params)
	Checks if the parameters of the provided ini file are applicable to this tool.
Debug and Log output

void	writeLog_ (const String &text) const
	Writes a string to the log file and to std::cout.
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`.
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`.
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 catched in the main method of this class. They do not have to be handled in the tool itself!
void	inputFileReadable_ (const String &filename, const String &param_name) const
	Checks if an input file exists, is readable and is not empty.
void	outputFileWritable_ (const String &filename, const String &param_name) const
	Checks if an output file is writeable.
Data processing auxilary functions

void	addDataProcessing_ (ConsensusMap &map, const DataProcessing &dp) const
	Data processing setter for consensus maps.
template<typename FeatureType >
void	addDataProcessing_ (FeatureMap< FeatureType > &map, const DataProcessing &dp) const
	Data processing setter for feature maps.
template<typename PeakType , typename CT >
void	addDataProcessing_ (MSExperiment< PeakType, CT > &map, const DataProcessing &dp) const
	Data processing setter for peak maps.
DataProcessing	getProcessingInfo_ (DataProcessing::ProcessingAction action) const
	Returns the the data processing information.
DataProcessing	getProcessingInfo_ (const std::set< DataProcessing::ProcessingAction > &actions) const
	Returns the the data processing information.
Protected Attributes
String	version_
	Version string (if empty, the OpenMS/TOPP version is printed).
String	verboseVersion_
	Version string including additional revision/date time information. Note: This differs from version_ only if not provided by the user.
bool	official_
	Flag indicating if this an official TOPP tool.
ProgressLogger::LogType	log_type_
	Type of progress logging.
bool	test_mode_
	Test mode.
int	console_width_
	width of console we are currently in (if not determinable, set to 80 as default)
Int	debug_level_
	Debug level set by -debug.
Static Protected Attributes
static String	topp_ini_file_
	.TOPP.ini file for storing system default parameters
Private Member Functions
	TOPPBase ()
	No default constructor. It is "declared away".
	TOPPBase (const TOPPBase &)
	No default copy constructor. It is "declared away".
void	enableLogging_ () const
	Ensures that at least some default logging destination is opened for writing in append mode.
virtual Param	getSubsectionDefaults_ (const String &section) const
	This method should return the default parameters for subsections.
void	addText_ (const String &text)
Internal parameter handling

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.
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.
DoubleReal	getParamAsDouble_ (const String &key, DoubleReal default_value=0) const
	Return the value of parameter `key` as a double or `default_value` if this value is not set.
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.
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.
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.
bool	getParamAsBool_ (const String &key) const
	Return the value of flag parameter `key` as bool.
const DataValue &	getParam_ (const String &key) const
	Return the value `key` of parameters as DataValue. DataValue::EMPTY indicates that a parameter was not found.
String	getSubsection_ (const String &name) const
	Get the part of a parameter name that makes up the subsection.
Param	getDefaultParameters_ () const
	Returns the default parameters.
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.
Private Attributes
String const	tool_name_
	Tool name. This is assigned once and for all in the constructor.
String const	tool_description_
	Tool description. This is assigned once and for all in the constructor.
bool	id_tag_support_
	Tool indicates it supports assignment of unique DocumentID from IDPool.
bool	require_args_
	Require at least one command line argument, exit immediately otherwise. GUI tools should disable this to be callable by double clicking.
DocumentIDTagger	id_tagger_
	Instance of DocumentIDTagger, which can be accessed using getDocumentIDTagger_().
Int const	instance_number_
	Instance number.
String const	ini_location_
	Location in the ini file where to look for parameters.
Param	param_
	All parameters relevant to this invocation of the program.
Param	param_inifile_
	All parameters specified in the ini file.
Param	param_cmdline_
	Parameters from command line.
Param	param_instance_
	Parameters from instance section.
Param	param_common_tool_
	Parameters from common section with tool name.
Param	param_common_
	Parameters from common section without tool name.
std::ofstream	log_
	Log file stream. Use the writeLog_() and writeDebug_() methods to access it.
std::vector< ParameterInformation >	parameters_
	Storage location for parameter information.
std::map< String, String >	subsections_
	Storage location and description for allowed subsections.
std::map< String, String >	subsections_TOPP_
	Storage location and description for allowed subsections from TOPP tool's command-line parameters.

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

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	(	const String &	name,
		const String &	description,
		bool	official = `true`,
		bool	id_tag_support = `false`,
		bool	require_args = `true`,
		const String &	version = `""`
	)

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.
	id_tag_support	Does the TOPP tool support unique DocumentIdentifier assignment?! The default is false. In the default case you cannot use the -id_pool argument when calling the TOPP tool (it will terminate during init)
	version	Optional version of the tools (if empty, the version of OpenMS/TOPP is used).
	require_args	Require arguments on the command line (GUI tools should disable this)

virtual ~TOPPBase ( ) [virtual]

Destructor.

TOPPBase ( ) [private]

No default constructor. It is "declared away".

TOPPBase ( const TOPPBase & ) [private]

No default copy constructor. It is "declared away".

Member Function Documentation

void addDataProcessing_	(	ConsensusMap &	map,
		const DataProcessing &	dp
	)			const `[protected]`

Data processing setter for consensus maps.

void addDataProcessing_	(	FeatureMap< FeatureType > &	map,
		const DataProcessing &	dp
	)			const `[inline, protected]`

Data processing setter for feature maps.

References FeatureMap< FeatureT >::getDataProcessing().

void addDataProcessing_	(	MSExperiment< PeakType, CT > &	map,
		const DataProcessing &	dp
	)			const `[inline, protected]`

Data processing setter for peak maps.

References MSExperiment< PeakT, ChromatogramPeakT >::getChromatograms(), and MSExperiment< PeakT, ChromatogramPeakT >::setChromatograms().

void addEmptyLine_ ( ) [protected]

Adds an empty line between registered variables in the documentation.

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

String breakString_	(	const String &	input,
		const Size	line_len,
		const Size	indentation,
		const Size	max_lines
	)			const `[protected]`

make a string console friendly

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.

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

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

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

Param getDefaultParameters_ ( ) const [private]

Returns the default parameters.

const DocumentIDTagger& getDocumentIDTagger_ ( ) const [protected]

get DocumentIDTagger to assign DocumentIDs to maps

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

DoubleReal 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

bool getFlag_ ( const String & name ) const [protected]

Returns the value of a previously registered flag.

const String& getIniLocation_ ( ) const [inline, protected]

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.

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

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

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.

const DataValue& getParam_ ( const String & key ) const [private]

Return the value key of parameters as DataValue. DataValue::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.

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.

DoubleReal getParamAsDouble_	(	const String &	key,
		DoubleReal	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.

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.

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.

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.

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.

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.

DataProcessing getProcessingInfo_ ( DataProcessing::ProcessingAction action ) const [protected]

Returns the the data processing information.

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

Returns the the data processing information.

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

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

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.

virtual Param getSubsectionDefaults_ ( const String & section ) const [private, virtual]

This method should return the default parameters for subsections.

It is called once for each registered subsection, when writing the an 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 unexperienced users.

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.

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.

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

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

Main routine of all TOPP applications.

Referenced by main().

virtual ExitCodes main_	(	int	argc,
		const char **	argv
	)			`[protected, pure virtual]`

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

Implemented in TOPPRNPxl, and TOPPRNPxlXICFilter.

void outputFileWritable_	(	const String &	filename,
		const String &	param_name
	)			const `[protected]`

Checks if an output file is writeable.

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

void parseRange_	(	const String &	text,
		double &	low,
		double &	high
	)			const `[protected]`

Helper function that parses a range string ([a]:[b]) into two variables.

void parseRange_	(	const String &	text,
		Int &	low,
		Int &	high
	)			const `[protected]`

Helper function that parses a range string ([a]:[b]) into two variables.

void printUsage_ ( ) [protected]

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

void readConsoleSize_ ( ) [protected]

read console settings for output shaping

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.

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.

void registerFlag_	(	const String &	name,
		const String &	description,
		bool	advanced = `false`
	)			`[protected]`

Registers a flag.

void registerFullParam_ ( const Param & param ) [protected]

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

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.

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, e.g. 'skipexists', specifying the handling of the input file (e.g. when its an executable) Valid tags: 'skipexists' - will prevent checking if the given file really exists (useful for an executable in global PATH)

void registerInputFileList_	(	const String &	name,
		const String &	argument,
		StringList	default_value,
		const String &	description,
		bool	required = `true`,
		bool	advanced = `false`
	)			`[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.

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.

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.

virtual void registerOptionsAndFlags_ ( ) [protected, pure 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 TOPPRNPxl, and TOPPRNPxlXICFilter.

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.

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.

void registerParamEntry_	(	const Param::ParamEntry &	entry,
		const String &	argument = `""`,
		const String &	full_name = `""`
	)			`[protected]`

Registers a command line parameter derived from a ParamEntry object.

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)

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.

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.

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_

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_

void setMaxFloat_	(	const String &	name,
		DoubleReal	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

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

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.

void setMinFloat_	(	const String &	name,
		DoubleReal	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

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

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)

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

const String& toolName_ ( ) const [protected]

Returns the tool name.

bool writeCTD_ ( ) [protected]

Write common tool description (CTD) file.

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.

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.

void writeLog_ ( const String & text ) const [protected]

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

ExitCodes writeWSDL_ ( const String & filename ) [protected]

Write WSDL file and validate it. Returns EXECUTION_OK or INTERNAL_ERROR (if validation failed).

Member Data Documentation

int console_width_ [protected]

width of console we are currently in (if not determinable, set to 80 as default)

Int debug_level_ [protected]

Debug level set by -debug.

bool id_tag_support_ [private]

Tool indicates it supports assignment of unique DocumentID from IDPool.

DocumentIDTagger id_tagger_ [private]

Instance of DocumentIDTagger, which can be accessed using getDocumentIDTagger_().

String const ini_location_ [private]

Location in the ini file where to look for parameters.

Int const instance_number_ [private]

Instance number.

std::ofstream log_ [mutable, private]

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

ProgressLogger::LogType log_type_ [protected]

Type of progress logging.

bool official_ [protected]

Flag indicating if this an official TOPP tool.

Param param_ [private]

All parameters relevant to this invocation of the program.

Param param_cmdline_ [private]

Parameters from command line.

Param param_common_ [private]

Parameters from common section without tool name.

Param param_common_tool_ [private]

Parameters from common section with tool name.

Param param_inifile_ [private]

All parameters specified in the ini file.

Param param_instance_ [private]

Parameters from instance section.

std::vector<ParameterInformation> parameters_ [private]

Storage location for parameter information.

bool require_args_ [private]

Require at least one command line argument, exit immediately otherwise. GUI tools should disable this to be callable by double clicking.

std::map<String, String> subsections_ [private]

Storage location and description for allowed subsections.

std::map<String, String> subsections_TOPP_ [private]

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

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

String const tool_description_ [private]

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

String const tool_name_ [private]

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

String topp_ini_file_ [static, protected]

.TOPP.ini file for storing system default parameters

String verboseVersion_ [protected]

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

String version_ [protected]

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

OpenMS / TOPP release 1.10.0

Documentation generated on Thu Mar 7 2013 09:42:50 using doxygen 1.7.1

TOPPBase Class Reference

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Static Protected Attributes

Private Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation