A class for handling command line specified options. More...

#include <common/user_options/user_options.h>

Public Member Functions
void	show_hidden ()
	A method for showing all options.
	UserOptions (string message)
	Class constructor.
template<typename Type >
void	add_option (string handle, string message)
	Function for adding a new command-line option, without a default.
template<typename Type >
void	add_option (string handle, Type dvalue, string message)
	Function for adding a new command-line option, with a default.
template<typename Type >
void	add_option (string handle, Type dvalue, string message, string dtext)
	Function for adding a new command-line option, with a default and default text.
template<typename Type >
void	add_option (string handle, string message, int pos)
	Function for adding a new command-line option, without a default but with a positional argument.
template<typename Type >
void	add_option (string handle, Type dvalue, string message, int pos)
	Function for adding a new command-line option, with a default and with a positional argument.
bool	exist (string handle)
	Tests for the existance of an option.
template<typename Type >
Type	get (string handle)
	Function for returning a command-line specified option.
void	add_flag (string flag, string message)
	Function for adding a flag (no associated value) options.
bool	get_flag (string flag)
	Function for testing if an flag was supplied on the command-line.
void	apply_options (int argc, char *argv[])
	Function for collecting and applying command-line inputs.
UserOptions &	add (UserOptions &new_opt)
	A function for grouping UserOptions together.
void	add_title (string str)
	Allows user to add title text that prints with --help.
Public Attributes
bool	hidden
	A flag for hidding the options associated with this class.
opt::options_description	opt_list
	Boost::program_options::options description class associated with this UserOptions instance.
opt::variables_map	opt_map
	Boost::program_options::variables_map class associated with this UserOptions instance.

Detailed Description

A class for handling command line specified options.

This class is basically a wrapper for the Boost.Program_options library. As such, the syntax for this class was designed to be somewhat similar to the Boost libraries.

The example program detailed in Using the UserOptions Class has extensive documentation for this class including. The resulting executable allows the user to test the various features.

The functionality of the Boost.Program_options is not restrained in anyway. It is possible to work directly with the Boost classes and this class. The members opt_list and opt_map may be used as shown in the Boost documentation they represent the boost::program_options::options_description and boost::program_options::variables_map classes, respectively.

Special Behavior:
The option "config", if added, is automatically considered to contain the name of a configuration file that contains program options. This options must use the string type. The options in the coinfiguration file are always overwritten by those on the command line. The following code demonstrates this behavior.

 UserOptions opt("General Options");
 opt.add_option<string>("config", "default.cfg", "Configuration file name");

The options "help", if added with the add_flag function, will cause the program to automatically exit after displaying all of the available user options. See the documentation for add_flag for more details.

Grouping is accomplished using the add member function. Example code for creating groups are provided in the class documentation. It is possible to hide groups, just set the hidden attribute to false. Note, the master class (the one to which all the add commands are linked) will always display its options, only classes that are attached can be hidden.

Examples:: fem/examples/example2.cpp, and test_user_options.cpp.

Constructor & Destructor Documentation

UserOptions::UserOptions ( string message )

Class constructor.

This constrcutor requires a single argument, the message that will be displayed when the command-line options are displayed on the screen.

Parameters:

message A std::string containing the desired message.

Example Syntax:

 UserOptions opt("Available options");

Member Function Documentation

UserOptions & UserOptions::add ( UserOptions & new_opt )

A function for grouping UserOptions together.

It is possible to seperate user options into groups, as shown in the Boost.Program_options documentation. This can also be done with the UserOptions class in a similar fashion by creating several instances of the UserOptions class.

Parameters:

new_opt

The instance of a UserOptions that should be added to the calling class, the class inputed here is considered then to be a slave class to the calling class. Slave classes have the following members are disabled:

apply_options

 UserOptions opt("General Options");
 opt.add_help("help,h", "Display the available options");
 opt.add_option<double>("angle,a", 35, "Interface angle");
 
 UserOptions opt2("Advanced Options");
 opt2.add_options<int>("advanced",0, "Use advanced options");
 opt.add(opt2);
 opt.apply_options(argc, argv);

Examples:: fem/examples/example2.cpp, and test_user_options.cpp.

void UserOptions::add_flag	(	string	flag,
		string	message
	)

Function for adding a flag (no associated value) options.

Parameters:

flag	Text to use for accessing help, e.g., "help,h"
message	associated with the flag option

Example Syntax:

 UserOptions opt("Available options");
 opt.add_help("help,h", "Show all available options.");

A flag does not contain any other input, just the command itself (e.g., --help or --verbose).

A true|false value is returned from the get_flag() function if the options is specified.

Note, "help" is a special case. When this options is given it automatically lists the various command-line options and stops execution of the program.

Examples:: fem/examples/example2.cpp, and test_user_options.cpp.

template<typename Type >

void SlaughterCommon::UserOptions::add_option	(	string	handle,
		string	message
	)		`[inline]`

Function for adding a new command-line option, without a default.

Template Parameters:

Type	The type of variable desired, e.g., `double`

Parameters:

handle	The text reference to the added option, uses the same syntax as Boost
message	A description of the option

Example Syntax:

 UserOptions opt("Available options");
 opt.add_option<double>("angle,a", 35, "Interface angle");

Examples:: test_user_options.cpp.

template<typename Type >

void SlaughterCommon::UserOptions::add_option	(	string	handle,
		Type	dvalue,
		string	message
	)		`[inline]`

Function for adding a new command-line option, with a default.

Template Parameters:

Type	The type of variable desired, e.g., `double`

Parameters:

handle	The text reference to the added option, uses the same syntax as Boost
dvalue	The default value of the same Type
message	A description of the option

Example Syntax:

 UserOptions opt("Available options");
 opt.add_option<double>("angle,a", 35, "Interface angle");

template<typename Type >

void SlaughterCommon::UserOptions::add_option	(	string	handle,
		Type	dvalue,
		string	message,
		string	dtext
	)		`[inline]`

Function for adding a new command-line option, with a default and default text.

Template Parameters:

Type	The type of variable desired, e.g., `double`

Parameters:

handle	The text reference to the added option, uses the same syntax as Boost
dvalue	The default value of the same Type
message	A description of the option
dtext	A string containing the default text to display; useful when ouputing a vector

Example Syntax:

 UserOptions opt("Available options");
 std::vector vec;
 vec.push_back(35);
 vec.push_back(50);
 opt.add_option<std::<double> >("angle,a", vec, "Interface angle", "[35,50]");

template<typename Type >

void SlaughterCommon::UserOptions::add_option	(	string	handle,
		string	message,
		int	pos
	)		`[inline]`

Function for adding a new command-line option, without a default but with a positional argument.

Template Parameters:

Type	The type of variable desired, e.g., `double`

Parameters:

handle	The text reference to the added option, uses the same syntax as Boost
message	A description of the option
pos	Positional specification, refer to Boost.Program_options documentation for more information.

Example Syntax:

 UserOptions opt("Available options");
 opt.add_option<string>("input,i", "Input file name", 1);

template<typename Type >

void SlaughterCommon::UserOptions::add_option	(	string	handle,
		Type	dvalue,
		string	message,
		int	pos
	)		`[inline]`

Function for adding a new command-line option, with a default and with a positional argument.

Template Parameters:

Type	The type of variable desired, e.g., `double`

Parameters:

handle	The text reference to the added option, uses the same syntax as Boost
dvalue	The default value of the same Type
message	A description of the option
pos	Positional specification, refer to Boost.Program_options documentation for more information.

Example Syntax:

 UserOptions opt("Available options");
 opt.add_option<string>("input,i", "default.txt", "Input file name", 1);

void UserOptions::add_title ( string str )

Allows user to add title text that prints with --help.

Parameters:

str	A string contiaing the text to display.

 UserOptions opt("Available Options");
 opt.add_title("\nThis is my wonderful program.\n\nCopyright 2012\n");
 opt.add_flag("help","Display the available options");
 opt.add_option("input","The input file name");
 opt.apply_options(argc, argv);

Examples:: fem/examples/example2.cpp, and test_user_options.cpp.

void UserOptions::apply_options	(	int	argc,
		char *	argv[]
	)

Function for collecting and applying command-line inputs.

This function should be the last to be called, as shown in the example.

Parameters:

argc	Number of command-line inputs, from `main`
argv	Character array storing the inputs, from `main`

Example Syntax:

 UserOptions opt("Available options");
 opt.add_option<string>("input,i", "default.txt", "Input file name", 1);
 opt.apply_options(argc, argv);
 std::string filename = opt.get<string>("input");

Examples:: fem/examples/example2.cpp, and test_user_options.cpp.

bool UserOptions::exist ( string handle )

Tests for the existance of an option.

Allows the user to test if an option contains a value, which may not be the case for an option that is specified without a default value.

Examples:: test_user_options.cpp.

template<typename Type >

Type SlaughterCommon::UserOptions::get ( string handle ) [inline]

Function for returning a command-line specified option.

This allows the users to extract the default value or the user specified value from the command line. Note, that the apply_options member function must be called prior to using this function.

Template Parameters:

Type	The type of variable, e.g., `double`

Parameters:

handle The text reference to the options, do not include the short-hand value.

Example Syntax:

 UserOptions opt("Available options");
 opt.add_option<string>("input,i", "default.txt", "Input file name", 1);
 opt.apply_options(argc, argv);
 std::string filename = opt.get<string>("input");

Examples:: fem/examples/example2.cpp, and test_user_options.cpp.

bool UserOptions::get_flag ( string flag )

Function for testing if an flag was supplied on the command-line.

Parameters:

flag	Text to use for accessing flag value, e.g., "help"

Examples:: fem/examples/example2.cpp, and test_user_options.cpp.

void UserOptions::show_hidden ( )

A method for showing all options.

This function exists to allow for a --advanced type flag that will display all the options. This must be called after the apply_option member is called.

See also:: v2m.cpp

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

include/common/user_options/user_options.h
source/common/user_options/user_options.cpp

Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation