STXXL  1.4-dev
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
stxxl::cmdline_parser Class Reference

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)
void stxxl::cmdline_parser::print_usage ( std::ostream &  os = std::cout)
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: