OpenMS
Param.h
Go to the documentation of this file.
1 // --------------------------------------------------------------------------
2 // OpenMS -- Open-Source Mass Spectrometry
3 // --------------------------------------------------------------------------
4 // Copyright The OpenMS Team -- Eberhard Karls University Tuebingen,
5 // ETH Zurich, and Freie Universitaet Berlin 2002-2023.
6 //
7 // This software is released under a three-clause BSD license:
8 // * Redistributions of source code must retain the above copyright
9 // notice, this list of conditions and the following disclaimer.
10 // * Redistributions in binary form must reproduce the above copyright
11 // notice, this list of conditions and the following disclaimer in the
12 // documentation and/or other materials provided with the distribution.
13 // * Neither the name of any author or any participating institution
14 // may be used to endorse or promote products derived from this software
15 // without specific prior written permission.
16 // For a full list of authors, refer to the file AUTHORS.
17 // --------------------------------------------------------------------------
18 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
19 // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 // ARE DISCLAIMED. IN NO EVENT SHALL ANY OF THE AUTHORS OR THE CONTRIBUTING
22 // INSTITUTIONS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
23 // EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
24 // PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
25 // OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
26 // WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
27 // OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
28 // ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29 //
30 // --------------------------------------------------------------------------
31 // $Maintainer: Timo Sachsenberg $
32 // $Authors: Marc Sturm, Clemens Groepl $
33 // --------------------------------------------------------------------------
34 
35 #pragma once
36 
38 #include <OpenMS/OpenMSConfig.h>
39 
40 #include <set>
41 #include <string>
42 #include <map>
43 
44 namespace OpenMS
45 {
46 
47  namespace Logger
48  {
49  class LogStream;
50  }
51 
69  class OPENMS_DLLAPI Param
70  {
71 public:
72 
74  struct OPENMS_DLLAPI ParamEntry
75  {
79  ParamEntry(const std::string& n, const ParamValue& v, const std::string& d, const std::vector<std::string>& t = std::vector<std::string>());
81  ParamEntry(const ParamEntry&) = default;
83  ParamEntry(ParamEntry&&) = default;
86 
88  ParamEntry& operator=(const ParamEntry&) = default;
90  ParamEntry& operator=(ParamEntry&&) & = default;
91 
93  bool isValid(std::string& message) const;
95  bool operator==(const ParamEntry& rhs) const;
96 
98  std::string name;
100  std::string description;
104  std::set<std::string> tags;
106 
107  double min_float;
108  double max_float;
109  int min_int;
110  int max_int;
111  std::vector<std::string> valid_strings;
113  };
114 
116  struct OPENMS_DLLAPI ParamNode
117  {
119  typedef std::vector<ParamNode>::iterator NodeIterator;
121  typedef std::vector<ParamEntry>::iterator EntryIterator;
123  typedef std::vector<ParamNode>::const_iterator ConstNodeIterator;
125  typedef std::vector<ParamEntry>::const_iterator ConstEntryIterator;
126 
130  ParamNode(const std::string& n, const std::string& d);
132  ParamNode(const ParamNode&) = default;
134  ParamNode(ParamNode&&) = default;
137 
139  ParamNode& operator=(const ParamNode&) = default;
141  ParamNode& operator=(ParamNode&&) & = default;
142 
144  bool operator==(const ParamNode& rhs) const;
145 
151  EntryIterator findEntry(const std::string& name);
157  NodeIterator findNode(const std::string& name);
163  ParamNode* findParentOf(const std::string& name);
169  ParamEntry* findEntryRecursive(const std::string& name);
170 
172  void insert(const ParamNode& node, const std::string& prefix = "");
174  void insert(const ParamEntry& entry, const std::string& prefix = "");
176  size_t size() const;
178  std::string suffix(const std::string& key) const;
179 
181  std::string name;
183  std::string description;
185  std::vector<ParamEntry> entries;
187  std::vector<ParamNode> nodes;
188  };
189 
190 public:
191 
193  class OPENMS_DLLAPI ParamIterator
194  {
195 public:
197  struct OPENMS_DLLAPI TraceInfo
198  {
200  inline TraceInfo(const std::string& n, const std::string& d, bool o) :
201  name(n),
202  description(d),
203  opened(o)
204  {
205  }
206 
208  std::string name;
210  std::string description;
212  bool opened;
213  };
214 
230  bool operator==(const ParamIterator& rhs) const;
232  bool operator!=(const ParamIterator& rhs) const;
234  std::string getName() const;
236  const std::vector<TraceInfo>& getTrace() const;
237 
238 protected:
242  int current_;
244  std::vector<const Param::ParamNode*> stack_;
246  std::vector<TraceInfo> trace_;
247 
248  };
249 
251  Param();
252 
254  Param(const Param&) = default;
255 
257  Param(Param&&) = default;
258 
261 
263  Param& operator=(const Param&) = default;
264 
266  Param& operator=(Param&&) & = default;
267 
269  bool operator==(const Param& rhs) const;
270 
273 
276 
278 
279 
288  void setValue(const std::string& key, const ParamValue& value, const std::string& description = "", const std::vector<std::string>& tags = std::vector<std::string>());
289 
295  const ParamValue& getValue(const std::string& key) const;
296 
302  ParamValue::ValueType getValueType(const std::string& key) const;
303 
309  const ParamEntry& getEntry(const std::string& key) const;
310 
317  bool exists(const std::string& key) const;
318 
325  bool hasSection(const std::string& key) const;
326 
333  ParamIterator findFirst(const std::string& leaf) const;
334 
342  ParamIterator findNext(const std::string& leaf, const ParamIterator& start_leaf) const;
344 
346 
347 
356  void addTag(const std::string& key, const std::string& tag);
357 
364  void addTags(const std::string& key, const std::vector<std::string>& tags);
365 
374  bool hasTag(const std::string& key, const std::string& tag) const;
375 
381  std::vector<std::string> getTags(const std::string& key) const;
382 
388  void clearTags(const std::string& key);
390 
391 
393 
394 
400  const std::string& getDescription(const std::string& key) const;
401 
410  void setSectionDescription(const std::string& key, const std::string& description);
411 
417  const std::string& getSectionDescription(const std::string& key) const;
418 
424  void addSection(const std::string& key, const std::string& description);
426 
428 
429 
431  size_t size() const;
432 
434  bool empty() const;
435 
437  void clear();
438 
441  void insert(const std::string& prefix, const Param& param);
442 
452  void remove(const std::string& key);
453 
462  void removeAll(const std::string& prefix);
463 
471  Param copy(const std::string& prefix, bool remove_prefix = false) const;
472 
482  Param copySubset(const Param& subset) const;
483 
489  bool update(const Param& p_outdated, const bool add_unknown = false);
490 
496  bool update(const Param& p_outdated, const bool add_unknown, Logger::LogStream& stream);
497 
498 
519  bool update(const Param& p_outdated, bool verbose, bool add_unknown, bool fail_on_invalid_values, bool fail_on_unknown_parameters, Logger::LogStream& stream);
520 
526  void merge(const Param& toMerge);
527 
529 
530 
532 
533 
542  void setDefaults(const Param& defaults, const std::string& prefix = "", bool showMessage = false);
543 
563  void checkDefaults(const std::string& name, const Param& defaults, const std::string& prefix = "") const;
565 
567 
568 
576  void setValidStrings(const std::string& key, const std::vector<std::string>& strings);
577 
583  const std::vector<std::string>& getValidStrings(const std::string& key) const;
584 
592  void setMinInt(const std::string& key, int min);
593 
601  void setMaxInt(const std::string& key, int max);
602 
610  void setMinFloat(const std::string& key, double min);
611 
619  void setMaxFloat(const std::string& key, double max);
621 
623 
624 
642  void parseCommandLine(const int argc, const char** argv, const std::string& prefix = "");
643 
657  void parseCommandLine(const int argc, const char** argv, const std::map<std::string, std::string>& options_with_one_argument, const std::map<std::string, std::string>& options_without_argument, const std::map<std::string, std::string>& options_with_multiple_argument, const std::string& misc = "misc", const std::string& unknown = "unknown");
658 
660 
661 protected:
662 
668  ParamEntry& getEntry_(const std::string& key) const;
669 
671  Param(const Param::ParamNode& node);
672 
675  };
676 
678  OPENMS_DLLAPI std::ostream& operator<<(std::ostream& os, const Param& param);
679 
680 } // namespace OpenMS
681 
Log Stream Class.
Definition: LogStream.h:318
Class to hold strings, numeric values, vectors of strings and vectors of numeric values using the stl...
Definition: ParamValue.h:55
ValueType
Supported types for ParamValue.
Definition: ParamValue.h:64
Forward const iterator for the Param class.
Definition: Param.h:194
bool operator!=(const ParamIterator &rhs) const
Equality operator.
ParamIterator operator++(int)
Postfix increment operator.
const Param::ParamEntry & operator*()
Dereferencing.
const Param::ParamNode * root_
Pointer to the root node.
Definition: Param.h:240
ParamIterator(const Param::ParamNode &root)
Constructor for begin iterator.
std::vector< TraceInfo > trace_
Node traversal data during last ++ operation.
Definition: Param.h:246
std::string getName() const
Returns the absolute path of the current element (including all sections)
const std::vector< TraceInfo > & getTrace() const
Returns the traceback of the opened and closed sections.
const Param::ParamEntry * operator->()
Dereferencing.
int current_
Index of the current ParamEntry (-1 means invalid)
Definition: Param.h:242
ParamIterator & operator++()
Prefix increment operator.
std::vector< const Param::ParamNode * > stack_
Pointers to the ParamNodes we are in.
Definition: Param.h:244
ParamIterator()
Default constructor used to create a past-the-end iterator.
bool operator==(const ParamIterator &rhs) const
Equality operator.
Management and storage of parameters / INI files.
Definition: Param.h:70
bool hasTag(const std::string &key, const std::string &tag) const
Returns if the parameter key has a tag.
bool update(const Param &p_outdated, bool verbose, bool add_unknown, bool fail_on_invalid_values, bool fail_on_unknown_parameters, Logger::LogStream &stream)
Rescue parameter values from p_outdated to current param.
size_t size() const
Returns the number of entries (leafs).
ParamEntry & getEntry_(const std::string &key) const
Returns a mutable reference to a parameter entry.
void addTag(const std::string &key, const std::string &tag)
Adds the tag tag to the entry key.
void setValidStrings(const std::string &key, const std::vector< std::string > &strings)
Sets the valid strings for the parameter key.
void clearTags(const std::string &key)
Removes all tags from the entry key.
void remove(const std::string &key)
Remove the entry key or a section key (when suffix is ':')
Param()
Default constructor.
Param & operator=(Param &&) &=default
Move assignment operator.
Param(const Param &)=default
Copy constructor.
std::vector< std::string > getTags(const std::string &key) const
Returns the tags of entry key.
bool update(const Param &p_outdated, const bool add_unknown=false)
Rescue parameter values from p_outdated to current param.
Param copy(const std::string &prefix, bool remove_prefix=false) const
Returns a new Param object containing all entries that start with prefix.
bool operator==(const Param &rhs) const
Equality operator.
const ParamEntry & getEntry(const std::string &key) const
Returns the whole parameter entry.
void addSection(const std::string &key, const std::string &description)
Adds a parameter section under the path key with the given description.
ParamIterator begin() const
Begin iterator for the internal tree.
const std::string & getDescription(const std::string &key) const
Returns the description of a parameter.
bool empty() const
Returns if there are no entries.
Param(Param &&)=default
Move constructor.
Param & operator=(const Param &)=default
Assignment operator.
Param::ParamNode root_
Invisible root node that stores all the data.
Definition: Param.h:674
void setMaxFloat(const std::string &key, double max)
Sets the maximum value for the floating point or floating point list parameter key.
void insert(const std::string &prefix, const Param &param)
bool exists(const std::string &key) const
Tests if a parameter is set (expecting its fully qualified name, e.g., TextExporter:1:proteins_only)
void removeAll(const std::string &prefix)
Remove all entries that start with prefix.
ParamIterator findFirst(const std::string &leaf) const
Find leaf node by name (if it exists).
void setMaxInt(const std::string &key, int max)
Sets the maximum value for the integer or integer list parameter key.
ParamValue::ValueType getValueType(const std::string &key) const
Returns the type of a parameter.
void parseCommandLine(const int argc, const char **argv, const std::map< std::string, std::string > &options_with_one_argument, const std::map< std::string, std::string > &options_without_argument, const std::map< std::string, std::string > &options_with_multiple_argument, const std::string &misc="misc", const std::string &unknown="unknown")
Parses command line arguments to specified key locations.
const ParamValue & getValue(const std::string &key) const
Returns a value of a parameter.
void checkDefaults(const std::string &name, const Param &defaults, const std::string &prefix="") const
Checks the current parameter entries against given defaults.
ParamIterator end() const
End iterator for the internal tree.
void merge(const Param &toMerge)
Adds missing parameters from the given param toMerge to this param. Existing parameters will not be m...
void clear()
Deletes all entries.
ParamIterator findNext(const std::string &leaf, const ParamIterator &start_leaf) const
Find next leaf node by name (if it exists), not considering the start_leaf.
void addTags(const std::string &key, const std::vector< std::string > &tags)
Adds the tags in the list tags to the entry key.
void setMinInt(const std::string &key, int min)
Sets the minimum value for the integer or integer list parameter key.
const std::vector< std::string > & getValidStrings(const std::string &key) const
Gets he valid strings for the parameter key.
Param(const Param::ParamNode &node)
Constructor from a node which is used as root node.
bool hasSection(const std::string &key) const
Checks whether a section is present.
void parseCommandLine(const int argc, const char **argv, const std::string &prefix="")
Parses command line arguments.
~Param()
Destructor.
void setSectionDescription(const std::string &key, const std::string &description)
Sets a description for an existing section.
bool update(const Param &p_outdated, const bool add_unknown, Logger::LogStream &stream)
Rescue parameter values from p_outdated to current param.
Param copySubset(const Param &subset) const
Returns a new Param object containing all entries in the given subset.
void setValue(const std::string &key, const ParamValue &value, const std::string &description="", const std::vector< std::string > &tags=std::vector< std::string >())
Sets a value.
const std::string & getSectionDescription(const std::string &key) const
Returns the description corresponding to the section with name key.
void setMinFloat(const std::string &key, double min)
Sets the minimum value for the floating point or floating point list parameter key.
void setDefaults(const Param &defaults, const std::string &prefix="", bool showMessage=false)
Insert all values of defaults and adds the prefix prefix, if the values are not already set.
int verbose
Verbosity level ( "-v" is 1 and "-V" is 2 )
static String prefix(const String &this_s, size_t length)
Definition: StringUtilsSimple.h:147
Main OpenMS namespace.
Definition: FeatureDeconvolution.h:48
std::ostream & operator<<(std::ostream &os, const AccurateMassSearchResult &amsr)
Parameter entry used to store the actual information inside of a Param entry.
Definition: Param.h:75
ParamEntry(const std::string &n, const ParamValue &v, const std::string &d, const std::vector< std::string > &t=std::vector< std::string >())
Constructor with name, description, value and advanced flag.
double max_float
Default: std::numeric_limits<double>::max()
Definition: Param.h:108
std::string description
Description of the entry.
Definition: Param.h:100
ParamEntry(ParamEntry &&)=default
Move constructor.
ParamEntry & operator=(ParamEntry &&) &=default
Move assignment operator.
ParamEntry & operator=(const ParamEntry &)=default
Assignment operator.
std::vector< std::string > valid_strings
Default: empty.
Definition: Param.h:111
double min_float
Default: - std::numeric_limits<double>::max()
Definition: Param.h:107
std::string name
Name of the entry.
Definition: Param.h:98
ParamValue value
Value associated with the entry.
Definition: Param.h:102
int min_int
Default: - std::numeric_limits<Int>::max()
Definition: Param.h:109
bool operator==(const ParamEntry &rhs) const
Equality operator (only name and value are compared)
int max_int
Default: std::numeric_limits<Int>::max()
Definition: Param.h:110
ParamEntry()
Default constructor.
std::set< std::string > tags
Tags list, used e.g. for advanced parameter tag.
Definition: Param.h:104
bool isValid(std::string &message) const
Check if 'value' fulfills restrictions.
ParamEntry(const ParamEntry &)=default
Copy constructor.
Struct that captures information on entered / left nodes for ParamIterator.
Definition: Param.h:198
std::string description
description of the node
Definition: Param.h:210
TraceInfo(const std::string &n, const std::string &d, bool o)
Constructor with name, description, and open flag.
Definition: Param.h:200
std::string name
name of the node
Definition: Param.h:208
bool opened
If it was opened (true) or closed (false)
Definition: Param.h:212
Node inside a Param object which is used to build the internal tree.
Definition: Param.h:117
ParamNode(const std::string &n, const std::string &d)
Constructor with name and description.
std::string suffix(const std::string &key) const
Returns the name suffix of a key (the part behind the last ':' character)
std::vector< ParamNode > nodes
Subnodes.
Definition: Param.h:187
ParamNode & operator=(const ParamNode &)=default
Assignment operator.
std::vector< ParamNode >::const_iterator ConstNodeIterator
Iterator for child nodes.
Definition: Param.h:123
size_t size() const
Returns the number of entries in the whole subtree.
ParamNode(const ParamNode &)=default
Copy constructor.
std::string description
Description of the node.
Definition: Param.h:183
NodeIterator findNode(const std::string &name)
Look up subnode of this node (local search)
ParamNode & operator=(ParamNode &&) &=default
Move assignment operator.
EntryIterator findEntry(const std::string &name)
Look up entry of this node (local search)
void insert(const ParamNode &node, const std::string &prefix="")
Inserts a node with the given prefix.
std::vector< ParamEntry >::iterator EntryIterator
Iterator for entries.
Definition: Param.h:121
ParamNode * findParentOf(const std::string &name)
Look up the parent node of the entry or node corresponding to name (tree search)
std::string name
Name of the node.
Definition: Param.h:181
ParamEntry * findEntryRecursive(const std::string &name)
Look up the entry corresponding to name (tree search)
std::vector< ParamNode >::iterator NodeIterator
Iterator for child nodes.
Definition: Param.h:119
void insert(const ParamEntry &entry, const std::string &prefix="")
Inserts an entry with the given prefix.
std::vector< ParamEntry >::const_iterator ConstEntryIterator
Iterator for entries.
Definition: Param.h:125
ParamNode()
Default constructor.
std::vector< ParamEntry > entries
Entries (leafs) in the node.
Definition: Param.h:185
bool operator==(const ParamNode &rhs) const
Equality operator (name, entries and subnodes are compared)
ParamNode(ParamNode &&)=default
Move constructor.