ProgramOptions Namespace Reference

Namespaces
namespace	detail
Classes
class	AmbiguousOption
class	Application
struct	bad_value_cast
class	ContextError
	Used for signaling errors in OptionContext. More...
class	CustomValue
struct	DefaultCreator
struct	DefaultFormat
	Default formatting for options. More...
class	DuplicateOption
class	Error
	Base class for all exceptions. More...
struct	FileWriter
	Writes formatted option descriptions to a FILE. More...
struct	FlagAction
class	NotifiedValue
class	Option
	Represents one program option. More...
class	OptionContext
	A (logically grouped) list of unique options. More...
class	OptionGroup
	A list of options logically grouped under a caption. More...
class	OptionInitHelper
class	OptionOutput
	Base class for printing options. More...
class	OptionOutputImpl
	Implementation class for printing options. More...
class	OptionParser
	Base class for options parsers. More...
struct	OstreamWriter
	Writes formatted option descriptions to an std::ostream. More...
class	ParseContext
class	ParsedOptions
	Set of options holding a parsed value. More...
class	ParsedValues
class	StoredValue
struct	StringWriter
	Writes formatted option descriptions to an std::string. More...
class	SyntaxError
	Used for signaling errors on command-line and in declaring options. More...
class	UnknownOption
class	Value
	Manages the value of an option and defines how it is parsed from a string. More...
class	ValueError
	Used for signaling validation errors when trying to assign option values. More...
class	ValueMap
struct	ValueMapping
struct	ValueMappingBase
class	ValueStore
	A type that can hold any kind of value type. More...
Typedefs
typedef OptionOutputImpl < FileWriter >	FileOut
typedef bool(*	PosOption )(const std::string &, std::string &)
typedef detail::IntrusiveSharedPtr < Option >	SharedOptPtr
typedef OptionOutputImpl < OstreamWriter >	StreamOut
typedef OptionOutputImpl < StringWriter >	StringOut
typedef std::vector< std::string >	StringSeq
Enumerations
enum	CommandLineFlags { command_line_allow_flag_value = 1u }
enum	DescriptionLevel {   desc_level_default = 0, desc_level_e1 = 1, desc_level_e2 = 2, desc_level_e3 = 3,   desc_level_all = 4, desc_level_hidden = 5 }
Functions
NotifiedValue< bool > *	flag (ValueMap &map, FlagAction a=store_true)
StoredValue< bool > *	flag (bool &b, FlagAction x=store_true)
template<class ParamT >
NotifiedValue< bool > *	flag (ParamT *p0, typename detail::Notify< const bool *, ParamT >::type nf, FlagAction a=store_true)
static std::string	format (SyntaxError::Type t, const std::string &key)
static std::string	format (ContextError::Type t, const std::string &ctx, const std::string &key, const std::string &alt)
static std::string	format (ValueError::Type t, const std::string &ctx, const std::string &key, const std::string &value)
template<class T , class ParamT >
NotifiedValue< T > *	notify (ParamT *p0, typename detail::Notify< const T *, ParamT >::type nf, typename detail::Parser< T >::type parser=&string_cast< T >)
template<class ParamT >
CustomValue *	notify (ParamT *p0, typename detail::Notify< const std::string &, ParamT >::type nf)
std::ostream &	operator<< (std::ostream &os, const OptionContext &grp)
ParsedValues	parseCfgFile (std::istream &is, const OptionContext &o, bool allowUnregistered)
ParsedValues	parseCommandLine (int &argc, char **argv, const OptionContext &ctx, bool allowUnregistered=true, PosOption posParser=0, unsigned flags=0)
ParseContext &	parseCommandLine (int &argc, char **argv, ParseContext &ctx, unsigned flags=0)
ParsedValues	parseCommandString (const std::string &cmd, const OptionContext &ctx, bool allowUnreg=false, PosOption posParser=0, unsigned flags=command_line_allow_flag_value)
ParseContext &	parseCommandString (const char *cmd, ParseContext &ctx, unsigned flags=command_line_allow_flag_value)
static std::string	quote (const std::string &x)
template<class T >
NotifiedValue< T > *	store (ValueMap &map, typename detail::Parser< T >::type p=&string_cast< T >)
static const FlagAction	store_false ((FlagAction::act_store_false))
static const FlagAction	store_true ((FlagAction::act_store_true))
template<class T , class ParamT >
NotifiedValue< T > *	storeNotify (T &obj, ParamT *p0, typename detail::Notify< const T *, ParamT >::type nf, typename detail::Parser< T >::type parser=&string_cast< T >)
template<class T >
StoredValue< T > *	storeTo (T &v, typename detail::Parser< T >::type p=&string_cast< T >)
template<class T >
const T *	unsafe_value_cast (const ValueStore *v, const T *=0)
	Extracts a typed value from a ValueStore *without* checking if the type matches.
template<class T >
T *	unsafe_value_cast (ValueStore *v, const T *p=0)
template<class T >
const T &	value_cast (const ValueStore &v, const T *=0)
	Extracts a typed value from a ValueStore.
template<class T >
const T *	value_cast (const ValueStore *v, const T *=0)
	Returns 0 on error.
template<class T >
T &	value_cast (ValueStore &v, const T *p=0)
template<class T >
T *	value_cast (ValueStore *v, const T *p=0)
template<class T >
ValueMapping< T > &	values ()

---

Typedef Documentation

typedef OptionOutputImpl<FileWriter> ProgramOptions::FileOut

Definition at line 442 of file program_options.h.

typedef bool(* ProgramOptions::PosOption)(const std::string &, std::string &)

A function type that is used by parsers for processing tokens that have no option name. Concrete functions shall either return true and store the name of the option that should receive the token as value in its second argument or return false to signal an error.

Definition at line 452 of file program_options.h.

typedef detail::IntrusiveSharedPtr<Option> ProgramOptions::SharedOptPtr

Definition at line 74 of file program_options.h.

typedef OptionOutputImpl<OstreamWriter> ProgramOptions::StreamOut

Definition at line 440 of file program_options.h.

typedef OptionOutputImpl<StringWriter> ProgramOptions::StringOut

Definition at line 441 of file program_options.h.

typedef std::vector<std::string> ProgramOptions::StringSeq

Definition at line 37 of file application.h.

---

Enumeration Type Documentation

enum ProgramOptions::CommandLineFlags

Enumerator:

command_line_allow_flag_value

Definition at line 454 of file program_options.h.

enum ProgramOptions::DescriptionLevel

Enumerator:

desc_level_default	Always shown in description
desc_level_e1
desc_level_e2
desc_level_e3
desc_level_all
desc_level_hidden	Never shown in description

Definition at line 38 of file value.h.

---

Function Documentation

NotifiedValue<bool>* ProgramOptions::flag	(	ValueMap &	map,
		FlagAction	a = store_true
	)		[inline]

Definition at line 88 of file mapped_value.h.

StoredValue<bool>* ProgramOptions::flag	(	bool &	b,
		FlagAction	x = store_true
	)		[inline]

Definition at line 193 of file typed_value.h.

template<class ParamT >

NotifiedValue<bool>* ProgramOptions::flag	(	ParamT *	p0,
		typename detail::Notify< const bool *, ParamT >::type	nf,
		FlagAction	a = store_true
	)		[inline]

Definition at line 224 of file typed_value.h.

static std::string ProgramOptions::format	(	SyntaxError::Type	t,
		const std::string &	key
	)		[static]

Definition at line 891 of file program_options.cpp.

static std::string ProgramOptions::format	(	ContextError::Type	t,
		const std::string &	ctx,
		const std::string &	key,
		const std::string &	alt
	)		[static]

Definition at line 902 of file program_options.cpp.

static std::string ProgramOptions::format	(	ValueError::Type	t,
		const std::string &	ctx,
		const std::string &	key,
		const std::string &	value
	)		[static]

Definition at line 919 of file program_options.cpp.

template<class T , class ParamT >

NotifiedValue<T>* ProgramOptions::notify	(	ParamT *	p0,
		typename detail::Notify< const T *, ParamT >::type	nf,
		typename detail::Parser< T >::type	parser = &string_cast<T>
	)		[inline]

Creates a notified value, i.e. a value for which a notification function is called once it was parsed. The return value of that function determines whether the value is kept (true) or deleted (false). In the former case ownership of the value is transferred to the notified context.

Parameters:

p0	A pointer to an object that should be passed to the notification function once invoked.
nf	The function to be invoked once a value is created. On invocation, the first parameter will be p0. The second parameter will be the value's option name and the third the location of the newly created value.
parser	The parser to use for parsing the value

See also:

OptionGroup::addOptions()

Definition at line 216 of file typed_value.h.

template<class ParamT >

CustomValue* ProgramOptions::notify	(	ParamT *	p0,
		typename detail::Notify< const std::string &, ParamT >::type	nf
	)		[inline]

Creates a custom value, i.e. a value that is fully controlled (parsed and created) by a notified context.

During parsing of options, the notification function of a custom value is called with its option name and the parsed value. The return value of that function determines whether the value is considered valid (true) or invalid (false).

Parameters:

p0	A pointer to an object that should be passed to the notification function once invoked.
nf	The function to be invoked once a value is parsed. On invocation, the first parameter will be p0. The second parameter will be the value's option name and the third a pointer to the parsed value string.

See also:

OptionGroup::addOptions()

Definition at line 247 of file typed_value.h.

std::ostream& ProgramOptions::operator<<	(	std::ostream &	os,
		const OptionContext &	grp
	)

Definition at line 476 of file program_options.cpp.

ParsedValues ProgramOptions::parseCfgFile	(	std::istream &	is,
		const OptionContext &	o,
		bool	allowUnregistered
	)

Parses a config file having the format key = value.

Parameters:

is	the stream representing the config file
o	options to search in the config file
allowUnregistered	Allow arguments that match no option in ctx

Returns:

A ParsedOptions-Object containing names and values for all options found.

Exceptions:

SyntaxError	if command line syntax is incorrect.
UnknownOption	if an argument is found that does not match any option.

Note:

Keys are option's long names.

Lines starting with # are treated as comments and are ignored.

Definition at line 880 of file program_options.cpp.

ParsedValues ProgramOptions::parseCommandLine	(	int &	argc,
		char **	argv,
		const OptionContext &	ctx,
		bool	allowUnregistered = true,
		PosOption	posParser = 0,
		unsigned	flags = 0
	)

Parses the command line starting at index 1 and removes all found options from argv.

Parameters:

argc	nr of arguments in argv
argv	the command line arguments
ctx	options to search in the command line.
allowUnregistered	Allow arguments that match no option in ctx
posParser	parse function for positional options

Returns:

A ParsedOptions-Object containing names and values for all options found.

Exceptions:

SyntaxError	if command line syntax is incorrect.
UnknownOption	if allowUnregistered is false and an argument is found that does not match any option.

Definition at line 858 of file program_options.cpp.

ParseContext & ProgramOptions::parseCommandLine	(	int &	argc,
		char **	argv,
		ParseContext &	ctx,
		unsigned	flags = 0
	)

Definition at line 862 of file program_options.cpp.

ParsedValues ProgramOptions::parseCommandString	(	const std::string &	cmd,
		const OptionContext &	ctx,
		bool	allowUnreg = false,
		PosOption	posParser = 0,
		unsigned	flags = command_line_allow_flag_value
	)

Parses the command line given in the first parameter.

Parameters:

cmd	command line to parse
ctx	options to search in the command string.
allowUnregistered	Allow arguments that match no option in ctx
posParser	parse function for positional options

Returns:

A ParsedOptions-Object containing names and values for all options found.

Exceptions:

SyntaxError	if command line syntax is incorrect.
UnknownOption	if an argument is found that does not match any option.

Definition at line 875 of file program_options.cpp.

ParseContext & ProgramOptions::parseCommandString	(	const char *	cmd,
		ParseContext &	ctx,
		unsigned	flags = command_line_allow_flag_value
	)

Definition at line 872 of file program_options.cpp.

static std::string ProgramOptions::quote

(

const std::string &

x

)

[static]

Definition at line 888 of file program_options.cpp.

template<class T >

NotifiedValue<T>* ProgramOptions::store	(	ValueMap &	map,
		typename detail::Parser< T >::type	p = &string_cast<T>
	)		[inline]

Creates a value that is created on demand and stored in a given value map.

See also:

OptionGroup::addOptions()

Definition at line 84 of file mapped_value.h.

static const FlagAction ProgramOptions::store_false

(

(FlagAction::act_store_false)

)

[static]

static const FlagAction ProgramOptions::store_true

(

(FlagAction::act_store_true)

)

[static]

template<class T , class ParamT >

NotifiedValue<T>* ProgramOptions::storeNotify	(	T &	obj,
		ParamT *	p0,
		typename detail::Notify< const T *, ParamT >::type	nf,
		typename detail::Parser< T >::type	parser = &string_cast<T>
	)		[inline]

Definition at line 220 of file typed_value.h.

template<class T >

StoredValue<T>* ProgramOptions::storeTo	(	T &	v,
		typename detail::Parser< T >::type	p = &string_cast<T>
	)		[inline]

Creates a value that is bound to an existing variable. Assignments to the created value are directly stored in the given variable.

Parameters:

v	The variable to which the new value object is bound
p	The parser to use for parsing the value. If no parser is given, type T must provide an operator>>(std::istream&, T&).

Definition at line 190 of file typed_value.h.

template<class T >

const T* ProgramOptions::unsafe_value_cast	(	const ValueStore *	v,
		const T *	= 0
	)

Extracts a typed value from a ValueStore *without* checking if the type matches.

Definition at line 139 of file value_store.h.

template<class T >

T* ProgramOptions::unsafe_value_cast	(	ValueStore *	v,
		const T *	p = 0
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 146 of file value_store.h.

template<class T >

const T& ProgramOptions::value_cast	(	const ValueStore &	v,
		const T *	= 0
	)

Extracts a typed value from a ValueStore.

Exceptions:

bad_value_cast

if value is not of type T

Definition at line 111 of file value_store.h.

template<class T >

const T* ProgramOptions::value_cast	(	const ValueStore *	v,
		const T *	= 0
	)

Returns 0 on error.

Definition at line 119 of file value_store.h.

template<class T >

T& ProgramOptions::value_cast	(	ValueStore &	v,
		const T *	p = 0
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 129 of file value_store.h.

template<class T >

T* ProgramOptions::value_cast	(	ValueStore *	v,
		const T *	p = 0
	)

Definition at line 133 of file value_store.h.

template<class T >

ValueMapping<T>& ProgramOptions::values

(

)

Definition at line 72 of file typed_value.h.