OpenMS
2.8.0
|
Management and storage of parameters / INI files. More...
#include <OpenMS/DATASTRUCTURES/Param.h>
Classes | |
struct | ParamEntry |
Parameter entry used to store the actual information inside of a Param entry. More... | |
class | ParamIterator |
Forward const iterator for the Param class. More... | |
struct | ParamNode |
Node inside a Param object which is used to build the internal tree. More... | |
Public Member Functions | |
Param () | |
Default constructor. More... | |
Param (const Param &)=default | |
Copy constructor. More... | |
Param (Param &&)=default | |
Move constructor. More... | |
~Param () | |
Destructor. More... | |
Param & | operator= (const Param &)=default |
Assignment operator. More... | |
Param & | operator= (Param &&) &=default |
Move assignment operator. More... | |
bool | operator== (const Param &rhs) const |
Equality operator. More... | |
ParamIterator | begin () const |
Begin iterator for the internal tree. More... | |
ParamIterator | end () const |
End iterator for the internal tree. More... | |
Accessors for single parameters | |
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. More... | |
const ParamValue & | getValue (const std::string &key) const |
Returns a value of a parameter. More... | |
ParamValue::ValueType | getValueType (const std::string &key) const |
Returns the type of a parameter. More... | |
const ParamEntry & | getEntry (const std::string &key) const |
Returns the whole parameter entry. More... | |
bool | exists (const std::string &key) const |
Tests if a parameter is set (expecting its fully qualified name, e.g., TextExporter:1:proteins_only) More... | |
bool | hasSection (const std::string &key) const |
Checks whether a section is present. More... | |
ParamIterator | findFirst (const std::string &leaf) const |
Find leaf node by name (if it exists). More... | |
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 . More... | |
Tags handling | |
void | addTag (const std::string &key, const std::string &tag) |
Adds the tag tag to the entry key . More... | |
void | addTags (const std::string &key, const std::vector< std::string > &tags) |
Adds the tags in the list tags to the entry key . More... | |
bool | hasTag (const std::string &key, const std::string &tag) const |
Returns if the parameter key has a tag. More... | |
std::vector< std::string > | getTags (const std::string &key) const |
Returns the tags of entry key . More... | |
void | clearTags (const std::string &key) |
Removes all tags from the entry key . More... | |
Descriptions handling | |
const std::string & | getDescription (const std::string &key) const |
Returns the description of a parameter. More... | |
void | setSectionDescription (const std::string &key, const std::string &description) |
Sets a description for an existing section. More... | |
const std::string & | getSectionDescription (const std::string &key) const |
Returns the description corresponding to the section with name key . More... | |
void | addSection (const std::string &key, const std::string &description) |
Adds a parameter section under the path key with the given description . More... | |
Manipulation of the whole parameter set | |
size_t | size () const |
Returns the number of entries (leafs). More... | |
bool | empty () const |
Returns if there are no entries. More... | |
void | clear () |
Deletes all entries. More... | |
void | insert (const std::string &prefix, const Param ¶m) |
void | remove (const std::string &key) |
Remove the entry key or a section key (when suffix is ':') More... | |
void | removeAll (const std::string &prefix) |
Remove all entries that start with prefix . More... | |
Param | copy (const std::string &prefix, bool remove_prefix=false) const |
Returns a new Param object containing all entries that start with prefix . More... | |
Param | copySubset (const Param &subset) const |
Returns a new Param object containing all entries in the given subset. More... | |
bool | update (const Param &p_outdated, const bool add_unknown=false) |
Rescue parameter values from p_outdated to current param. More... | |
bool | update (const Param &p_outdated, const bool add_unknown, Logger::LogStream &stream) |
Rescue parameter values from p_outdated to current param. More... | |
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. More... | |
void | merge (const Param &toMerge) |
Adds missing parameters from the given param toMerge to this param. Existing parameters will not be modified. More... | |
Default value handling | |
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. More... | |
void | checkDefaults (const std::string &name, const Param &defaults, const std::string &prefix="") const |
Checks the current parameter entries against given defaults . More... | |
Restriction handling | |
void | setValidStrings (const std::string &key, const std::vector< std::string > &strings) |
Sets the valid strings for the parameter key . More... | |
const std::vector< std::string > & | getValidStrings (const std::string &key) const |
Gets he valid strings for the parameter key . More... | |
void | setMinInt (const std::string &key, int min) |
Sets the minimum value for the integer or integer list parameter key . More... | |
void | setMaxInt (const std::string &key, int max) |
Sets the maximum value for the integer or integer list parameter key . More... | |
void | setMinFloat (const std::string &key, double min) |
Sets the minimum value for the floating point or floating point list parameter key . More... | |
void | setMaxFloat (const std::string &key, double max) |
Sets the maximum value for the floating point or floating point list parameter key . More... | |
Command line parsing | |
Param::ParamNode | root_ |
Invisible root node that stores all the data. More... | |
void | parseCommandLine (const int argc, const char **argv, const std::string &prefix="") |
Parses command line arguments. More... | |
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. More... | |
ParamEntry & | getEntry_ (const std::string &key) const |
Returns a mutable reference to a parameter entry. More... | |
Param (const Param::ParamNode &node) | |
Constructor from a node which is used as root node. More... | |
Management and storage of parameters / INI files.
This class provides a means to associate string names to int/double/string/StringList values. It allows for parameter hierarchies and to save/load the data as XML. Hierarchy levels are separated from each other by colons.
Example: 'common:file_options:default_file_open_path = /share/'
Each parameter and section has a description. Newline characters in the description are possible.
Each parameter can be annotated with an arbitrary number of tags. Tags must not contain comma characters!
E.g. the advanced tag indicates if this parameter is shown to all users or in advanced mode only.
Param | ( | ) |
Default constructor.
~Param | ( | ) |
Destructor.
|
protected |
Constructor from a node which is used as root node.
void addSection | ( | const std::string & | key, |
const std::string & | description | ||
) |
Adds a parameter section under the path key
with the given description
.
If the section already exists, the description is only overwritten if not empty.
Referenced by TOPPViewBase::addToolParamsToIni_().
void addTag | ( | const std::string & | key, |
const std::string & | tag | ||
) |
Adds the tag tag
to the entry key
.
E.g. "advanced", "required", "input file", "output file"
Exception::ElementNotFound | is thrown if the parameter does not exists. |
Exception::InvalidValue | is thrown if the tag contain a comma character. |
void addTags | ( | const std::string & | key, |
const std::vector< std::string > & | tags | ||
) |
Adds the tags in the list tags
to the entry key
.
Exception::ElementNotFound | is thrown if the parameter does not exists. |
Exception::InvalidValue | is thrown if a tag contain a comma character. |
ParamIterator begin | ( | ) | const |
Begin iterator for the internal tree.
Referenced by main(), and DigestionEnzymeDB< DigestionEnzymeType, InstanceType >::readEnzymesFromFile_().
void checkDefaults | ( | const std::string & | name, |
const Param & | defaults, | ||
const std::string & | prefix = "" |
||
) | const |
Checks the current parameter entries against given defaults
.
Several checks are performed:
os
.name | The name that is used in error messages. |
defaults | The default values. |
prefix | The prefix where to check for the defaults. |
Warnings etc. will be send to OPENMS_LOG_WARN.
Exception::InvalidParameter | is thrown if errors occur during the check |
void clear | ( | ) |
Deletes all entries.
Referenced by INIFileEditorWindow::openFile().
void clearTags | ( | const std::string & | key | ) |
Removes all tags from the entry key
.
Exception::ElementNotFound | is thrown if the parameter does not exists. |
Param copy | ( | const std::string & | prefix, |
bool | remove_prefix = false |
||
) | const |
Returns a new Param object containing all entries that start with prefix
.
prefix | should contain a ':' at the end if you want to extract a subtree. Otherwise not only nodes, but as well values with that prefix are copied. |
remove_prefix | indicates if the prefix is removed before adding entries to the new Param |
Referenced by FeatureDistance::DistanceParams_::DistanceParams_(), TOPPViewBase::getCanvasParameters(), TOPPASBase::loadPreferences(), TOPPViewBase::loadPreferences(), TOPPOpenSwathBase::performCalibration(), TOPPViewBase::preferencesDialog(), TOPPASBase::savePreferences(), TOPPViewBase::savePreferences(), TOPPViewBase::showTOPPDialog_(), and ProductModel< 2 >::updateMembers_().
Returns a new Param object containing all entries in the given subset.
subset | The subset of Param nodes that should be copied out of the object here. Includes values etc. Does not check any compatibility. Just matches the names. |
bool empty | ( | ) | const |
Returns if there are no entries.
Referenced by DigestionEnzymeDB< DigestionEnzymeType, InstanceType >::readEnzymesFromFile_().
ParamIterator end | ( | ) | const |
End iterator for the internal tree.
Referenced by main(), and DigestionEnzymeDB< DigestionEnzymeType, InstanceType >::readEnzymesFromFile_().
bool exists | ( | const std::string & | key | ) | const |
Tests if a parameter is set (expecting its fully qualified name, e.g., TextExporter:1:proteins_only)
key | The fully qualified name of the parameter to check. |
Referenced by TOPPASBase::loadPreferences(), TOPPViewBase::loadPreferences(), and main().
ParamIterator findFirst | ( | const std::string & | leaf | ) | const |
Find leaf node by name (if it exists).
leaf | The name of the parameter to find excluding the path parameter, e.g., given the parameter TextExporter:1:proteins_only the leaf would be named proteins_only. |
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
.
leaf | The name of the parameter to find excluding the path parameter, e.g., given the parameter TextExporter:1:proteins_only the leaf would be named proteins_only. |
start_leaf | The already found leaf, that should not be considered during this search. |
const std::string& getDescription | ( | const std::string & | key | ) | const |
Returns the description of a parameter.
Exception::ElementNotFound | is thrown if the parameter does not exists. |
const ParamEntry& getEntry | ( | const std::string & | key | ) | const |
Returns the whole parameter entry.
Exception::ElementNotFound | is thrown if the parameter does not exists. |
|
protected |
Returns a mutable reference to a parameter entry.
Exception::ElementNotFound | is thrown for unset parameters |
const std::string& getSectionDescription | ( | const std::string & | key | ) | const |
Returns the description corresponding to the section with name key
.
If the section does not exist an empty string is returned.
std::vector<std::string> getTags | ( | const std::string & | key | ) | const |
Returns the tags of entry key
.
Exception::ElementNotFound | is thrown if the parameter does not exists. |
const std::vector<std::string>& getValidStrings | ( | const std::string & | key | ) | const |
Gets he valid strings for the parameter key
.
Exception::ElementNotFound | exception is thrown, if the parameter is no string/stringlist parameter |
const ParamValue& getValue | ( | const std::string & | key | ) | const |
Returns a value of a parameter.
Exception::ElementNotFound | is thrown if the parameter does not exists. |
Referenced by TOPPViewBase::addData(), TOPPViewBase::addDataFile(), FeatureDistance::DistanceParams_::DistanceParams_(), TOPPViewBase::fileChanged_(), TOPPViewBase::finishTOPPToolExecution(), TOPPViewBase::getCanvasParameters(), SiriusAdapterAlgorithm::ParameterSection::getCommandLine(), SiriusAdapterAlgorithm::ParameterSection::getValue(), TOPPASBase::loadPreferences(), TOPPViewBase::loadPreferences(), main(), TOPPOpenSwathBase::performCalibration(), TOPPASBase::savePreferences(), TOPPViewBase::savePreferences(), TOPPViewBase::showSpectrumGenerationDialog(), TOPPASBase::TOPPASBase(), TOPPViewBase::TOPPViewBase(), TOPPASBase::updateCurrentPath(), TOPPViewBase::updateCurrentPath(), SignalToNoiseEstimatorMeanIterative< Container >::updateMembers_(), SignalToNoiseEstimatorMedian< Container >::updateMembers_(), and BaseModel< D >::updateMembers_().
ParamValue::ValueType getValueType | ( | const std::string & | key | ) | const |
Returns the type of a parameter.
Exception::ElementNotFound | is thrown if the parameter does not exists. |
bool hasSection | ( | const std::string & | key | ) | const |
Checks whether a section is present.
key | The key of the section to be searched for. May or may not contain ":" suffix. |
Referenced by TOPPViewBase::loadPreferences(), TOPPViewBase::savePreferences(), and TOPPViewBase::showTOPPDialog_().
bool hasTag | ( | const std::string & | key, |
const std::string & | tag | ||
) | const |
Returns if the parameter key
has a tag.
Example: The tag 'advanced' is used in the GUI to determine which parameters are always displayed and which parameters are displayed only in 'advanced mode'.
Exception::ElementNotFound | is thrown if the parameter does not exists. |
void insert | ( | const std::string & | prefix, |
const Param & | param | ||
) |
Insert all values of param
and adds the prefix prefix
. You should append ':' to prefix manually when you want it to be a section.
Referenced by TOPPViewBase::addToolParamsToIni_(), TOPPViewBase::initializeDefaultParameters_(), TOPPViewBase::loadPreferences(), TOPPViewBase::preferencesDialog(), TOPPASBase::savePreferences(), and TOPPViewBase::savePreferences().
void merge | ( | const Param & | toMerge | ) |
Adds missing parameters from the given param toMerge
to this param. Existing parameters will not be modified.
toMerge | The Param object from which parameters should be added to this param. |
bool operator== | ( | const Param & | rhs | ) | const |
Equality operator.
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.
Parses command line arguments to specified key locations and stores the result internally.
argc | argc variable from command line |
argv | argv variable from command line |
options_with_one_argument | a map of options that are followed by one argument (with key where they are stored) |
options_without_argument | a map of options that are not followed by an argument (with key where they are stored). Options specified on the command line are set to the string 'true'. |
options_with_multiple_argument | a map of options that are followed by several arguments (with key where they are stored) |
misc | key where a StringList of all non-option arguments are stored |
unknown | key where a StringList of all unknown options are stored |
void parseCommandLine | ( | const int | argc, |
const char ** | argv, | ||
const std::string & | prefix = "" |
||
) |
Parses command line arguments.
This method discriminates three types of arguments:
(1) options (starting with '-') that have a text argument
(2) options (starting with '-') that have no text argument
(3) text arguments (not starting with '-')
Command line arguments '-a avalue -b -c bvalue misc1 misc2' would be stored like this:
"prefix:-a" -> "avalue"
"prefix:-b" -> ""
"prefix:-c" -> "bvalue"
"prefix:misc" -> list("misc1","misc2")
argc | argc variable from command line |
argv | argv variable from command line |
prefix | prefix for all options |
Referenced by main().
void remove | ( | const std::string & | key | ) |
Remove the entry key
or a section key
(when suffix is ':')
Remove deletes either an entry or a section (when key
ends with ':'), by matching the exact name. No partial matches are accepted.
If an empty internal node remains, the tree is pruned until every node has either a successor node or a leaf, i.e. no naked nodes remain.
Referenced by TOPPViewBase::preferencesDialog().
void removeAll | ( | const std::string & | prefix | ) |
Remove all entries that start with prefix
.
Partial are valid as well. All entries and sections which match the prefix are deleted.
If an empty internal node remains, the tree is pruned until every node has either a successor node or a leaf, i.e. no naked nodes remain.
Referenced by TOPPASBase::savePreferences(), and TOPPViewBase::savePreferences().
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.
defaults | The default values. |
prefix | The prefix to add to all defaults. |
showMessage | If true each default that is actually set is printed to stdout as well. |
void setMaxFloat | ( | const std::string & | key, |
double | max | ||
) |
Sets the maximum value for the floating point or floating point list parameter key
.
It is only checked in checkDefaults().
Exception::ElementNotFound | is thrown if key is not found or if the parameter type is wrong |
Referenced by SignalToNoiseEstimatorMeanIterative< Container >::SignalToNoiseEstimatorMeanIterative(), and SignalToNoiseEstimatorMedian< Container >::SignalToNoiseEstimatorMedian().
void setMaxInt | ( | const std::string & | key, |
int | max | ||
) |
Sets the maximum value for the integer or integer list parameter key
.
It is only checked in checkDefaults().
Exception::ElementNotFound | is thrown if key is not found or if the parameter type is wrong |
Referenced by SignalToNoiseEstimatorMeanIterative< Container >::SignalToNoiseEstimatorMeanIterative(), and SignalToNoiseEstimatorMedian< Container >::SignalToNoiseEstimatorMedian().
void setMinFloat | ( | const std::string & | key, |
double | min | ||
) |
Sets the minimum value for the floating point or floating point list parameter key
.
It is only checked in checkDefaults().
Exception::ElementNotFound | is thrown if key is not found or if the parameter type is wrong |
Referenced by SignalToNoiseEstimatorMeanIterative< Container >::SignalToNoiseEstimatorMeanIterative(), and SignalToNoiseEstimatorMedian< Container >::SignalToNoiseEstimatorMedian().
void setMinInt | ( | const std::string & | key, |
int | min | ||
) |
Sets the minimum value for the integer or integer list parameter key
.
It is only checked in checkDefaults().
Exception::ElementNotFound | is thrown if key is not found or if the parameter type is wrong |
Referenced by SignalToNoiseEstimatorMeanIterative< Container >::SignalToNoiseEstimatorMeanIterative(), SignalToNoiseEstimatorMedian< Container >::SignalToNoiseEstimatorMedian(), and SiriusAdapterAlgorithm::ParameterModifier::withMinInt().
void setSectionDescription | ( | const std::string & | key, |
const std::string & | description | ||
) |
Sets a description for an existing section.
Descriptions for values cannot be set with this method. They have to be set when inserting the value itself.
Exception::ElementNotFound | is thrown if the section does not exists. |
Referenced by TOPPViewBase::initializeDefaultParameters_().
void setValidStrings | ( | const std::string & | key, |
const std::vector< std::string > & | strings | ||
) |
Sets the valid strings for the parameter key
.
It is only checked in checkDefaults().
Exception::InvalidParameter | is thrown, if one of the strings contains a comma character |
Exception::ElementNotFound | exception is thrown, if the parameter is no string/stringlist parameter |
Referenced by TOPPViewBase::initializeDefaultParameters_(), SignalToNoiseEstimatorMedian< Container >::SignalToNoiseEstimatorMedian(), TOPPASBase::TOPPASBase(), and SiriusAdapterAlgorithm::ParameterModifier::withValidStrings().
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.
key | String key. Can contain ':' which separates section names |
value | The actual value |
description | Verbose description of the parameter |
tags | list of tags associated to this parameter |
Referenced by BaseModel< D >::BaseModel(), NucleicAcidSearchEngine::calculateAndFilterFDR_(), TOPPViewBase::getCanvasParameters(), TOPPViewBase::initializeDefaultParameters_(), TOPPViewBase::loadFiles(), TOPPASBase::loadPreferences(), TOPPViewBase::loadPreferences(), NucleicAcidSearchEngine::main_(), SpectraMerger::mergeSpectra_(), TOPPOpenSwathBase::performCalibration(), PeakPickerIterative::pick(), EmgScoring::prepareFit_(), NucleicAcidSearchEngine::preprocessSpectra_(), TOPPASBase::savePreferences(), TOPPViewBase::savePreferences(), BaseModel< D >::setCutOff(), TOPPViewBase::showSpectrumAlignmentDialog(), TOPPViewBase::showSpectrumGenerationDialog(), SignalToNoiseEstimatorMeanIterative< Container >::SignalToNoiseEstimatorMeanIterative(), SignalToNoiseEstimatorMedian< Container >::SignalToNoiseEstimatorMedian(), SignalToNoiseOpenMS< ContainerT >::SignalToNoiseOpenMS(), and TOPPASBase::TOPPASBase().
size_t size | ( | ) | const |
Returns the number of entries (leafs).
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.
All parameters present in both param objects will be transferred into this object, given that:
p_outdated
meets the new restrictions Not transferred are values from parameter "version" (to preserve the new version) or "type" (to preserve layout).
p_outdated | Old/outdated param object, whose values (as long as they are still valid) are used to update this object |
verbose | Print information about expected value updates |
add_unknown | Add unknown parameters from @p_outdated to this param object. |
fail_on_invalid_values | Return false if outdated parameters hold invalid values |
fail_on_unknown_parameters | Return false if outdated parameters contain unknown parameters (takes precedence over add_unknown ) |
stream | The stream where all the logging output is send to. |
bool update | ( | const Param & | p_outdated, |
const bool | add_unknown, | ||
Logger::LogStream & | stream | ||
) |
Rescue parameter values from p_outdated
to current param.
Calls ::update(p_outdated, true, add_unknown, false, false, stream) and returns its value.
bool update | ( | const Param & | p_outdated, |
const bool | add_unknown = false |
||
) |
Rescue parameter values from p_outdated
to current param.
Calls ::update(p_outdated, true, add_unknown, false, false, OPENMS_LOG_WARN) and returns its value.
|
mutableprotected |
Invisible root node that stores all the data.