Detailed Description

Command line parser which automatically fills variables and prints nice usage messages.

This is a straightforward command line parser in C++, which will recognize short options -s, long options –long and parameters, both required and optional. It will automatically parse integers and byte sizes with SI/IEC suffixes (e.g. 1 GiB). It also works with lists of strings, e.g. multiple filenames.

Maybe most important it will nicely format the options and parameters description using word wrapping.

Examples:: examples/applications/skew3.cpp, and examples/common/cmdline.cpp.

Definition at line 45 of file cmdline.h.

Inheritance diagram for stxxl::cmdline_parser:

Collaboration diagram for stxxl::cmdline_parser:

Classes
struct	argument
	base class of all options and parameters More...

struct	argument_bytes32
	specialization of argument for SI/IEC suffixes byte size options or parameters More...

struct	argument_bytes64
	specialization of argument for SI/IEC suffixes byte size options or parameters More...

struct	argument_double
	specialization of argument for double options or parameters More...

struct	argument_flag
	specialization of argument for boolean flags (can only be set to true). More...

struct	argument_int
	specialization of argument for integer options or parameters More...

struct	argument_string
	specialization of argument for string options or parameters More...

struct	argument_stringlist
	specialization of argument for multiple string options or parameters More...

struct	argument_uint
	specialization of argument for unsigned integer options or parameters More...

Public Member Functions
	cmdline_parser ()
	Construct new command line parser. More...

	~cmdline_parser ()
	Delete all added arguments. More...

void	add_bytes (char key, const std::string &longkey, const std::string &keytype, stxxl::uint32 &dest, const std::string &desc)
	add SI/IEC suffixes byte size option -key, –longkey [keytype] and store to 64-bit dest More...

void	add_bytes (char key, const std::string &longkey, const std::string &keytype, stxxl::uint64 &dest, const std::string &desc)
	add SI/IEC suffixes byte size option -key, –longkey [keytype] and store to 64-bit dest More...

void	add_bytes (char key, const std::string &longkey, stxxl::uint32 &dest, const std::string &desc)
	add SI/IEC suffixes byte size option -key, –longkey [keytype] and store to 32-bit dest More...

void	add_bytes (char key, const std::string &longkey, stxxl::uint64 &dest, const std::string &desc)
	add SI/IEC suffixes byte size option -key, –longkey [keytype] and store to 64-bit dest More...

void	add_double (char key, const std::string &longkey, const std::string &keytype, double &dest, const std::string &desc)
	add double option -key, –longkey [keytype] with description and store to dest More...

void	add_double (char key, const std::string &longkey, double &dest, const std::string &desc)
	add double option -key, –longkey [keytype] with description and store to dest More...

void	add_flag (char key, const std::string &longkey, const std::string &keytype, bool &dest, const std::string &desc)
	add boolean option flag -key, –longkey [keytype] with description and store to dest More...

void	add_flag (char key, const std::string &longkey, bool &dest, const std::string &desc)
	add boolean option flag -key, –longkey with description and store to dest More...

void	add_int (char key, const std::string &longkey, const std::string &keytype, int &dest, const std::string &desc)
	add signed integer option -key, –longkey [keytype] with description and store to dest More...

void	add_int (char key, const std::string &longkey, int &dest, const std::string &desc)
	add signed integer option -key, –longkey with description and store to dest More...

void	add_opt_param_bytes (const std::string &name, uint32 &dest, const std::string &desc)
	add optional SI/IEC suffixes byte size parameter [name] with description and store to dest More...

void	add_opt_param_bytes (const std::string &name, uint64 &dest, const std::string &desc)
	add optional SI/IEC suffixes byte size parameter [name] with description and store to dest More...

void	add_opt_param_double (const std::string &name, double &dest, const std::string &desc)
	add optional double parameter [name] with description and store to dest More...

void	add_opt_param_int (const std::string &name, int &dest, const std::string &desc)
	add optional signed integer parameter [name] with description and store to dest More...

void	add_opt_param_string (const std::string &name, std::string &dest, const std::string &desc)
	add optional string parameter [name] with description and store to dest More...

void	add_opt_param_stringlist (const std::string &name, std::vector< std::string > &dest, const std::string &desc)
	add optional string parameter [name] with description and store to dest More...

void	add_opt_param_uint (const std::string &name, unsigned int &dest, const std::string &desc)
	add optional unsigned integer parameter [name] with description and store to dest More...

void	add_param_bytes (const std::string &name, uint32 &dest, const std::string &desc)
	add SI/IEC suffixes byte size parameter [name] with description and store to dest More...

void	add_param_bytes (const std::string &name, uint64 &dest, const std::string &desc)
	add SI/IEC suffixes byte size parameter [name] with description and store to dest More...

void	add_param_double (const std::string &name, double &dest, const std::string &desc)
	add double parameter [name] with description and store to dest More...

void	add_param_int (const std::string &name, int &dest, const std::string &desc)
	add signed integer parameter [name] with description and store to dest More...

void	add_param_string (const std::string &name, std::string &dest, const std::string &desc)
	add string parameter [name] with description and store to dest More...

void	add_param_stringlist (const std::string &name, std::vector< std::string > &dest, const std::string &desc)
	add string list parameter [name] with description and store to dest. More...

void	add_param_uint (const std::string &name, unsigned int &dest, const std::string &desc)
	add unsigned integer parameter [name] with description and store to dest More...

void	add_string (char key, const std::string &longkey, const std::string &keytype, std::string &dest, const std::string &desc)
	add string option -key, –longkey [keytype] and store to dest More...

void	add_string (char key, const std::string &longkey, std::string &dest, const std::string &desc)
	add string option -key, –longkey [keytype] and store to dest More...

void	add_stringlist (char key, const std::string &longkey, const std::string &keytype, std::vector< std::string > &dest, const std::string &desc)
	add string list option -key, –longkey [keytype] and store to dest More...

void	add_stringlist (char key, const std::string &longkey, std::vector< std::string > &dest, const std::string &desc)
	add string list option -key, –longkey [keytype] and store to dest More...

void	add_uint (char key, const std::string &longkey, const std::string &keytype, unsigned int &dest, const std::string &desc)
	add unsigned integer option -key, –longkey [keytype] with description and store to dest More...

void	add_uint (char key, const std::string &longkey, unsigned int &dest, const std::string &desc)
	add unsigned integer option -key, –longkey [keytype] with description and store to dest More...

void	print_result (std::ostream &os=std::cout)
	print nicely formatted result of processing More...

void	print_usage (std::ostream &os=std::cout)
	output nicely formatted usage information including description of all parameters and options. More...

bool	process (int argc, const char const argv, std::ostream &os=std::cout)
	parse command line options as specified by the options and parameters added. More...

void	set_author (const std::string &author)
	Set author of program, will be wrapped. More...

void	set_description (const std::string &description)
	Set description of program, text will be wrapped. More...

void	set_verbose_process (bool verbose_process)
	Set verbose processing of command line arguments. More...

Static Public Member Functions
static void	output_wrap (std::ostream &os, const std::string &text, size_t wraplen, size_t indent_first=0, size_t indent_rest=0, size_t current=0, size_t indent_newline=0)
	Wrap a long string at spaces into lines. Prefix is added unconditionally to each line. Lines are wrapped after wraplen characters if possible. More...

Protected Types
typedef std::vector< argument * >	arglist_type
	option and parameter list type More...

Protected Attributes
std::string	m_author
	user set author of program, will be wrapped More...

std::string	m_description
	user set description of program, will be wrapped More...

unsigned int	m_linewrap
	set line wrap length More...

int	m_opt_maxlong
	formatting width for options, '-s, –switch <#>' More...

arglist_type	m_optlist
	list of options available More...

int	m_param_maxlong
	formatting width for parameters, 'param <#>' More...

arglist_type	m_paramlist
	list of parameters, both required and optional More...

const char *	m_progname
	argv[0] for usage. More...

bool	m_verbose_process
	verbose processing of arguments More...

Static Protected Attributes
static const int	m_maxtypename = 16
	maximum length of a type_name() result More...

Private Member Functions
void	calc_opt_max (const argument *arg)
	update maximum formatting width for new option More...

void	calc_param_max (const argument *arg)
	update maximum formatting width for new parameter More...

void	print_option_error (int argc, const char const argv, const argument *arg, std::ostream &os)
	print error about option. More...

void	print_param_error (int argc, const char const argv, const argument *arg, std::ostream &os)
	print error about parameter. More...

Private Member Functions inherited from stxxl::noncopyable
	noncopyable ()

Member Typedef Documentation

typedef std::vector<argument*> stxxl::cmdline_parser::arglist_type

protected

option and parameter list type

Definition at line 386 of file cmdline.h.

Constructor & Destructor Documentation

stxxl::cmdline_parser::cmdline_parser ( )

inline

Construct new command line parser.

Definition at line 441 of file cmdline.h.

stxxl::cmdline_parser::~cmdline_parser ( )

inline

Delete all added arguments.

Definition at line 450 of file cmdline.h.

Member Function Documentation

void stxxl::cmdline_parser::add_bytes	(	char	key,
		const std::string &	longkey,
		const std::string &	keytype,
		stxxl::uint32 &	dest,
		const std::string &	desc
	)

inline

add SI/IEC suffixes byte size option -key, –longkey [keytype] and store to 64-bit dest

Examples:: examples/applications/skew3.cpp, and examples/common/cmdline.cpp.

Definition at line 531 of file cmdline.h.

void stxxl::cmdline_parser::add_bytes	(	char	key,
		const std::string &	longkey,
		const std::string &	keytype,
		stxxl::uint64 &	dest,
		const std::string &	desc
	)

inline

add SI/IEC suffixes byte size option -key, –longkey [keytype] and store to 64-bit dest

Definition at line 543 of file cmdline.h.

void stxxl::cmdline_parser::add_bytes	(	char	key,
		const std::string &	longkey,
		stxxl::uint32 &	dest,
		const std::string &	desc
	)

inline

add SI/IEC suffixes byte size option -key, –longkey [keytype] and store to 32-bit dest

Definition at line 602 of file cmdline.h.

void stxxl::cmdline_parser::add_bytes	(	char	key,
		const std::string &	longkey,
		stxxl::uint64 &	dest,
		const std::string &	desc
	)

inline

add SI/IEC suffixes byte size option -key, –longkey [keytype] and store to 64-bit dest

Definition at line 608 of file cmdline.h.

void stxxl::cmdline_parser::add_double	(	char	key,
		const std::string &	longkey,
		const std::string &	keytype,
		double &	dest,
		const std::string &	desc
	)

inline

add double option -key, –longkey [keytype] with description and store to dest

Definition at line 519 of file cmdline.h.

void stxxl::cmdline_parser::add_double	(	char	key,
		const std::string &	longkey,
		double &	dest,
		const std::string &	desc
	)

inline

add double option -key, –longkey [keytype] with description and store to dest

Definition at line 596 of file cmdline.h.

void stxxl::cmdline_parser::add_flag	(	char	key,
		const std::string &	longkey,
		const std::string &	keytype,
		bool &	dest,
		const std::string &	desc
	)

inline

add boolean option flag -key, –longkey [keytype] with description and store to dest

Examples:: examples/applications/skew3.cpp.

Definition at line 483 of file cmdline.h.

void stxxl::cmdline_parser::add_flag	(	char	key,
		const std::string &	longkey,
		bool &	dest,
		const std::string &	desc
	)

inline

add boolean option flag -key, –longkey with description and store to dest

Definition at line 578 of file cmdline.h.

void stxxl::cmdline_parser::add_int	(	char	key,
		const std::string &	longkey,
		const std::string &	keytype,
		int &	dest,
		const std::string &	desc
	)

inline

add signed integer option -key, –longkey [keytype] with description and store to dest

Definition at line 495 of file cmdline.h.

void stxxl::cmdline_parser::add_int	(	char	key,
		const std::string &	longkey,
		int &	dest,
		const std::string &	desc
	)

inline

add signed integer option -key, –longkey with description and store to dest

Definition at line 584 of file cmdline.h.

void stxxl::cmdline_parser::add_opt_param_bytes	(	const std::string &	name,
		uint32 &	dest,
		const std::string &	desc
	)

inline

add optional SI/IEC suffixes byte size parameter [name] with description and store to dest

Definition at line 735 of file cmdline.h.

void stxxl::cmdline_parser::add_opt_param_bytes	(	const std::string &	name,
		uint64 &	dest,
		const std::string &	desc
	)

inline

add optional SI/IEC suffixes byte size parameter [name] with description and store to dest

Definition at line 746 of file cmdline.h.

void stxxl::cmdline_parser::add_opt_param_double	(	const std::string &	name,
		double &	dest,
		const std::string &	desc
	)

inline

add optional double parameter [name] with description and store to dest

Definition at line 724 of file cmdline.h.

void stxxl::cmdline_parser::add_opt_param_int	(	const std::string &	name,
		int &	dest,
		const std::string &	desc
	)

inline

add optional signed integer parameter [name] with description and store to dest

Definition at line 703 of file cmdline.h.

void stxxl::cmdline_parser::add_opt_param_string	(	const std::string &	name,
		std::string &	dest,
		const std::string &	desc
	)

inline

add optional string parameter [name] with description and store to dest

Definition at line 756 of file cmdline.h.

void stxxl::cmdline_parser::add_opt_param_stringlist	(	const std::string &	name,
		std::vector< std::string > &	dest,
		const std::string &	desc
	)

inline

add optional string parameter [name] with description and store to dest

Warning: this parameter must be last, as it will gobble all non-option arguments!

Definition at line 768 of file cmdline.h.

void stxxl::cmdline_parser::add_opt_param_uint	(	const std::string &	name,
		unsigned int &	dest,
		const std::string &	desc
	)

inline

add optional unsigned integer parameter [name] with description and store to dest

Definition at line 714 of file cmdline.h.

void stxxl::cmdline_parser::add_param_bytes	(	const std::string &	name,
		uint32 &	dest,
		const std::string &	desc
	)

inline

add SI/IEC suffixes byte size parameter [name] with description and store to dest

Definition at line 656 of file cmdline.h.

void stxxl::cmdline_parser::add_param_bytes	(	const std::string &	name,
		uint64 &	dest,
		const std::string &	desc
	)

inline

add SI/IEC suffixes byte size parameter [name] with description and store to dest

Definition at line 667 of file cmdline.h.

void stxxl::cmdline_parser::add_param_double	(	const std::string &	name,
		double &	dest,
		const std::string &	desc
	)

inline

add double parameter [name] with description and store to dest

Definition at line 645 of file cmdline.h.

void stxxl::cmdline_parser::add_param_int	(	const std::string &	name,
		int &	dest,
		const std::string &	desc
	)

inline

add signed integer parameter [name] with description and store to dest

Definition at line 625 of file cmdline.h.

void stxxl::cmdline_parser::add_param_string	(	const std::string &	name,
		std::string &	dest,
		const std::string &	desc
	)

inline

add string parameter [name] with description and store to dest

Examples:: examples/applications/skew3.cpp, and examples/common/cmdline.cpp.

Definition at line 677 of file cmdline.h.

void stxxl::cmdline_parser::add_param_stringlist	(	const std::string &	name,
		std::vector< std::string > &	dest,
		const std::string &	desc
	)

inline

add string list parameter [name] with description and store to dest.

Warning: this parameter must be last, as it will gobble all non-option arguments!

Definition at line 689 of file cmdline.h.

void stxxl::cmdline_parser::add_param_uint	(	const std::string &	name,
		unsigned int &	dest,
		const std::string &	desc
	)

inline

add unsigned integer parameter [name] with description and store to dest

Definition at line 635 of file cmdline.h.

void stxxl::cmdline_parser::add_string	(	char	key,
		const std::string &	longkey,
		const std::string &	keytype,
		std::string &	dest,
		const std::string &	desc
	)

inline

add string option -key, –longkey [keytype] and store to dest

Examples:: examples/applications/skew3.cpp.

Definition at line 554 of file cmdline.h.

void stxxl::cmdline_parser::add_string	(	char	key,
		const std::string &	longkey,
		std::string &	dest,
		const std::string &	desc
	)

inline

add string option -key, –longkey [keytype] and store to dest

Definition at line 613 of file cmdline.h.

void stxxl::cmdline_parser::add_stringlist	(	char	key,
		const std::string &	longkey,
		const std::string &	keytype,
		std::vector< std::string > &	dest,
		const std::string &	desc
	)

inline

add string list option -key, –longkey [keytype] and store to dest

Definition at line 565 of file cmdline.h.

void stxxl::cmdline_parser::add_stringlist	(	char	key,
		const std::string &	longkey,
		std::vector< std::string > &	dest,
		const std::string &	desc
	)

inline

add string list option -key, –longkey [keytype] and store to dest

Definition at line 618 of file cmdline.h.

void stxxl::cmdline_parser::add_uint	(	char	key,
		const std::string &	longkey,
		const std::string &	keytype,
		unsigned int &	dest,
		const std::string &	desc
	)

inline

add unsigned integer option -key, –longkey [keytype] with description and store to dest

Examples:: examples/applications/skew3.cpp, and examples/common/cmdline.cpp.

Definition at line 507 of file cmdline.h.

void stxxl::cmdline_parser::add_uint	(	char	key,
		const std::string &	longkey,
		unsigned int &	dest,
		const std::string &	desc
	)

inline

add unsigned integer option -key, –longkey [keytype] with description and store to dest

Definition at line 590 of file cmdline.h.

void stxxl::cmdline_parser::calc_opt_max ( const argument * arg )

inlineprivate

update maximum formatting width for new option

Definition at line 417 of file cmdline.h.

References stxxl::cmdline_parser::argument::option_text(), and stxxl::STXXL_MAX().

void stxxl::cmdline_parser::calc_param_max ( const argument * arg )

inlineprivate

update maximum formatting width for new parameter

Definition at line 424 of file cmdline.h.

References stxxl::cmdline_parser::argument::param_text(), and stxxl::STXXL_MAX().

void stxxl::cmdline_parser::output_wrap	(	std::ostream &	os,
		const std::string &	text,
		size_t	wraplen,
		size_t	indent_first = `0`,
		size_t	indent_rest = `0`,
		size_t	current = `0`,
		size_t	indent_newline = `0`
	)

static

Wrap a long string at spaces into lines. Prefix is added unconditionally to each line. Lines are wrapped after wraplen characters if possible.

Definition at line 22 of file cmdline.cpp.

void stxxl::cmdline_parser::print_option_error	(	int	argc,
		const char const	argv,
		const argument *	arg,
		std::ostream &	os
	)

private

print error about option.

Definition at line 131 of file cmdline.cpp.

References stxxl::cmdline_parser::argument::option_text(), and stxxl::cmdline_parser::argument::type_name().

void stxxl::cmdline_parser::print_param_error	(	int	argc,
		const char const	argv,
		const argument *	arg,
		std::ostream &	os
	)

private

print error about parameter.

Definition at line 146 of file cmdline.cpp.

References stxxl::cmdline_parser::argument::param_text(), and stxxl::cmdline_parser::argument::type_name().

void stxxl::cmdline_parser::print_result ( std::ostream & os = std::cout )

print nicely formatted result of processing

Examples:: examples/common/cmdline.cpp.

Definition at line 306 of file cmdline.cpp.

References stxxl::cmdline_parser::argument::option_text(), stxxl::cmdline_parser::argument::param_text(), stxxl::cmdline_parser::argument::print_value(), stxxl::STXXL_MAX(), and stxxl::cmdline_parser::argument::type_name().

void stxxl::cmdline_parser::print_usage ( std::ostream & os = std::cout )

output nicely formatted usage information including description of all parameters and options.

Definition at line 62 of file cmdline.cpp.

References stxxl::cmdline_parser::argument::m_desc, stxxl::cmdline_parser::argument::m_longkey, stxxl::cmdline_parser::argument::m_repeated, stxxl::cmdline_parser::argument::m_required, stxxl::cmdline_parser::argument::option_text(), and stxxl::cmdline_parser::argument::param_text().

bool stxxl::cmdline_parser::process	(	int	argc,
		const char const	argv,
		std::ostream &	os = `std::cout`
	)

parse command line options as specified by the options and parameters added.

Returns: true if command line is okay and all required parameters are present.

Examples:: examples/applications/skew3.cpp, and examples/common/cmdline.cpp.

Definition at line 160 of file cmdline.cpp.

void stxxl::cmdline_parser::set_author ( const std::string & author )

inline

Set author of program, will be wrapped.

Examples:: examples/applications/skew3.cpp, and examples/common/cmdline.cpp.

Definition at line 468 of file cmdline.h.

void stxxl::cmdline_parser::set_description ( const std::string & description )

inline

Set description of program, text will be wrapped.

Examples:: examples/applications/skew3.cpp, and examples/common/cmdline.cpp.

Definition at line 462 of file cmdline.h.

void stxxl::cmdline_parser::set_verbose_process ( bool verbose_process )

inline

Set verbose processing of command line arguments.

Definition at line 474 of file cmdline.h.

Member Data Documentation

std::string stxxl::cmdline_parser::m_author

protected

user set author of program, will be wrapped

Definition at line 407 of file cmdline.h.

std::string stxxl::cmdline_parser::m_description

protected

user set description of program, will be wrapped

Definition at line 405 of file cmdline.h.

unsigned int stxxl::cmdline_parser::m_linewrap

protected

set line wrap length

Definition at line 410 of file cmdline.h.

const int stxxl::cmdline_parser::m_maxtypename = 16

staticprotected

maximum length of a type_name() result

Definition at line 413 of file cmdline.h.

int stxxl::cmdline_parser::m_opt_maxlong

protected

formatting width for options, '-s, –switch <#>'

Definition at line 394 of file cmdline.h.

arglist_type stxxl::cmdline_parser::m_optlist

protected

list of options available

Definition at line 389 of file cmdline.h.

int stxxl::cmdline_parser::m_param_maxlong

protected

formatting width for parameters, 'param <#>'

Definition at line 396 of file cmdline.h.

arglist_type stxxl::cmdline_parser::m_paramlist

protected

list of parameters, both required and optional

Definition at line 391 of file cmdline.h.

const char* stxxl::cmdline_parser::m_progname

protected

argv[0] for usage.

Definition at line 399 of file cmdline.h.

bool stxxl::cmdline_parser::m_verbose_process

protected

verbose processing of arguments

Definition at line 402 of file cmdline.h.

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

include/stxxl/bits/common/cmdline.h
lib/common/cmdline.cpp

Detailed Description

Classes

Public Member Functions

Static Public Member Functions

Protected Types

Protected Attributes

Static Protected Attributes

Private Member Functions

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation