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

#include <OptionsFromStreamPack_OptionsFromStream.hpp>

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

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

Static Public Member Functions
static bool	options_group_exists (const options_group_t &options_group)

Public Types
typedef OptionsFromStreamUtilityPack::options_group_map_t::iterator	iterator
	const iterator through options group access options More...

typedef OptionsFromStreamUtilityPack::options_group_map_t::const_iterator	const_iterator
	non-const iterator through options group access options More...

typedef OptionsFromStreamUtilityPack::OptionsGroup	options_group_t
	{OptionsGroup} typedef More...

Constructors / Initializes.
The default constructor, copy constructor and assignment operator functions are allowed.
	OptionsFromStream ()
	Construct with no options set. More...

	OptionsFromStream (std::istream &in)
	Construct initialized from a text stream. More...

void	clear_options ()
	Clear all the options. More...

void	read_options (std::istream &in)
	Add / modify options read in from a text stream. More...

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

void	print_unaccessed_options_groups (std::ostream &out) const
	Print a list of options groups never accessed (accessed flag is falsed). More...

Iterator access to options groups.
int	num_options_groups () const

iterator	begin ()

iterator	end ()

const_iterator	begin () const

const_iterator	end () const

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:

begin_options

*** 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
}

end_options

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:

Options are read from a stream, not a file, and can therefore represent any kind of source (C++ strings, files, console etc.).
Options are inclosed in namespaces (called options_group) and therefore can handle options from many different sources.
An OptionsFromStream object can be passed around in a software application and interested sub-objects can search for 'their' options group and can pull out options that apply to them.
Reasonable mechanisms are available to validate that users have spelled the names of options groups and their options names or the allowable value of the option values properly.
The implementation is very light weight and uses very little code. Most of the major functionality comes from the ISO standard C++ library and therefore should be portable to any up to date C++ compiler.

Definition at line 422 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 429 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 431 of file OptionsFromStreamPack_OptionsFromStream.hpp.

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

{OptionsGroup} typedef

Definition at line 434 of file OptionsFromStreamPack_OptionsFromStream.hpp.

Constructor & Destructor Documentation

OptionsFromStreamPack::OptionsFromStream::OptionsFromStream ( )

inline

Construct with no options set.

Definition at line 641 of file OptionsFromStreamPack_OptionsFromStream.hpp.

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

inlineexplicit

Construct initialized from a text stream.

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

Definition at line 645 of file OptionsFromStreamPack_OptionsFromStream.hpp.

Member Function Documentation

void OptionsFromStreamPack::OptionsFromStream::clear_options ( )

inline

Clear all the options.

Definition at line 650 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 126 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 228 of file OptionsFromStreamPack_OptionsFromStream.cpp.

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

Definition at line 89 of file OptionsFromStreamPack_OptionsFromStream.cpp.

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

Definition at line 100 of file OptionsFromStreamPack_OptionsFromStream.cpp.

bool OptionsFromStreamPack::OptionsFromStream::options_group_exists ( const options_group_t & options_group )

inlinestatic

Definition at line 655 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 110 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 117 of file OptionsFromStreamPack_OptionsFromStream.cpp.

int OptionsFromStreamPack::OptionsFromStream::num_options_groups ( ) const

inline

Definition at line 661 of file OptionsFromStreamPack_OptionsFromStream.hpp.

OptionsFromStream::iterator OptionsFromStreamPack::OptionsFromStream::begin ( )

inline

Definition at line 666 of file OptionsFromStreamPack_OptionsFromStream.hpp.

OptionsFromStream::iterator OptionsFromStreamPack::OptionsFromStream::end ( )

inline

Definition at line 671 of file OptionsFromStreamPack_OptionsFromStream.hpp.

OptionsFromStream::const_iterator OptionsFromStreamPack::OptionsFromStream::begin ( ) const

inline

Definition at line 676 of file OptionsFromStreamPack_OptionsFromStream.hpp.

OptionsFromStream::const_iterator OptionsFromStreamPack::OptionsFromStream::end ( ) const

inline

Definition at line 681 of file OptionsFromStreamPack_OptionsFromStream.hpp.

The documentation for this class was generated from the following files:

Classes

Public Member Functions

Static Public Member Functions

Public Types

Constructors / Initializes.

Get an options group access object given its name.

Determine what options groups where not accessed.

Iterator access to options groups.

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation