#include <OpenMS/APPLICATIONS/TOPPBase.h>
This base class implements functionality used in most TOPP tools:
If you want to create a new TOPP tool, please take care of the following:
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 } |
Exit codes. More... | |
Public Member Functions | |
TOPPBase (const String &tool_name, const String &tool_description) | |
Construtor. | |
virtual | ~TOPPBase () |
Destructor. | |
ExitCodes | main (int argc, const char **argv) |
Main routine of all TOPP applications. | |
Protected Member Functions | |
String const & | 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. | |
void | printUsage_ () const |
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. | |
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_ and getFlag_. The values of the certain options can be restricted using: setMinInt_, setMaxInt_, setMinFloat_, setMaxFloat_, setValidStrings_ and setValidFormats_.
In order to format the help output the methods addEmptyLine_ and addText_ can be used. | |
virtual void | registerOptionsAndFlags_ ()=0 |
Sets the valid command line options (with argument) and flags (without argument). | |
void | registerStringOption_ (const String &name, const String &argument, const String &default_value, const String &description, bool required=true) |
Registers a string option. | |
void | setValidStrings_ (const String &name, const std::vector< String > &strings) throw (Exception::ElementNotFound<String>,Exception::InvalidParameter) |
Sets the valid strings for a string option. | |
void | registerInputFile_ (const String &name, const String &argument, const String &default_value, const String &description, bool required=true) |
Registers an input file option. | |
void | registerOutputFile_ (const String &name, const String &argument, const String &default_value, const String &description, bool required=true) |
Registers an output file option. | |
void | setValidFormats_ (const String &name, const std::vector< String > &formats) throw (Exception::ElementNotFound<String>,Exception::InvalidParameter) |
Sets the formats for a input/output file option. | |
void | registerDoubleOption_ (const String &name, const String &argument, double default_value, const String &description, bool required=true) |
Registers a double option. | |
void | setMinInt_ (const String &name, Int min) throw (Exception::ElementNotFound<String>) |
Sets the minimum value for the integer parameter name . | |
void | setMaxInt_ (const String &name, Int max) throw (Exception::ElementNotFound<String>) |
Sets the maximum value for the integer parameter name . | |
void | setMinFloat_ (const String &name, DoubleReal min) throw (Exception::ElementNotFound<String>) |
Sets the minimum value for the floating point parameter name . | |
void | setMaxFloat_ (const String &name, DoubleReal max) throw (Exception::ElementNotFound<String>) |
Sets the maximum value for the floating point parameter name . | |
void | registerIntOption_ (const String &name, const String &argument, Int default_value, const String &description, bool required=true) |
Registers an integer option. | |
void | registerFlag_ (const String &name, const String &description) |
Registers a flag. | |
void | registerSubsection_ (const String &name, const String &description) |
Registers an allowed subsection in the INI file. | |
void | addEmptyLine_ () |
Adds an empty line between registered variables in the documentation. | |
void | addText_ (const String &text) |
Adds a left aligned text between registered variables in the documentation e.g. for subdividing the documentation. | |
String | getStringOption_ (const String &name) const throw ( Exception::UnregisteredParameter, Exception::RequiredParameterNotGiven, Exception::WrongParameterType, Exception::InvalidParameter, Exception::FileNotFound, Exception::FileNotReadable, Exception::FileEmpty, Exception::UnableToCreateFile) |
Returns the value of a previously registered string option. | |
double | getDoubleOption_ (const String &name) const throw ( Exception::UnregisteredParameter, Exception::RequiredParameterNotGiven, Exception::WrongParameterType, Exception::InvalidParameter ) |
Returns the value of a previously registered double option. | |
Int | getIntOption_ (const String &name) const throw ( Exception::UnregisteredParameter, Exception::RequiredParameterNotGiven, Exception::WrongParameterType, Exception::InvalidParameter ) |
Returns the value of a previously registered integer option. | |
bool | getFlag_ (const String &name) const throw ( Exception::UnregisteredParameter, Exception::WrongParameterType ) |
Returns the value of a previously registered flag. | |
bool | setByUser_ (const String &name) const throw ( Exception::UnregisteredParameter ) |
Returns if an option was set by the user (needed to distinguish between user-set and default value). | |
const ParameterInformation & | findEntry_ (const String &name) const throw ( Exception::UnregisteredParameter ) |
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 ¶m, const String &filename, const String &location) const |
Checks top-level entries of param according to the the information during registration. | |
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 ¶m, 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 throw ( Exception::FileNotFound, Exception::FileNotReadable, Exception::FileEmpty ) |
Checks if an input file exists, is readable and is not empty. | |
void | outputFileWritable_ (const String &filename) const throw ( Exception::UnableToCreateFile ) |
Checks if an output file is writable. | |
Protected Attributes | |
ProgressLogger::LogType | log_type_ |
Type of progress logging. | |
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 §ion) const |
This method should return the default parameters for subsections. | |
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. | |
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. | |
bool | getParamAsBool_ (const String &key, bool default_value=false) const |
Return the value of parameter key as a bool or default_value if this value is not set. | |
DataValue const & | getParam_ (const String &key) const |
Return the value key of parameters as DataValue. DataValue::EMPTY indicates that a parameter was not found. | |
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. | |
Int const | instance_number_ |
Instance number. | |
String const | ini_location_ |
Location in the ini file where to look for parameters. | |
Int | debug_level_ |
Debug level. | |
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. | |
Classes | |
struct | ParameterInformation |
Stuct that captures all information of a parameter. More... |
enum ExitCodes |
virtual ~TOPPBase | ( | ) | [virtual] |
Destructor.
TOPPBase | ( | ) | [private] |
No default constructor. It is "declared away".
ExitCodes main | ( | int | argc, | |
const char ** | argv | |||
) |
Main routine of all TOPP applications.
void enableLogging_ | ( | ) | const [private] |
Ensures that at least some default logging destination is opened for writing in append mode.
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.
Return the value of parameter key
as a string or default_value
if this value is not set.
Return the value of parameter key
as an integer or default_value
if this value is not set.
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.
bool getParamAsBool_ | ( | const String & | key, | |
bool | default_value = false | |||
) | const [private] |
Return the value of parameter key
as a bool or default_value
if this value is not set.
If the DataValue is a string, the values 'off', 'on', 'true' and 'false' are interpreted. If the DataValue is a numerical value, the values '0' and '1' interpreted. For all other values and when the value of key key
is not set, the default_value
is returned.
Return the value key
of parameters as DataValue. DataValue::EMPTY indicates that a parameter was not found.
Parameters are searched in this order:
where "some_key" == key in the examples.
String const& 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.
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.
void registerStringOption_ | ( | const String & | name, | |
const String & | argument, | |||
const String & | default_value, | |||
const String & | description, | |||
bool | required = true | |||
) | [protected] |
Registers a string option.
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) |
void setValidStrings_ | ( | const String & | name, | |
const std::vector< String > & | strings | |||
) | throw (Exception::ElementNotFound<String>,Exception::InvalidParameter) [protected] |
Sets the valid strings for a string option.
The strings must not contain comma characters. Otherwise an InvalidParameter exception is thrown.
void registerInputFile_ | ( | const String & | name, | |
const String & | argument, | |||
const String & | default_value, | |||
const String & | description, | |||
bool | required = true | |||
) | [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.
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) |
void registerOutputFile_ | ( | const String & | name, | |
const String & | argument, | |||
const String & | default_value, | |||
const String & | description, | |||
bool | required = true | |||
) | [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.
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) |
void setValidFormats_ | ( | const String & | name, | |
const std::vector< String > & | formats | |||
) | throw (Exception::ElementNotFound<String>,Exception::InvalidParameter) [protected] |
Sets the formats for a input/output file option.
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.
Valid file type strings are definded by the Type enum of FileHandler. Writeing the format names in uppercase and lowercase does not matter. If an invalid firmat name is used, an InvalidParameter exception is thrown.
void registerDoubleOption_ | ( | const String & | name, | |
const String & | argument, | |||
double | default_value, | |||
const String & | description, | |||
bool | required = true | |||
) | [protected] |
Registers a double option.
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) |
void setMinInt_ | ( | const String & | name, | |
Int | min | |||
) | throw (Exception::ElementNotFound<String>) [protected] |
Sets the minimum value for the integer parameter name
.
Throws an exception if key
is not found or if the parameter type is wrong.
void setMaxInt_ | ( | const String & | name, | |
Int | max | |||
) | throw (Exception::ElementNotFound<String>) [protected] |
Sets the maximum value for the integer parameter name
.
Throws an exception if key
is not found or if the parameter type is wrong.
void setMinFloat_ | ( | const String & | name, | |
DoubleReal | min | |||
) | throw (Exception::ElementNotFound<String>) [protected] |
Sets the minimum value for the floating point parameter name
.
Throws an exception if key
is not found or if the parameter type is wrong.
void setMaxFloat_ | ( | const String & | name, | |
DoubleReal | max | |||
) | throw (Exception::ElementNotFound<String>) [protected] |
Sets the maximum value for the floating point parameter name
.
Throws an exception if key
is not found or if the parameter type is wrong.
void registerIntOption_ | ( | const String & | name, | |
const String & | argument, | |||
Int | default_value, | |||
const String & | description, | |||
bool | required = true | |||
) | [protected] |
Registers an integer option.
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) |
Registers a flag.
Registers an allowed subsection in the INI file.
Use this method to register subsections that are passed to algorithms
void addEmptyLine_ | ( | ) | [protected] |
Adds an empty line between registered variables in the documentation.
void addText_ | ( | const String & | text | ) | [protected] |
Adds a left aligned text between registered variables in the documentation e.g. for subdividing the documentation.
String getStringOption_ | ( | const String & | name | ) | const throw ( Exception::UnregisteredParameter, Exception::RequiredParameterNotGiven, Exception::WrongParameterType, Exception::InvalidParameter, Exception::FileNotFound, Exception::FileNotReadable, Exception::FileEmpty, Exception::UnableToCreateFile) [protected] |
Returns the value of a previously registered string option.
double getDoubleOption_ | ( | const String & | name | ) | const throw ( Exception::UnregisteredParameter, Exception::RequiredParameterNotGiven, Exception::WrongParameterType, Exception::InvalidParameter ) [protected] |
Returns the value of a previously registered double option.
If you want to find out if a value was really set or is a default value, use the setByUser_(String) method.
Int getIntOption_ | ( | const String & | name | ) | const throw ( Exception::UnregisteredParameter, Exception::RequiredParameterNotGiven, Exception::WrongParameterType, Exception::InvalidParameter ) [protected] |
Returns the value of a previously registered integer option.
If you want to find out if a value was really set or is a default value, use the setByUser_(String) method.
bool getFlag_ | ( | const String & | name | ) | const throw ( Exception::UnregisteredParameter, Exception::WrongParameterType ) [protected] |
Returns the value of a previously registered flag.
bool setByUser_ | ( | const String & | name | ) | const throw ( Exception::UnregisteredParameter ) [protected] |
Returns if an option was set by the user (needed to distinguish between user-set and default value).
const ParameterInformation& findEntry_ | ( | const String & | name | ) | const throw ( Exception::UnregisteredParameter ) [protected] |
Finds the entry in the parameters_ array that has the name name
.
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.
void checkParam_ | ( | const Param & | param, | |
const String & | filename, | |||
const String & | location | |||
) | const [protected] |
Checks top-level entries of param
according to the the information during registration.
Only top-lvel 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
param | Parameters to check | |
filename | The source file name | |
location | Exact location inside the source file |
void printUsage_ | ( | ) | const [protected] |
Prints the tool-specific command line options and appends the common options.
virtual ExitCodes main_ | ( | int | argc, | |
const char ** | argv | |||
) | [protected, pure virtual] |
void writeLog_ | ( | const String & | text | ) | const [protected] |
Writes a string to the log file and to std::cout.
Writes a text
to the log file and to std::cout if the debug level is at least min_level
.
void inputFileReadable_ | ( | const String & | filename | ) | const throw ( Exception::FileNotFound, Exception::FileNotReadable, Exception::FileEmpty ) [protected] |
Checks if an input file exists, is readable and is not empty.
void outputFileWritable_ | ( | const String & | filename | ) | const throw ( Exception::UnableToCreateFile ) [protected] |
Checks if an output file is writable.
void parseRange_ | ( | const String & | text, | |
double & | low, | |||
double & | high | |||
) | const [protected] |
Helper function that parses a range string ([a]:[b]) into two variables.
String const tool_name_ [private] |
Tool name. This is assigned once and for all in the constructor.
String const tool_description_ [private] |
Tool description. This is assigned once and for all in the constructor.
Int const instance_number_ [private] |
Instance number.
String const ini_location_ [private] |
Location in the ini file where to look for parameters.
Int debug_level_ [private] |
Debug level.
Param param_inifile_ [private] |
All parameters specified in the ini file.
Param param_cmdline_ [private] |
Parameters from command line.
Param param_instance_ [private] |
Parameters from instance section.
Param param_common_tool_ [private] |
Parameters from common section with tool name.
Param param_common_ [private] |
Parameters from common section without tool name.
std::ofstream log_ [mutable, private] |
Log file stream. Use the writeLog_() and writeDebug_() methods to access it.
std::vector<ParameterInformation> parameters_ [private] |
Storage location for parameter information.
std::map<String, String> subsections_ [private] |
Storage location and description for allowed subsections.
ProgressLogger::LogType log_type_ [protected] |
Type of progress logging.
Generated Tue Apr 1 15:36:42 2008 -- using doxygen 1.5.4 | OpenMS / TOPP 1.1 |