utilmm::command_line Class Reference

#include <commandline.hh>

Public Member Functions
	command_line (const std::list< std::string > &description)
	command_line (const char *options[])
	command_line (const std::list< std::string > &description)
	command_line (const char *options[])
void	parse (int argc, char const *const argv[], config_set &config)
void	parse (int argc, char const *const argv[], config_set &config)
std::list< std::string >	remaining () const
std::list< std::string >	remaining () const
void	setBanner (std::string const &banner)
void	setBanner (std::string const &banner)
void	usage (std::ostream &out) const
void	usage (std::ostream &out) const
	~command_line ()
	~command_line ()
Private Types
typedef std::vector < cmdline_option >	Options
typedef std::vector < cmdline_option >	Options
Private Member Functions
void	add_argument (config_set &config, cmdline_option const &optdesc, std::string const &value)
void	add_argument (config_set &config, cmdline_option const &optdesc, std::string const &value)
int	option_match (config_set &config, cmdline_option const &opt, int argc, char const const argv, int i)
int	option_match (config_set &config, cmdline_option const &opt, int argc, char const const argv, int i)
Private Attributes
std::string	m_banner
Options	m_options
std::list< std::string >	m_remaining

Detailed Description

command_line handling based on getopt_long

Description

The command_line class allows you to parse user-provided command line options and fill a Config object with them.

For each command line option, you must provide a long option (--option_text), may provide a short one (-option_character), and each option may have one (optional) argument. Eventually, you can give a help string (not used yet).

During the parsing, a key/value pair is added to a Config object for each option encountered. The value of the entry is either the option's argument or a boolean value of true if no option is specified.

Usage

The full syntax is

    [!*][config_key]:long_name[,short_name][=value_type[,default]|?value_type,default][:help]

where value_type is one of: int, bool, string

When an option is found, an entry is added to a Config object with the config_key key. The value associated is:

if there is an argument, the value is this argument
if the option takes no argument, it is set to true
if the argument is optional and not given, the value is default. default is required in case of optional arguments

If default is given, the option is set to default if it is not found

If the option has a mandatory argument, add =value_type after the option names. If it is optional, use the ?value_type syntax. The 'int' and 'bool' value types are checked by the command_line object and an error is generated if the user-provided value dos not match.

Multiplicity (* and ! options)

When the same option is provided more than once on the command line, the normal behaviour is to use the value of the latest. However, you can also get all the values by adding * at the front of the description line. In that case, the config value will a list of values in the config object

For instance, an option like the -I option of gcc will be described using
*:include,I=string|include path. The result of gcc -I /a/path -I=/another/path can then be retrieved with list<string> includes = config.get< list<string> >('include');

If the ! flag is set, the option is required.

Examples

The classical --help option will be given using :help|display this help and exit

The -r and --recursive options of grep are described using :recursive,r|equivalent to --directories=recurse

The -m and --max-count options of grep are described using :max-count,m=int|stop after NUM matches

Definition at line 165 of file install/include/utilmm/configfile/commandline.hh.

Member Typedef Documentation

typedef std::vector<cmdline_option> utilmm::command_line::Options [private]

Definition at line 168 of file utilmm/configfile/commandline.hh.

typedef std::vector<cmdline_option> utilmm::command_line::Options [private]

Definition at line 168 of file install/include/utilmm/configfile/commandline.hh.

Constructor & Destructor Documentation

utilmm::command_line::command_line ( const char * options[] )

Builds an object with a null-terminated string list

Parameters:

options

the option list, null-terminated

Definition at line 152 of file commandline.cc.

utilmm::command_line::command_line ( const std::list< std::string > & description )

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 158 of file commandline.cc.

utilmm::command_line::~command_line ( )

Definition at line 164 of file commandline.cc.

utilmm::command_line::command_line ( const char * options[] )

Builds an object with a null-terminated string list

Parameters:

options

the option list, null-terminated

utilmm::command_line::command_line ( const std::list< std::string > & description )

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

utilmm::command_line::~command_line ( )

Member Function Documentation

void utilmm::command_line::add_argument	(	config_set &	config,
		cmdline_option const &	optdesc,
		std::string const &	value
	)			`[private]`

void utilmm::command_line::add_argument	(	config_set &	config,
		cmdline_option const &	optdesc,
		std::string const &	value
	)			`[private]`

Definition at line 166 of file commandline.cc.

int utilmm::command_line::option_match	(	config_set &	config,
		cmdline_option const &	opt,
		int	argc,
		char const const	argv,
		int	i
	)			`[private]`

int utilmm::command_line::option_match	(	config_set &	config,
		cmdline_option const &	opt,
		int	argc,
		char const const	argv,
		int	i
	)			`[private]`

Definition at line 177 of file commandline.cc.

void utilmm::command_line::parse	(	int	argc,
		char const *const	argv[],
		config_set &	config
	)

Parses the command line option

Parameters:

	argc	the argument count
	argv	the argument value
	config	the Config object the option values will be written to

Exceptions:

commandline_error

void utilmm::command_line::parse	(	int	argc,
		char const *const	argv[],
		config_set &	config
	)

Parses the command line option

Parameters:

	argc	the argument count
	argv	the argument value
	config	the Config object the option values will be written to

Exceptions:

commandline_error

Definition at line 213 of file commandline.cc.

std::list<std::string> utilmm::command_line::remaining ( ) const

Remaining command line options After all options are matched, and if no error has occured, this function will return all non-option arguments (input files for instance)

list< string > utilmm::command_line::remaining ( ) const

Remaining command line options After all options are matched, and if no error has occured, this function will return all non-option arguments (input files for instance)

Definition at line 257 of file commandline.cc.

void utilmm::command_line::setBanner ( std::string const & banner )

Sets the first line to appear in usage()

void utilmm::command_line::setBanner ( std::string const & banner )

Sets the first line to appear in usage()

Definition at line 258 of file commandline.cc.

void utilmm::command_line::usage ( std::ostream & out ) const

Outputs a help message to out

void utilmm::command_line::usage ( std::ostream & out ) const

Outputs a help message to out

Definition at line 259 of file commandline.cc.