OptionsFromStreamPack::OptionsFromStream Class Reference

Extracts options from a text stream and then allows convenient access to them. More...

#include <OptionsFromStreamPack_OptionsFromStream.hpp>

List of all members.

Public Types

typedef OptionsFromStreamUtilityPack::options_group_map_t::iterator iterator
 const iterator through options group access options
typedef OptionsFromStreamUtilityPack::options_group_map_t::const_iterator const_iterator
 non-const iterator through options group access options
typedef OptionsFromStreamUtilityPack::OptionsGroup options_group_t
 OptionsGroup} typedef

Constructors / Initializes.

The default constructor, copy constructor and assignment operator functions are allowed.

 OptionsFromStream ()
 Construct with no options set.
 OptionsFromStream (std::istream &in)
 Construct initialized from a text stream.
void clear_options ()
 Clear all the options.
void read_options (std::istream &in)
 Add / modify options read in from a text stream.

Get an options group access object given its name.

If the option group does not exist then\ options_group_exists( this->options_group( options_group_name ) ) == false\ where options_group_name is the string name of the option group.

options_group_t options_group (const std::string &options_group_name)
const options_group_t options_group (const std::string &options_group_name) const

Determine what options groups where not accessed.

The only the options groups accessed through the this->options_group(...) functions are maked as accessed. When the options groups are accessed through the iterator access, it is assumed that the client will not need this other information. Note that all of the flags are false by default.

void reset_unaccessed_options_groups ()
 Reset the flags to false for if the options groups was accessed.
void print_unaccessed_options_groups (std::ostream &out) const
 Print a list of options groups never accessed (accessed flag is falsed).

Iterator access to options groups.

int num_options_groups () const
iterator begin ()
iterator end ()
const_iterator begin () const
const_iterator end () const

Public Member Functions

void print_options (std::ostream &out) const
 Print the options to an output stream.

Static Public Member Functions

static bool options_group_exists (const options_group_t &options_group)


class  InputStreamError
 Thrown if there is an input error. More...

Detailed Description

Extracts options from a text stream and then allows convenient access to them.

The basic idea is that options are read in from a stream (which can be a file, C++ string etc.) and then parsed and stored in a format so that options can be efficiently looked up by client software.

The syntax for the file (or any C++ istream) is as follows:


  *** These are my solver options
  options_group MySolverOptions {
      tol       = 1e-5; *** Convergence tolerance
      max_iter  = 100;  *** Maximum number of iterations
      prob_type = LINEAR;
      *prob_type = NON_LINEAR;  *** Comment this line out

  *** Options for another solver
  options_group YourSolverOptions {
      tol       = 1e-4;
      *** These options determine the type of problem solved
  *    type_prob = LP;
      type_prob = QP;

  *** Reset the tolerance
  options_group MySolverOptions {
      tol = 1e-8; *** Reset to a tighter tolerance



The text stream will be read up to the end_options line. Options groups will be read starting with the begin_options line. Options groups can not be nested. The names for the option groups or the option names themselves can not contain any white space. The text for the option values however can contain white space. The = must separate each option from its value. The value for an option begins with the first non-whitespace character after the = and ends with the last non-whitespace character before the ;. For the option and value pair "tol = + 1e-5 ;" the option value would be stored as "+ 1e-5". Comment lines starting with * can be placed anywhere in the stream and will be ignored. Also comments starting with * after the ; for an option and value pair can occur on the same line as shown above.

Warning! Do not use the char '}' in any comment within an options group! This will break the parser.

The options groups are also reentrant which means that they may be included more than once as shown above. Therefore options may be set and reset in the same or another declaration of the options groups. In the above example, the second declaration of the options group declaration for OptionsGroup1 resets the value of OptionsGroup1::option1 from value1 to another_value. This feature provides much more flexibility in letting options be changed easily without having to edit the text stream before it is read in.

Now, what if the user misspells an options group name? One strategy is to require that the options group exist and then for the client to throw exceptions if the options group does not exist. However, where will be occasions where and options group may be "optional" and you don't want the user to have to specify every options group. Therefore we don't want to make all of the options groups mandatory. However, what if a user thinks he/she is setting options in an "optional" options group but misspells the name of the options group? In this case the options group would never be read by the client software and the user may be perplexed as to why nothing changed. To help deal with this problem, after all of the option groups have been accessed, the client can call the function print_unaccessed_options_groups(...) to print the list of options groups that have not been accessed. This way the user can see if they may have not spelled and "optional" options group correctly.

Careful use of this simple class for specifying and setting options has the following advantages/features:

Definition at line 407 of file OptionsFromStreamPack_OptionsFromStream.hpp.

Member Typedef Documentation

typedef OptionsFromStreamUtilityPack::options_group_map_t::iterator OptionsFromStreamPack::OptionsFromStream::iterator

const iterator through options group access options

Definition at line 414 of file OptionsFromStreamPack_OptionsFromStream.hpp.

typedef OptionsFromStreamUtilityPack::options_group_map_t::const_iterator OptionsFromStreamPack::OptionsFromStream::const_iterator

non-const iterator through options group access options

Definition at line 416 of file OptionsFromStreamPack_OptionsFromStream.hpp.

typedef OptionsFromStreamUtilityPack::OptionsGroup OptionsFromStreamPack::OptionsFromStream::options_group_t

OptionsGroup} typedef

Definition at line 419 of file OptionsFromStreamPack_OptionsFromStream.hpp.

Constructor & Destructor Documentation

OptionsFromStreamPack::OptionsFromStream::OptionsFromStream (  )  [inline]

Construct with no options set.

Definition at line 631 of file OptionsFromStreamPack_OptionsFromStream.hpp.

OptionsFromStreamPack::OptionsFromStream::OptionsFromStream ( std::istream &  in  )  [inline, explicit]

Construct initialized from a text stream.

This is equivalent to calling the default constructor and then calling read_options(in).

Definition at line 635 of file OptionsFromStreamPack_OptionsFromStream.hpp.

Member Function Documentation

void OptionsFromStreamPack::OptionsFromStream::clear_options (  )  [inline]

Clear all the options.

Definition at line 640 of file OptionsFromStreamPack_OptionsFromStream.hpp.

void OptionsFromStreamPack::OptionsFromStream::read_options ( std::istream &  in  ) 

Add / modify options read in from a text stream.

The format of the text stream is described in the introduction.

The options read in from in will either be added anew or will overwrite options already present.

If the format of the stream is not correct then a InputStreamError exception will be thrown.

Warning! Do not use the char '}' in any comment within an options group! This will break the parser.

Definition at line 113 of file OptionsFromStreamPack_OptionsFromStream.cpp.

void OptionsFromStreamPack::OptionsFromStream::print_options ( std::ostream &  out  )  const

Print the options to an output stream.

This is useful for debugging and also to record exactly what options have been set.

Definition at line 215 of file OptionsFromStreamPack_OptionsFromStream.cpp.

OptionsFromStream::options_group_t OptionsFromStreamPack::OptionsFromStream::options_group ( const std::string &  options_group_name  ) 

Definition at line 76 of file OptionsFromStreamPack_OptionsFromStream.cpp.

const OptionsFromStream::options_group_t OptionsFromStreamPack::OptionsFromStream::options_group ( const std::string &  options_group_name  )  const

Definition at line 87 of file OptionsFromStreamPack_OptionsFromStream.cpp.

bool OptionsFromStreamPack::OptionsFromStream::options_group_exists ( const options_group_t options_group  )  [inline, static]

Definition at line 645 of file OptionsFromStreamPack_OptionsFromStream.hpp.

void OptionsFromStreamPack::OptionsFromStream::reset_unaccessed_options_groups (  ) 

Reset the flags to false for if the options groups was accessed.

Definition at line 97 of file OptionsFromStreamPack_OptionsFromStream.cpp.

void OptionsFromStreamPack::OptionsFromStream::print_unaccessed_options_groups ( std::ostream &  out  )  const

Print a list of options groups never accessed (accessed flag is falsed).

Definition at line 104 of file OptionsFromStreamPack_OptionsFromStream.cpp.

int OptionsFromStreamPack::OptionsFromStream::num_options_groups (  )  const [inline]

Definition at line 651 of file OptionsFromStreamPack_OptionsFromStream.hpp.

OptionsFromStream::iterator OptionsFromStreamPack::OptionsFromStream::begin (  )  [inline]

Definition at line 656 of file OptionsFromStreamPack_OptionsFromStream.hpp.

OptionsFromStream::iterator OptionsFromStreamPack::OptionsFromStream::end (  )  [inline]

Definition at line 661 of file OptionsFromStreamPack_OptionsFromStream.hpp.

OptionsFromStream::const_iterator OptionsFromStreamPack::OptionsFromStream::begin (  )  const [inline]

Definition at line 666 of file OptionsFromStreamPack_OptionsFromStream.hpp.

OptionsFromStream::const_iterator OptionsFromStreamPack::OptionsFromStream::end (  )  const [inline]

Definition at line 671 of file OptionsFromStreamPack_OptionsFromStream.hpp.

The documentation for this class was generated from the following files:
Generated on Tue Jul 13 09:28:35 2010 for MoochoPack: Miscellaneous Utilities for MOOCHO by  doxygen 1.4.7