Home  · Classes  · Annotated Classes  · Modules  · Members  · Namespaces  · Related Pages

TOPPBase Class Reference

#include <OpenMS/APPLICATIONS/TOPPBase.h>

List of all members.


Detailed Description

Base class for TOPP applications.

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 ParameterInformationfindEntry_ (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 &param, 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 &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 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 &section) 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< ParameterInformationparameters_
 Storage location for parameter information.
std::map< String, Stringsubsections_
 Storage location and description for allowed subsections.

Classes

struct  ParameterInformation
 Stuct that captures all information of a parameter. More...

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 


Constructor & Destructor Documentation

TOPPBase ( const String tool_name,
const String tool_description 
)

Construtor.

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

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.

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

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.

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.

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.

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.

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.

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

DataValue const& 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:

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

where "some_key" == key in the examples.

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.

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)

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.

Note:
If the parameter is no string parameter or unset, an ElementNotFound exception is thrown.

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.

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)

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.

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)

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.

Note:
If the parameter is no file parameter or unset, an ElementNotFound 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.

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)

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.

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)

void registerFlag_ ( const String name,
const String description 
) [protected]

Registers a flag.

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

Registers an allowed subsection in the INI file.

Use this method to register subsections that are passed to algorithms

See also:
checkParam_

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

Parameters:
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]

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

void writeLog_ ( const String text  )  const [protected]

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

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


Member Data Documentation

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_ [private]

All parameters relevant to this invocation of the program.

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.


The documentation for this class was generated from the following file:
Generated Tue Apr 1 15:36:42 2008 -- using doxygen 1.5.4 OpenMS / TOPP 1.1