OpenMS
Param Class Reference

Management and storage of parameters / INI files. More...

#include <OpenMS/DATASTRUCTURES/Param.h>

Collaboration diagram for Param:
[legend]

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...
 
Paramoperator= (const Param &)=default
 Assignment operator. More...
 
Paramoperator= (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 ParamValuegetValue (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 ParamEntrygetEntry (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 &param)
 
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...
 
ParamEntrygetEntry_ (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...
 

Detailed Description

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.

See also
DefaultParamHandler

Constructor & Destructor Documentation

◆ Param() [1/4]

Param ( )

Default constructor.

◆ Param() [2/4]

Param ( const Param )
default

Copy constructor.

◆ Param() [3/4]

Param ( Param &&  )
default

Move constructor.

◆ ~Param()

~Param ( )

Destructor.

◆ Param() [4/4]

Param ( const Param::ParamNode node)
protected

Constructor from a node which is used as root node.

Member Function Documentation

◆ addSection()

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.

◆ addTag()

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"

Exceptions
Exception::ElementNotFoundis thrown if the parameter does not exists.
Exception::InvalidValueis thrown if the tag contain a comma character.

Referenced by TOPPFLASHDeconv::registerOptionsAndFlags_().

◆ addTags()

void addTags ( const std::string &  key,
const std::vector< std::string > &  tags 
)

Adds the tags in the list tags to the entry key.

Exceptions
Exception::ElementNotFoundis thrown if the parameter does not exists.
Exception::InvalidValueis thrown if a tag contain a comma character.

◆ begin()

ParamIterator begin ( ) const

Begin iterator for the internal tree.

Referenced by main(), and DigestionEnzymeDB< DigestionEnzymeType, InstanceType >::readEnzymesFromFile_().

◆ checkDefaults()

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:

  • If a parameter is present for which no default value is specified, a warning is issued to os.
  • If the type of a parameter and its default do not match, an exception is thrown.
  • If a string parameter contains an invalid string, an exception is thrown.
  • If parameter entry is a string list, an exception is thrown, if one or more list members are invalid strings
  • If a numeric parameter is out of the valid range, an exception is thrown.
  • If entry is a numeric list an exception is thrown, if one or more list members are out of the valid range
Parameters
nameThe name that is used in error messages.
defaultsThe default values.
prefixThe prefix where to check for the defaults.

Warnings etc. will be send to OPENMS_LOG_WARN.

Exceptions
Exception::InvalidParameteris thrown if errors occur during the check

◆ clear()

void clear ( )

Deletes all entries.

Referenced by INIFileEditorWindow::openFile().

◆ clearTags()

void clearTags ( const std::string &  key)

Removes all tags from the entry key.

Exceptions
Exception::ElementNotFoundis thrown if the parameter does not exists.

◆ copy()

Param copy ( const std::string &  prefix,
bool  remove_prefix = false 
) const

Returns a new Param object containing all entries that start with prefix.

Parameters
prefixshould 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_prefixindicates if the prefix is removed before adding entries to the new Param

Referenced by FeatureDistance::DistanceParams_::DistanceParams_(), TOPPViewBase::getCanvasParameters(), TOPPASBase::loadPreferences(), TOPPViewBase::loadPreferences(), TOPPFLASHDeconv::main_(), TOPPOpenSwathBase::performCalibration(), TOPPViewBase::preferencesDialog(), TOPPASBase::savePreferences(), and TOPPViewBase::savePreferences().

◆ copySubset()

Param copySubset ( const Param subset) const

Returns a new Param object containing all entries in the given subset.

Parameters
subsetThe 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.
Note
Only matches entries and nodes at the root=top level and copies over whole subtrees if matched. This function is mainly used for copying subsection parameters that were not registered as as an actual subsection e.g. for backwards compatibility of param names.

◆ empty()

bool empty ( ) const

◆ end()

ParamIterator end ( ) const

End iterator for the internal tree.

Referenced by main(), and DigestionEnzymeDB< DigestionEnzymeType, InstanceType >::readEnzymesFromFile_().

◆ exists()

bool exists ( const std::string &  key) const

Tests if a parameter is set (expecting its fully qualified name, e.g., TextExporter:1:proteins_only)

Parameters
keyThe fully qualified name of the parameter to check.
Returns
True if the parameter exists, false otherwise.

Referenced by TOPPASBase::loadPreferences(), TOPPViewBase::loadPreferences(), and main().

◆ findFirst()

ParamIterator findFirst ( const std::string &  leaf) const

Find leaf node by name (if it exists).

Parameters
leafThe 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.
Returns
Returns end() if leaf does not exist.

◆ findNext()

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.

Parameters
leafThe 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_leafThe already found leaf, that should not be considered during this search.
Returns
Returns end() if leaf does not exist.

◆ getDescription()

const std::string& getDescription ( const std::string &  key) const

Returns the description of a parameter.

Exceptions
Exception::ElementNotFoundis thrown if the parameter does not exists.

◆ getEntry()

const ParamEntry& getEntry ( const std::string &  key) const

Returns the whole parameter entry.

Exceptions
Exception::ElementNotFoundis thrown if the parameter does not exists.

◆ getEntry_()

ParamEntry& getEntry_ ( const std::string &  key) const
protected

Returns a mutable reference to a parameter entry.

Exceptions
Exception::ElementNotFoundis thrown for unset parameters

◆ getSectionDescription()

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.

◆ getTags()

std::vector<std::string> getTags ( const std::string &  key) const

Returns the tags of entry key.

Exceptions
Exception::ElementNotFoundis thrown if the parameter does not exists.

◆ getValidStrings()

const std::vector<std::string>& getValidStrings ( const std::string &  key) const

Gets he valid strings for the parameter key.

Exceptions
Exception::ElementNotFoundexception is thrown, if the parameter is no string/stringlist parameter

◆ getValue()

◆ getValueType()

ParamValue::ValueType getValueType ( const std::string &  key) const

Returns the type of a parameter.

Exceptions
Exception::ElementNotFoundis thrown if the parameter does not exists.

◆ hasSection()

bool hasSection ( const std::string &  key) const

Checks whether a section is present.

Parameters
keyThe key of the section to be searched for. May or may not contain ":" suffix.
Returns
True if the section exists, false otherwise.

Referenced by TOPPViewBase::loadPreferences(), TOPPViewBase::savePreferences(), and TOPPViewBase::showTOPPDialog_().

◆ hasTag()

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

Exceptions
Exception::ElementNotFoundis thrown if the parameter does not exists.

◆ insert()

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::initializeDefaultParameters_(), TOPPViewBase::loadPreferences(), TOPPViewBase::preferencesDialog(), TOPPFLASHDeconv::registerOptionsAndFlags_(), TOPPASBase::savePreferences(), TOPPViewBase::savePreferences(), and TOPPViewBase::showTOPPDialog_().

◆ merge()

void merge ( const Param toMerge)

Adds missing parameters from the given param toMerge to this param. Existing parameters will not be modified.

Parameters
toMergeThe Param object from which parameters should be added to this param.

◆ operator=() [1/2]

Param& operator= ( const Param )
default

Assignment operator.

◆ operator=() [2/2]

Param& operator= ( Param &&  ) &
default

Move assignment operator.

◆ operator==()

bool operator== ( const Param rhs) const

Equality operator.

◆ parseCommandLine() [1/2]

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.

Parameters
argcargc variable from command line
argvargv variable from command line
options_with_one_argumenta map of options that are followed by one argument (with key where they are stored)
options_without_argumenta 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_argumenta map of options that are followed by several arguments (with key where they are stored)
misckey where a StringList of all non-option arguments are stored
unknownkey where a StringList of all unknown options are stored

◆ parseCommandLine() [2/2]

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")

Parameters
argcargc variable from command line
argvargv variable from command line
prefixprefix for all options

Referenced by main().

◆ remove()

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(), and TOPPFLASHDeconv::registerOptionsAndFlags_().

◆ removeAll()

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

◆ setDefaults()

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.

Parameters
defaultsThe default values.
prefixThe prefix to add to all defaults.
showMessageIf true each default that is actually set is printed to stdout as well.
See also
checkDefaults

◆ setMaxFloat()

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

Exceptions
Exception::ElementNotFoundis thrown if key is not found or if the parameter type is wrong

Referenced by SignalToNoiseEstimatorMeanIterative< Container >::SignalToNoiseEstimatorMeanIterative(), and SignalToNoiseEstimatorMedian< Container >::SignalToNoiseEstimatorMedian().

◆ setMaxInt()

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

Exceptions
Exception::ElementNotFoundis thrown if key is not found or if the parameter type is wrong

Referenced by SignalToNoiseEstimatorMeanIterative< Container >::SignalToNoiseEstimatorMeanIterative(), and SignalToNoiseEstimatorMedian< Container >::SignalToNoiseEstimatorMedian().

◆ setMinFloat()

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

Exceptions
Exception::ElementNotFoundis thrown if key is not found or if the parameter type is wrong

Referenced by SignalToNoiseEstimatorMeanIterative< Container >::SignalToNoiseEstimatorMeanIterative(), and SignalToNoiseEstimatorMedian< Container >::SignalToNoiseEstimatorMedian().

◆ setMinInt()

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

Exceptions
Exception::ElementNotFoundis thrown if key is not found or if the parameter type is wrong

Referenced by SignalToNoiseEstimatorMeanIterative< Container >::SignalToNoiseEstimatorMeanIterative(), and SignalToNoiseEstimatorMedian< Container >::SignalToNoiseEstimatorMedian().

◆ setSectionDescription()

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.

Exceptions
Exception::ElementNotFoundis thrown if the section does not exists.

Referenced by TOPPViewBase::initializeDefaultParameters_().

◆ setValidStrings()

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

Exceptions
Exception::InvalidParameteris thrown, if one of the strings contains a comma character
Exception::ElementNotFoundexception is thrown, if the parameter is no string/stringlist parameter

Referenced by TOPPViewBase::initializeDefaultParameters_(), SignalToNoiseEstimatorMedian< Container >::SignalToNoiseEstimatorMedian(), and TOPPASBase::TOPPASBase().

◆ setValue()

◆ size()

size_t size ( ) const

Returns the number of entries (leafs).

◆ update() [1/3]

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:

  • the name is equal
  • the type is equal
  • the value from p_outdated meets the new restrictions

Not transferred are values from parameter "version" (to preserve the new version) or "type" (to preserve layout).

Parameters
p_outdatedOld/outdated param object, whose values (as long as they are still valid) are used to update this object
verbosePrint information about expected value updates
add_unknownAdd unknown parameters from p_outdated to this param object.
fail_on_invalid_valuesReturn false if outdated parameters hold invalid values
fail_on_unknown_parametersReturn false if outdated parameters contain unknown parameters (takes precedence over add_unknown)
streamThe stream where all the logging output is send to.
Returns
true on success, false on failure

◆ update() [2/3]

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.

◆ update() [3/3]

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.

Member Data Documentation

◆ root_

Param::ParamNode root_
mutableprotected

Invisible root node that stores all the data.