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_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, const std::string &desc, stxxl::uint32 &dest)
	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, const std::string &desc, stxxl::uint64 &dest)
	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 &desc, stxxl::uint32 &dest)
	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, const std::string &desc, stxxl::uint64 &dest)
	add SI/IEC suffixes byte size option -key, –longkey [keytype] and store to 64-bit dest More...

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

void	add_flag (char key, const std::string &longkey, const std::string &desc, bool &dest)
	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, const std::string &desc, int &dest)
	add signed integer option -key, –longkey [keytype] with description and store to dest More...

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

void	add_opt_param_bytes (const std::string &name, const std::string &desc, uint32 &dest)
	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, const std::string &desc, uint64 &dest)
	add optional SI/IEC suffixes byte size parameter [name] with description and store to dest More...

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

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

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

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

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

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

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

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

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

void	add_param_uint (const std::string &name, const std::string &desc, unsigned int &dest)
	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, const std::string &desc, std::string &dest)
	add string option -key, –longkey [keytype] and store to dest More...

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

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

void	add_stringlist (char key, const std::string &longkey, const std::string &desc, std::vector< std::string > &dest)
	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, const std::string &desc, unsigned int &dest)
	add unsigned integer option -key, –longkey [keytype] with description and store to dest More...

void	add_uint (char key, const std::string &longkey, const std::string &desc, unsigned int &dest)
	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 334 of file cmdline.h.

Constructor & Destructor Documentation

stxxl::cmdline_parser::cmdline_parser ( )

inline

Construct new command line parser.

Definition at line 389 of file cmdline.h.

stxxl::cmdline_parser::~cmdline_parser ( )

inline

Delete all added arguments.

Definition at line 398 of file cmdline.h.

Member Function Documentation

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

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 457 of file cmdline.h.

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

inline

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

Definition at line 466 of file cmdline.h.

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

inline

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

Definition at line 505 of file cmdline.h.

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

inline

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

Definition at line 509 of file cmdline.h.

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

inline

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

Examples:: examples/applications/skew3.cpp.

Definition at line 430 of file cmdline.h.

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

inline

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

Definition at line 493 of file cmdline.h.

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

inline

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

Definition at line 439 of file cmdline.h.

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

inline

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

Definition at line 497 of file cmdline.h.

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

inline

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

Definition at line 598 of file cmdline.h.

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

inline

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

Definition at line 607 of file cmdline.h.

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

inline

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

Definition at line 580 of file cmdline.h.

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

inline

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

Definition at line 616 of file cmdline.h.

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

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 626 of file cmdline.h.

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

inline

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

Definition at line 589 of file cmdline.h.

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

inline

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

Definition at line 541 of file cmdline.h.

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

inline

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

Definition at line 550 of file cmdline.h.

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

inline

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

Definition at line 523 of file cmdline.h.

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

inline

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

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

Definition at line 559 of file cmdline.h.

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

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 569 of file cmdline.h.

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

inline

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

Definition at line 532 of file cmdline.h.

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

inline

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

Examples:: examples/applications/skew3.cpp.

Definition at line 475 of file cmdline.h.

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

inline

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

Definition at line 513 of file cmdline.h.

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

inline

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

Definition at line 484 of file cmdline.h.

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

inline

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

Definition at line 517 of file cmdline.h.

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

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 448 of file cmdline.h.

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

inline

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

Definition at line 501 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 365 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 372 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 416 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 410 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 422 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 355 of file cmdline.h.

std::string stxxl::cmdline_parser::m_description

protected

user set description of program, will be wrapped

Definition at line 353 of file cmdline.h.

unsigned int stxxl::cmdline_parser::m_linewrap

protected

set line wrap length

Definition at line 358 of file cmdline.h.

const int stxxl::cmdline_parser::m_maxtypename = 16

staticprotected

maximum length of a type_name() result

Definition at line 361 of file cmdline.h.

int stxxl::cmdline_parser::m_opt_maxlong

protected

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

Definition at line 342 of file cmdline.h.

arglist_type stxxl::cmdline_parser::m_optlist

protected

list of options available

Definition at line 337 of file cmdline.h.

int stxxl::cmdline_parser::m_param_maxlong

protected

formatting width for parameters, 'param <#>'

Definition at line 344 of file cmdline.h.

arglist_type stxxl::cmdline_parser::m_paramlist

protected

list of parameters, both required and optional

Definition at line 339 of file cmdline.h.

const char* stxxl::cmdline_parser::m_progname

protected

argv[0] for usage.

Definition at line 347 of file cmdline.h.

bool stxxl::cmdline_parser::m_verbose_process

protected

verbose processing of arguments

Definition at line 350 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