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

Param Class Reference
[Datastructures]

#include <OpenMS/DATASTRUCTURES/Param.h>

Inheritance diagram for Param:

XMLFile

List of all members.


Detailed Description

Management and storage of parameters / INI files.

This class provides a means to associate string names to int/double/string values. It parameter hierarchies and to save/load the contained data as XML. Hierachy levels are separated from each other and from the name 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 has a advanced flag that inidcates if this parameter is shown to all users (false) or in advanced mode only (true). This is mostly used in visualization.

See also:
DefaultParamHandler

Public Member Functions

Paramoperator= (const Param &rhs)
 Assignment operator.
bool operator== (const Param &rhs) const
 Equality operator.
Constructors and Destructors
 Param ()
 Default construtor.
 Param (const Param &rhs)
 Copy constructor.
 ~Param ()
 Destructor.
Accessors for single parameters
void setValue (const String &key, Int value, const String &description="", bool advanced=false)
 Set an Int value.
void setValue (const String &key, UInt value, const String &description="", bool advanced=false)
 Set a UInt value.
void setValue (const String &key, Real value, const String &description="", bool advanced=false)
 Set a float value.
void setValue (const String &key, DoubleReal value, const String &description="", bool advanced=false)
 Set a double value.
void setValue (const String &key, const String &value, const String &description="", bool advanced=false)
 Set a string value.
const DataValuegetValue (const String &key) const throw (Exception::ElementNotFound<String>)
 Returns a value of a parameter.
const ParamEntrygetEntry (const String &key) const throw (Exception::ElementNotFound<String>)
 Returns the whole parameter entry.
const StringgetDescription (const String &key) const throw (Exception::ElementNotFound<String>)
 Returns the description of a parameter.
bool isAdvancedParameter (const String &key) const throw (Exception::ElementNotFound<String>)
 Returns if the parameter is a advanced parameter.
void setSectionDescription (const String &key, const String &description) throw (Exception::ElementNotFound<String>)
 Sets a description for an existing section.
const StringgetSectionDescription (const String &key) const
 Returns the description corresponding to the section with name key.
ParamIterator begin () const
 Begin iterator for the internal tree.
ParamIterator end () const
 End iterator for the internal tree.
bool exists (const String &key) const
 Tests if a parameter is set.
Manipulation of the whole parameter set
UInt size () const
 Returns the number of entries (leafs).
bool empty () const
 Returns if there are no entries.
void clear ()
 Deletes all entries.
void insert (String prefix, const Param &param)
 Insert all values of param and adds the prefix prefix.
void remove (const String &prefix)
 Remove all entries that start with prefix.
Param copy (const String &prefix, bool remove_prefix=false) const
 Returns a new Param object containing all entries that start with prefix.
Default value handling
void setDefaults (const Param &defaults, String prefix="", bool showMessage=false)
 Insert all values of defaults and adds the prefix prefix, if the values are not already set.
void checkDefaults (const String &name, const Param &defaults, String prefix="", std::ostream &os=std::cout) const throw (Exception::InvalidParameter)
 Checks the current parameter entries against given defaults.
void setValidStrings (const String &key, const std::vector< String > &strings) throw (Exception::ElementNotFound<String>,Exception::InvalidParameter)
 Sets the valid strings for the parameter key.
void setMinInt (const String &key, Int min) throw (Exception::ElementNotFound<String>)
 Sets the minimum value for the integer parameter key.
void setMaxInt (const String &key, Int max) throw (Exception::ElementNotFound<String>)
 Sets the maximum value for the integer parameter key.
void setMinFloat (const String &key, DoubleReal min) throw (Exception::ElementNotFound<String>)
 Sets the minimum value for the floating point parameter key.
void setMaxFloat (const String &key, DoubleReal max) throw (Exception::ElementNotFound<String>)
 Sets the maximum value for the floating point parameter key.
Command line parsing
void parseCommandLine (const int argc, const char **argv, String prefix="")
 Parses command line arguments.
void parseCommandLine (const int argc, const char **argv, const std::map< String, String > &options_with_argument, const std::map< String, String > &options_without_argument, const String &misc="misc", const String &unknown="unknown")
 Parses command line arguments to specified key locations.
File I/O methods
void store (const String &filename) const throw (Exception::UnableToCreateFile)
 Write XML file.
void load (const String &filename) throw (Exception::FileNotFound,Exception::ParseError)
 Read XML file.

Protected Member Functions

ParamEntrygetEntry_ (const String &key) const throw (Exception::ElementNotFound<String>)
 Returns a mutable reference to a parameter entry.
 Param (const Param::ParamNode &node)
 Constructor from a node wich is used as root node.

Protected Attributes

Param::ParamNode root_
 Invisible root node that stores all the data.

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

Constructor & Destructor Documentation

Param (  ) 

Default construtor.

Param ( const Param rhs  ) 

Copy constructor.

~Param (  ) 

Destructor.

Param ( const Param::ParamNode node  )  [protected]

Constructor from a node wich is used as root node.


Member Function Documentation

Param& operator= ( const Param rhs  ) 

Assignment operator.

bool operator== ( const Param rhs  )  const

Equality operator.

void setValue ( const String key,
Int  value,
const String description = "",
bool  advanced = false 
)

Set an Int value.

Parameters:
key String key. Can contain ':' which separates section names
value The actual value
description Verbose description of the parameter
advanced If 'false' this parameter is always shown. If 'true' it is only shown in the expert mode

void setValue ( const String key,
UInt  value,
const String description = "",
bool  advanced = false 
)

Set a UInt value.

Parameters:
key String key. Can contain ':' which separates section names
value The actual value
description Verbose description of the parameter
advanced If 'false' this parameter is always shown. If 'true' it is only shown in the expert mode

void setValue ( const String key,
Real  value,
const String description = "",
bool  advanced = false 
)

Set a float value.

Parameters:
key String key. Can contain ':'which separates section names
value The actual value
description Verbose description of the parameter
advanced If 'false' this parameter is always shown. If 'true' it is only shown in the expert mode

void setValue ( const String key,
DoubleReal  value,
const String description = "",
bool  advanced = false 
)

Set a double value.

Parameters:
key String key. Can contain ':' which separates section names
value The actual value
description Verbose description of the parameter
advanced If 'false' this parameter is always shown. If 'true' it is only shown in the expert mode

void setValue ( const String key,
const String value,
const String description = "",
bool  advanced = false 
)

Set a string value.

Parameters:
key String key. Can contain ':' which separates section names
value The actual value
description Verbose description of the parameter
advanced If 'false' this parameter is always shown. If 'true' it is only shown in the expert mode

const DataValue& getValue ( const String key  )  const throw (Exception::ElementNotFound<String>)

Returns a value of a parameter.

An ElementNotFound exception is thrown if the paramter does not exists.

const ParamEntry& getEntry ( const String key  )  const throw (Exception::ElementNotFound<String>)

Returns the whole parameter entry.

An ElementNotFound exception is thrown if the paramter does not exists.

const String& getDescription ( const String key  )  const throw (Exception::ElementNotFound<String>)

Returns the description of a parameter.

An ElementNotFound exception is thrown if the paramter does not exists.

bool isAdvancedParameter ( const String key  )  const throw (Exception::ElementNotFound<String>)

Returns if the parameter is a advanced parameter.

This is mainly used in the GUI to determine which parmeters are always displayed and which parameters are displayed only in 'advanced mode'.

An ElementNotFound exception is thrown if the paramter does not exists.

void setSectionDescription ( const String key,
const String description 
) throw (Exception::ElementNotFound<String>)

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.

const String& getSectionDescription ( const String key  )  const

Returns the description corresponding to the section with name key.

If the section does not exist an empty string is returned.

ParamIterator begin (  )  const

Begin iterator for the internal tree.

ParamIterator end (  )  const

End iterator for the internal tree.

bool exists ( const String key  )  const

Tests if a parameter is set.

UInt size (  )  const

Returns the number of entries (leafs).

bool empty (  )  const

Returns if there are no entries.

void clear (  ) 

Deletes all entries.

void insert ( String  prefix,
const Param param 
)

Insert all values of param and adds the prefix prefix.

void remove ( const String prefix  ) 

Remove all entries that start with prefix.

Param copy ( const String prefix,
bool  remove_prefix = false 
) const

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

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

void setDefaults ( const Param defaults,
String  prefix = "",
bool  showMessage = false 
)

Insert all values of defaults and adds the prefix prefix, if the values are not already set.

Parameters:
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.
See also:
checkDefaults

void checkDefaults ( const String name,
const Param defaults,
String  prefix = "",
std::ostream &  os = std::cout 
) const throw (Exception::InvalidParameter)

Checks the current parameter entries against given defaults.

Several checks are performed:

Parameters:
name The name that is used in error messages.
defaults The default values.
prefix The prefix where to check for the defaults.
os The output stream for the warnings.

void setValidStrings ( const String key,
const std::vector< String > &  strings 
) throw (Exception::ElementNotFound<String>,Exception::InvalidParameter)

Sets the valid strings for the parameter key.

It is only checked in checkDefaults().

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

The strings must not contain comma characters. Otherwise an InvalidParameter exception is thrown.

void setMinInt ( const String key,
Int  min 
) throw (Exception::ElementNotFound<String>)

Sets the minimum value for the integer parameter key.

It is only checked in checkDefaults(). Throws an exception if key is not found or if the parameter type is wrong.

void setMaxInt ( const String key,
Int  max 
) throw (Exception::ElementNotFound<String>)

Sets the maximum value for the integer parameter key.

It is only checked in checkDefaults(). Throws an exception if key is not found or if the parameter type is wrong.

void setMinFloat ( const String key,
DoubleReal  min 
) throw (Exception::ElementNotFound<String>)

Sets the minimum value for the floating point parameter key.

It is only checked in checkDefaults(). Throws an exception if key is not found or if the parameter type is wrong.

void setMaxFloat ( const String key,
DoubleReal  max 
) throw (Exception::ElementNotFound<String>)

Sets the maximum value for the floating point parameter key.

It is only checked in checkDefaults(). Throws an exception if key is not found or if the parameter type is wrong.

void parseCommandLine ( const int  argc,
const char **  argv,
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" -> "misc1 misc2"

Parameters:
argc argc variable from command line
argv argv varaible from command line
prefix prefix for all options

void parseCommandLine ( const int  argc,
const char **  argv,
const std::map< String, String > &  options_with_argument,
const std::map< String, String > &  options_without_argument,
const String misc = "misc",
const String unknown = "unknown" 
)

Parses command line arguments to specified key locations.

Parameters:
argc argc variable from command line
argv argv varaible from command line
options_with_argument a map of options that are followed by an 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). Present options are set to the the string 'true'.
misc key where all non-option arguments are stored
unknown key where all unknown options are stored

void store ( const String filename  )  const throw (Exception::UnableToCreateFile)

Write XML file.

void load ( const String filename  )  throw (Exception::FileNotFound,Exception::ParseError)

Read XML file.

ParamEntry& getEntry_ ( const String key  )  const throw (Exception::ElementNotFound<String>) [protected]

Returns a mutable reference to a parameter entry.


Member Data Documentation

Param::ParamNode root_ [mutable, protected]

Invisible root node that stores all the data.


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