OpenMS
TOPPBase.h
Go to the documentation of this file.
1 // Copyright (c) 2002-2023, The OpenMS Team -- EKU Tuebingen, ETH Zurich, and FU Berlin
2 // SPDX-License-Identifier: BSD-3-Clause
3 //
4 // --------------------------------------------------------------------------
5 // $Maintainer: Timo Sachsenberg $
6 // $Authors: Marc Sturm, Clemens Groepl $
7 // --------------------------------------------------------------------------
8 
9 #pragma once
10 
15 
18 
20 
22 
23 #include <fstream>
24 
25 #include <QString>
26 
27 class QStringList;
28 
29 namespace OpenMS
30 {
31  class FeatureMap;
32  class ConsensusMap;
33  struct ParameterInformation;
34 
47  struct Citation
48  {
49  std::string authors;
50  std::string title;
51  std::string when_where;
52  std::string doi;
53 
55  std::string toString() const
56  {
57  return authors + ". " + title + ". " + when_where + ". doi:" + doi + ".";
58  }
59  };
60 
61  namespace Exception
62  {
64  class OPENMS_DLLAPI UnregisteredParameter :
66  {
67 public:
68  UnregisteredParameter(const char* file, int line, const char* function, const String& parameter) :
69  BaseException(file, line, function, "UnregisteredParameter", parameter)
70  {
72  }
73 
74  };
76  class OPENMS_DLLAPI WrongParameterType :
78  {
79 public:
80  WrongParameterType(const char* file, int line, const char* function, const String& parameter) :
81  BaseException(file, line, function, "WrongParameterType", parameter)
82  {
84  }
85 
86  };
88  class OPENMS_DLLAPI RequiredParameterNotGiven :
90  {
91 public:
92  RequiredParameterNotGiven(const char* file, int line, const char* function, const String& parameter) :
93  BaseException(file, line, function, "RequiredParameterNotGiven", parameter)
94  {
96  }
97 
98  };
99  }
100 
121  class OPENMS_DLLAPI TOPPBase
122  {
123 public:
124 
127  {
141  UNEXPECTED_RESULT
142  };
143 
144 
145 
147  TOPPBase() = delete;
148 
150  TOPPBase(const TOPPBase&) = delete;
151 
162  TOPPBase(const String& name, const String& description, bool official = true, const std::vector<Citation>& citations = {}, bool toolhandler_test = true);
163 
165  virtual ~TOPPBase();
166 
168  ExitCodes main(int argc, const char** argv);
169 
177  static void setMaxNumberOfThreads(int num_threads);
178 
187 
188 private:
191 
194 
197 
200 
203 
206 
209 
212 
215 
218 
220  mutable std::ofstream log_;
221 
230  void enableLogging_() const;
231 
233  std::vector<ParameterInformation> parameters_;
234 
244  virtual Param getSubsectionDefaults_(const String& section) const;
245 
254 
256  std::map<String, String> subsections_;
257 
259  std::map<String, String> subsections_TOPP_;
260 
261 
274  Param parseCommandLine_(const int argc, const char** argv, const String& misc = "misc", const String& unknown = "unknown");
275 
285  String getParamAsString_(const String& key, const String& default_value = "") const;
286 
292  Int getParamAsInt_(const String& key, Int default_value = 0) const;
293 
299  double getParamAsDouble_(const String& key, double default_value = 0) const;
300 
306  StringList getParamAsStringList_(const String& key, const StringList& default_value) const;
307 
313  IntList getParamAsIntList_(const String& key, const IntList& default_value) const;
314 
320  DoubleList getParamAsDoubleList_(const String& key, const DoubleList& default_value) const;
321 
331  bool getParamAsBool_(const String& key) const;
332 
344  const ParamValue& getParam_(const String& key) const;
345 
351  String getSubsection_(const String& name) const;
352 
355 
358 
362 
363 protected:
366 
369 
371  bool official_;
372 
374  std::vector<Citation> citations_;
375 
378 
386  const String& getIniLocation_() const
387  {
388  return ini_location_;
389  }
390 
392  const String& toolName_() const;
393 
414  virtual void registerOptionsAndFlags_() = 0;
415 
418 
420  std::vector<ParameterInformation> paramToParameterInformation_(const Param& param) const;
421 
431  ParameterInformation paramEntryToParameterInformation_(const Param::ParamEntry& entry, const String& argument = "", const String& full_name = "") const;
432 
434 
436  void registerFullParam_(const Param& param);
437 
448  void registerStringOption_(const String& name, const String& argument, const String& default_value, const String& description, bool required = true, bool advanced = false);
449 
456  void setValidStrings_(const String& name, const std::vector<String>& strings);
457 
467  void setValidStrings_(const String& name, const std::string vstrings[], int count);
468 
486  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());
487 
501  void registerOutputFile_(const String& name, const String& argument, const String& default_value, const String& description, bool required = true, bool advanced = false);
502 
523  void registerOutputPrefix_(const String& name, const String& argument, const String& default_value, const String& description, bool required = true, bool advanced = false);
524 
537  void setValidFormats_(const String& name, const std::vector<String>& formats, const bool force_OpenMS_format = true);
538 
539 
550  void registerDoubleOption_(const String& name, const String& argument, double default_value, const String& description, bool required = true, bool advanced = false);
551 
557  void setMinInt_(const String& name, Int min);
563  void setMaxInt_(const String& name, Int max);
569  void setMinFloat_(const String& name, double min);
575  void setMaxFloat_(const String& name, double max);
576 
587  void registerIntOption_(const String& name, const String& argument,
588  Int default_value, const String& description,
589  bool required = true, bool advanced = false);
590 
602  void registerIntList_(const String& name, const String& argument, const IntList& default_value, const String& description, bool required = true, bool advanced = false);
603 
614  void registerDoubleList_(const String& name, const String& argument, const DoubleList& default_value, const String& description, bool required = true, bool advanced = false);
615 
626  void registerStringList_(const String& name, const String& argument, const StringList& default_value, const String& description, bool required = true, bool advanced = false);
627 
644  void registerInputFileList_(const String& name, const String& argument, const StringList& default_value, const String& description, bool required = true, bool advanced = false, const StringList& tags = StringList());
645 
659  void registerOutputFileList_(const String& name, const String& argument, const StringList& default_value, const String& description, bool required = true, bool advanced = false);
660 
662  void registerFlag_(const String& name, const String& description, bool advanced = false);
663 
671  void registerSubsection_(const String& name, const String& description);
672 
682  void registerTOPPSubsection_(const String& name, const String& description);
683 
684 
687 
688 
697  String getStringOption_(const String& name) const;
698 
707  double getDoubleOption_(const String& name) const;
708 
717  Int getIntOption_(const String& name) const;
718 
727  StringList getStringList_(const String& name) const;
728 
737  IntList getIntList_(const String& name) const;
738 
747  DoubleList getDoubleList_(const String& name) const;
748 
750  bool getFlag_(const String& name) const;
751 
757  const ParameterInformation& findEntry_(const String& name) const;
758 
764  Param const& getParam_() const;
765 
779  void checkParam_(const Param& param, const String& filename, const String& location) const;
780 
791  void fileParamValidityCheck_(const StringList& param_value, const String& param_name, const ParameterInformation& p) const;
792 
808  void fileParamValidityCheck_(String& param_value, const String& param_name, const ParameterInformation& p) const;
809 
817  void checkIfIniParametersAreApplicable_(const Param& ini_params);
819 
821  void printUsage_();
822 
824  virtual ExitCodes main_(int argc, const char** argv) = 0;
825 
827 
828  void writeLogInfo_(const String& text) const;
830 
832  void writeLogWarn_(const String& text) const;
833 
835  void writeLogError_(const String& text) const;
836 
838  void writeDebug_(const String& text, UInt min_level) const;
839 
841  void writeDebug_(const String& text, const Param& param, UInt min_level) const;
843 
845 
846  ExitCodes runExternalProcess_(const QString& executable, const QStringList& arguments, const QString& workdir = "") const;
848 
851  ExitCodes runExternalProcess_(const QString& executable, const QStringList& arguments, String& proc_stdout, String& proc_stderr, const QString& workdir = "") const;
853 
880  void inputFileReadable_(const String& filename, const String& param_name) const;
881 
892  void outputFileWritable_(const String& filename, const String& param_name) const;
894 
902  bool parseRange_(const String& text, double& low, double& high) const;
903 
911  bool parseRange_(const String& text, Int& low, Int& high) const;
912 
915 
917 
918 
920  void addDataProcessing_(ConsensusMap& map, const DataProcessing& dp) const;
921 
923  void addDataProcessing_(FeatureMap& map, const DataProcessing& dp) const;
924 
926  void addDataProcessing_(PeakMap& map, const DataProcessing& dp) const;
927 
930 
932  DataProcessing getProcessingInfo_(const std::set<DataProcessing::ProcessingAction>& actions) const;
933 
935 
937  bool writeCTD_();
938 
951 
954 
956  static const Citation cite_openms_;
957 
960 private:
961 
967  void addText_(const String& text);
968 
977 
978  };
979 
980 } // namespace OpenMS
981 
const char * tool_name
Definition: FLASHDeconvWizard.cpp:53
A container for consensus elements.
Definition: ConsensusMap.h:66
Description of the applied preprocessing steps.
Definition: DataProcessing.h:27
ProcessingAction
Definition: DataProcessing.h:33
Exception base class.
Definition: Exception.h:65
static GlobalExceptionHandler & getInstance()
The accessor for the singleton. It also serves as a replacement for the constructor.
Definition: GlobalExceptionHandler.h:62
static void setMessage(const std::string &message)
A required parameter was not given.
Definition: TOPPBase.h:90
RequiredParameterNotGiven(const char *file, int line, const char *function, const String &parameter)
Definition: TOPPBase.h:92
An unregistered parameter was accessed.
Definition: TOPPBase.h:66
UnregisteredParameter(const char *file, int line, const char *function, const String &parameter)
Definition: TOPPBase.h:68
A parameter was accessed with the wrong type.
Definition: TOPPBase.h:78
WrongParameterType(const char *file, int line, const char *function, const String &parameter)
Definition: TOPPBase.h:80
A container for features.
Definition: FeatureMap.h:80
In-Memory representation of a mass spectrometry run.
Definition: MSExperiment.h:46
Class to hold strings, numeric values, vectors of strings and vectors of numeric values using the stl...
Definition: ParamValue.h:29
Management and storage of parameters / INI files.
Definition: Param.h:44
LogType
Possible log types.
Definition: ProgressLogger.h:43
A more convenient string class.
Definition: String.h:34
Base class for TOPP applications.
Definition: TOPPBase.h:122
Param param_inifile_
All parameters specified in the ini file.
Definition: TOPPBase.h:205
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.
String const ini_location_
Location in the ini file where to look for parameters.
Definition: TOPPBase.h:199
const ParamValue & getParam_(const String &key) const
Return the value key of parameters as DataValue. ParamValue::EMPTY indicates that a parameter was not...
TOPPBase(const String &name, const String &description, bool official=true, const std::vector< Citation > &citations={}, bool toolhandler_test=true)
Constructor.
void inputFileReadable_(const String &filename, const String &param_name) const
Checks if an input file exists, is readable and is not empty.
void registerInputFileList_(const String &name, const String &argument, const StringList &default_value, const String &description, bool required=true, bool advanced=false, const StringList &tags=StringList())
Registers a list of input files option.
String const tool_description_
Tool description. This is assigned once and for all in the constructor.
Definition: TOPPBase.h:193
void registerOutputFileList_(const String &name, const String &argument, const StringList &default_value, const String &description, bool required=true, bool advanced=false)
Registers a list of output files option.
const String & getIniLocation_() const
Returns the location of the ini file where parameters are taken from. E.g. if the command line was TO...
Definition: TOPPBase.h:386
void addEmptyLine_()
Adds an empty line between registered variables in the documentation.
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.
virtual Param getSubsectionDefaults_(const String &section) const
This method should return the default parameters for subsections.
std::ofstream log_
Log file stream. Use the writeLog_() and writeDebug_() methods to access it.
Definition: TOPPBase.h:220
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.
Param const & getParam_() const
Return all parameters relevant to this TOPP tool.
void enableLogging_() const
Ensures that at least some default logging destination is opened for writing in append mode.
bool toolhandler_test_
Enable the ToolHandler tests.
Definition: TOPPBase.h:377
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.
Param param_
All parameters relevant to this invocation of the program.
Definition: TOPPBase.h:202
bool getFlag_(const String &name) const
Returns the value of a previously registered flag.
void writeDebug_(const String &text, UInt min_level) const
Writes a string to the log file and to OPENMS_LOG_DEBUG if the debug level is at least min_level.
std::vector< ParameterInformation > paramToParameterInformation_(const Param &param) const
Translates the given parameter object into a vector of ParameterInformation, that can be utilized for...
void registerStringList_(const String &name, const String &argument, const StringList &default_value, const String &description, bool required=true, bool advanced=false)
Registers a list of strings option.
ExitCodes runExternalProcess_(const QString &executable, const QStringList &arguments, String &proc_stdout, String &proc_stderr, const QString &workdir="") const
static String topp_ini_file_
.TOPP.ini file for storing system default parameters
Definition: TOPPBase.h:953
std::vector< ParameterInformation > parameters_
Storage location for parameter information.
Definition: TOPPBase.h:233
Param parseCommandLine_(const int argc, const char **argv, const String &misc="misc", const String &unknown="unknown")
Parses command line arguments using parameter definitions from TOPPBase.
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.
String getParamArgument_(const Param::ParamEntry &entry) const
Utility function that determines a suitable argument value for the given Param::ParamEntry.
virtual ~TOPPBase()
Destructor.
static const Citation cite_openms_
The OpenMS citation.
Definition: TOPPBase.h:956
void registerTOPPSubsection_(const String &name, const String &description)
Registers an allowed subsection in the INI file originating from the TOPP tool itself.
void printUsage_()
Prints the tool-specific command line options and appends the common options.
void registerIntList_(const String &name, const String &argument, const IntList &default_value, const String &description, bool required=true, bool advanced=false)
Registers a list of integers option.
String version_
Version string (if empty, the OpenMS/TOPP version is printed)
Definition: TOPPBase.h:365
void addDataProcessing_(FeatureMap &map, const DataProcessing &dp) const
Data processing setter for feature maps.
Param param_instance_
Parameters from instance section.
Definition: TOPPBase.h:211
Int const instance_number_
Instance number.
Definition: TOPPBase.h:196
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 setMinInt_(const String &name, Int min)
Sets the minimum value for the integer parameter(can be a list of integers,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 setValidStrings_(const String &name, const std::string vstrings[], int count)
Sets the valid strings for a string option or a whole string list.
std::vector< Citation > citations_
Papers, specific for this tool (will be shown in '–help')
Definition: TOPPBase.h:374
DataProcessing getProcessingInfo_(const std::set< DataProcessing::ProcessingAction > &actions) const
Returns the data processing information.
ProgressLogger::LogType log_type_
Type of progress logging.
Definition: TOPPBase.h:914
void registerFlag_(const String &name, const String &description, bool advanced=false)
Registers a flag.
void setMaxInt_(const String &name, Int max)
Sets the maximum value for the integer parameter(can be a list of integers,too) name.
StringList getStringList_(const String &name) const
Returns the value of a previously registered StringList.
void addText_(const String &text)
String verboseVersion_
Version string including additional revision/date time information. Note: This differs from version_ ...
Definition: TOPPBase.h:368
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.
void writeLogWarn_(const String &text) const
Writes a string to the log file and to OPENMS_LOG_WARN.
bool test_mode_
Test mode.
Definition: TOPPBase.h:950
ExitCodes main(int argc, const char **argv)
Main routine of all TOPP applications.
String const tool_name_
Tool name. This is assigned once and for all in the constructor.
Definition: TOPPBase.h:190
void addDataProcessing_(PeakMap &map, const DataProcessing &dp) const
Data processing setter for peak maps.
TOPPBase()=delete
No default constructor.
String getStringOption_(const String &name) const
Returns the value of a previously registered string option.
void writeDebug_(const String &text, const Param &param, UInt min_level) const
Writes a String followed by a Param to the log file and to OPENMS_LOG_DEBUG if the debug level is at ...
void setValidStrings_(const String &name, const std::vector< String > &strings)
Sets the valid strings for a string option or a whole string list.
std::map< String, String > subsections_TOPP_
Storage location and description for allowed subsections from TOPP tool's command-line parameters.
Definition: TOPPBase.h:259
void outputFileWritable_(const String &filename, const String &param_name) const
Checks if an output file is writable.
virtual void registerOptionsAndFlags_()=0
Sets the valid command line options (with argument) and flags (without argument).
DataProcessing getProcessingInfo_(DataProcessing::ProcessingAction action) const
Returns the data processing information.
Param param_common_tool_
Parameters from common section with tool name.
Definition: TOPPBase.h:214
IntList getIntList_(const String &name) const
Returns the value of a previously registered IntList.
Int debug_level_
Debug level set by -debug.
Definition: TOPPBase.h:959
TOPPBase(const TOPPBase &)=delete
No default copy constructor.
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.
bool official_
Flag indicating if this an official TOPP tool.
Definition: TOPPBase.h:371
Param getDefaultParameters_() const
Returns the default parameters.
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 registerDoubleOption_(const String &name, const String &argument, double default_value, const String &description, bool required=true, bool advanced=false)
Registers a double option.
Param param_cmdline_
Parameters from command line.
Definition: TOPPBase.h:208
String getDocumentationURL() const
Returns a link to the documentation of the tool (accessible on our servers and only after inclusion i...
void registerDoubleList_(const String &name, const String &argument, const DoubleList &default_value, const String &description, bool required=true, bool advanced=false)
Registers a list of doubles option.
void setMaxFloat_(const String &name, double max)
Sets the maximum value for the floating point parameter(can be a list of floating points,...
bool writeCTD_()
Write common tool description (CTD) file.
void setMinFloat_(const String &name, double min)
Sets the minimum value for the floating point parameter(can be a list of floating points,...
static void setMaxNumberOfThreads(int num_threads)
Sets the maximal number of usable threads.
void registerParamSubsectionsAsTOPPSubsections_(const Param &param)
String getToolPrefix() const
Returns the prefix used to identify the tool.
ExitCodes
Exit codes.
Definition: TOPPBase.h:127
@ INPUT_FILE_EMPTY
Definition: TOPPBase.h:132
@ INPUT_FILE_CORRUPT
Definition: TOPPBase.h:131
@ ILLEGAL_PARAMETERS
Definition: TOPPBase.h:134
@ MISSING_PARAMETERS
Definition: TOPPBase.h:135
@ EXTERNAL_PROGRAM_ERROR
Definition: TOPPBase.h:137
@ INCOMPATIBLE_INPUT_DATA
Definition: TOPPBase.h:139
@ UNKNOWN_ERROR
Definition: TOPPBase.h:136
@ EXECUTION_OK
Definition: TOPPBase.h:128
@ INTERNAL_ERROR
Definition: TOPPBase.h:140
@ INPUT_FILE_NOT_FOUND
Definition: TOPPBase.h:129
@ INPUT_FILE_NOT_READABLE
Definition: TOPPBase.h:130
@ CANNOT_WRITE_OUTPUT_FILE
Definition: TOPPBase.h:133
@ PARSE_ERROR
Definition: TOPPBase.h:138
bool parseRange_(const String &text, Int &low, Int &high) const
Parses a range string ([a]:[b]) into two variables (integers)
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.
virtual ExitCodes main_(int argc, const char **argv)=0
The actual "main" method. main_() is invoked by main().
const ParameterInformation & findEntry_(const String &name) const
Finds the entry in the parameters_ array that has the name name.
std::map< String, String > subsections_
Storage location and description for allowed subsections.
Definition: TOPPBase.h:256
void fileParamValidityCheck_(String &param_value, const String &param_name, const ParameterInformation &p) const
checks if an input file exists (respecting the flags)
double getDoubleOption_(const String &name) const
Returns the value of a previously registered double option.
bool parseRange_(const String &text, double &low, double &high) const
Parses a range string ([a]:[b]) into two variables (doubles)
void checkIfIniParametersAreApplicable_(const Param &ini_params)
Checks if the parameters of the provided ini file are applicable to this tool.
String getSubsection_(const String &name) const
Get the part of a parameter name that makes up the subsection.
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 addDataProcessing_(ConsensusMap &map, const DataProcessing &dp) const
Data processing setter for consensus maps.
Param getSubsectionDefaults_() const
Returns a single Param object containing all subsection parameters.
const String & toolName_() const
Returns the tool name.
void registerOutputPrefix_(const String &name, const String &argument, const String &default_value, const String &description, bool required=true, bool advanced=false)
Registers an output file prefix used for tools with multiple file output.
void writeLogError_(const String &text) const
Writes a string to the log file and to OPENMS_LOG_ERROR.
void registerSubsection_(const String &name, const String &description)
Registers an allowed subsection in the INI file (usually from OpenMS algorithms).
ParameterInformation paramEntryToParameterInformation_(const Param::ParamEntry &entry, const String &argument="", const String &full_name="") const
Transforms a ParamEntry object to command line parameter (ParameterInformation).
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.
void registerFullParam_(const Param &param)
Register command line parameters for all entries in a Param object.
void fileParamValidityCheck_(const StringList &param_value, const String &param_name, const ParameterInformation &p) const
checks if files of an input file list exist
ParameterInformation & getParameterByName_(const String &name)
Returns the parameter identified by the given name.
Param param_common_
Parameters from common section without tool name.
Definition: TOPPBase.h:217
Int getIntOption_(const String &name) const
Returns the value of a previously registered integer option.
bool getParamAsBool_(const String &key) const
Return the value of flag parameter key as bool.
DoubleList getDoubleList_(const String &name) const
Returns the value of a previously registered DoubleList.
int Int
Signed integer type.
Definition: Types.h:76
unsigned int UInt
Unsigned integer type.
Definition: Types.h:68
std::vector< Int > IntList
Vector of signed integers.
Definition: ListUtils.h:29
std::vector< String > StringList
Vector of String.
Definition: ListUtils.h:44
std::vector< double > DoubleList
Vector of double precision real types.
Definition: ListUtils.h:36
Main OpenMS namespace.
Definition: FeatureDeconvolution.h:22
Stores Citations for individual TOPP tools.
Definition: TOPPBase.h:48
std::string toString() const
mangle members to string
Definition: TOPPBase.h:55
std::string when_where
suggested format: journal. year; volume, issue: pages
Definition: TOPPBase.h:51
std::string authors
list of authors in AMA style, i.e. "surname initials", ...
Definition: TOPPBase.h:49
std::string title
title of article
Definition: TOPPBase.h:50
std::string doi
plain DOI (no urls), e.g. 10.1021/pr100177k
Definition: TOPPBase.h:52
Parameter entry used to store the actual information inside of a Param entry.
Definition: Param.h:49
Struct that captures all information of a command line parameter.
Definition: ParameterInformation.h:22