Command line options and arguments. More...

#include <mutils/CommandLine.h>

Collaboration diagram for mutils::CommandLine:

[legend]

Classes
struct	Option
	Command line option specification. More...

Public Types
typedef std::vector< std::string >	Arguments
	Command line arguments type. More...

Public Member Functions
	CommandLine ()
	Default constructor. More...

	~CommandLine ()
	Destructor. More...

const Arguments &	arguments () const
	Returns remaining arguments (read-only). More...

const std::string &	driver () const
	Returns invoked driver program name (read-only). More...

double	getDouble (char shortName, double defValue) const
	Retrieves unique floating point option. More...

long	getInteger (char shortName) const
	Retrieves unique decimal integer option. More...

long	getInteger (char shortName, long defValue) const
	Retrieves unique decimal integer option. More...

unsigned	getOption (const Option &option, Arguments *values=nullptr, unsigned nMax=-1) const
	Retrieves all copies of a command line option. More...

unsigned	getOption (char shortName, Arguments *values=nullptr, unsigned nMax=-1) const
	Retrieves all copies of a command line option. More...

unsigned	getOption (const std::string &longName, Arguments *values=nullptr, unsigned nMax=-1) const
	Retrieves all copies of a command line option. More...

std::string	getString (char shortName, const std::string &defValue) const
	Retrieves unique string option. More...

void	init (int argc, char argv[], const std::vector< Option > opts)
	Initializes new command line input. More...

void	merge (Options &options) const
	Merges command line into options dictionary. More...

size_t	popOption (const Option &option)
	Removes and destroys all copies of a command line option. More...

size_t	popOption (char shortName)
	Removes and destroys all copies of a command line option. More...

size_t	popOption (const std::string &longName)
	Removes and destroys all copies of a command line option. More...

void	usage (FILE f, const std::vector< Option > &opts, const char args="", bool quiet=false, bool basename=true) const
	Summarizes command line usage (including options). More...

Private Types
typedef std::multimap< std::string, std::string >	LongMap
	Long option map type. More...

typedef std::multimap< char, std::string >	ShortMap
	Short option map type. More...

Private Member Functions
bool	parseLong (const char name, const char next)
	Processes a long option (possibly with a value). More...

bool	parseShort (const char name, const char next)
	Processes one or more short options (the last possibly with a value). More...

Private Attributes
Arguments	args_
	Trailing command line arguments. More...

std::string	driver_
	Invoked driver program name (argv[0] value). More...

LongMap	longOpts_
	Long option map. More...

ShortMap	shortOpts_
	Short option map. More...

const std::vector< Option > *	validOpts_
	Recognized command line options. More...

Detailed Description

Command line options and arguments.

This class manages command line options and arguments for an application. Its functionality is similar to the POSIX getopt() routine, but the API is structured to allow command line options to be retrieved in independent segments controlled by different callers. The command line interface accepts POSIX command line syntax, including support for GNU-style long options (e.g., --help), with the extension that short (single-character) options—like long options—may attach their value using an equals sign; e.g., -f FILE and -f=FILE are interchangeable, as are --file FILE and --file=FILE.

The complete command line is parsed into options (with or without values) and trailing arguments which are stored for later access. Callers then query for individual options in whatever order they find convenient; this allows queries to be divided among modules as appropriate. Options can have both short and long names and take a value, as indicated by the caller. It is permitted for the same option to be supplied multiple times on the command line; when queried, the option count and all values, if applicable, are returned.

Author: Kevin P. Rauch <rauch.nosp@m.@ast.nosp@m.ro.um.nosp@m.d.ed.nosp@m.u>

Definition at line 47 of file CommandLine.h.

Member Typedef Documentation

◆ Arguments

typedef std::vector<std::string> mutils::CommandLine::Arguments

Command line arguments type.

Definition at line 51 of file CommandLine.h.

◆ LongMap

typedef std::multimap<std::string, std::string> mutils::CommandLine::LongMap

private

Long option map type.

Definition at line 181 of file CommandLine.h.

◆ ShortMap

typedef std::multimap<char, std::string> mutils::CommandLine::ShortMap

private

Short option map type.

Definition at line 178 of file CommandLine.h.

Constructor & Destructor Documentation

◆ CommandLine()

mutils::CommandLine::CommandLine ( )

inline

Default constructor.

Definition at line 120 of file CommandLine.h.

◆ ~CommandLine()

mutils::CommandLine::~CommandLine ( )

inline

Destructor.

Definition at line 123 of file CommandLine.h.

Member Function Documentation

◆ arguments()

const Arguments& mutils::CommandLine::arguments ( ) const

inline

Returns remaining arguments (read-only).

Definition at line 132 of file CommandLine.h.

References args_.

Referenced by manticore::process().

◆ driver()

const std::string& mutils::CommandLine::driver ( ) const

inline

Returns invoked driver program name (read-only).

Definition at line 129 of file CommandLine.h.

References driver_.

◆ getDouble()

double mutils::CommandLine::getDouble	(	char	shortName,
		double	defValue
	)		const

Retrieves unique floating point option.

Parameters

[in]	shortName	Short name of option.
[in]	defValue	Default option value.

Returns: Option value, or the default value if the option is not present.

Exceptions

mu::Exception

The option is not unique.

Definition at line 376 of file CommandLine.cc.

References getOption().

Referenced by manticore::findParameters(), manticore::getError(), and manticore::solve().

◆ getInteger() [1/2]

long mutils::CommandLine::getInteger ( char shortName ) const

Retrieves unique decimal integer option.

Parameters

[in] shortName Short name of option.

Returns: Option value.

Exceptions

mu::Exception

The option does not exist, or is not unique.

Definition at line 341 of file CommandLine.cc.

References getOption(), and MU_EXCEPTION_IF.

Referenced by manticore::findParameters(), and manticore::solve().

◆ getInteger() [2/2]

long mutils::CommandLine::getInteger	(	char	shortName,
		long	defValue
	)		const

Retrieves unique decimal integer option.

Parameters

[in]	shortName	Short name of option.
[in]	defValue	Default option value.

Returns: Option value, or the default value if the option is not present.

Exceptions

mu::Exception

The option is not unique.

Definition at line 359 of file CommandLine.cc.

References getOption().

◆ getOption() [1/3]

unsigned mutils::CommandLine::getOption	(	const Option &	option,
		Arguments *	values = `nullptr`,
		unsigned	nMax = `-1`
	)		const

Retrieves all copies of a command line option.

Retrieves all occurrences of the specified option (if any). Use null single-letters and long names to indicate missing alternatives.

Parameters

[in]	option	Option specification.
[out]	values	Option values (optional).
[in]	nMax	Maximum number of entries allowed for option.

Returns: Number of entries for option.

Exceptions

mu::Exception

The number of values present exceeds maxVals.

Note: If values is specified for an option not taking a value, each returned value string will consist of a single null character (nullStr, which is distinct from an empty string in C++). This allows callers to distinguish "no value" from "empty value".

Definition at line 197 of file CommandLine.cc.

References std::vector::clear(), std::multimap::count(), std::string::empty(), std::multimap::equal_range(), mutils::CommandLine::Option::longName, longOpts_, MU_EXCEPTION_IF, std::vector::push_back(), mutils::CommandLine::Option::shortName, and shortOpts_.

Referenced by manticore::findParameters(), getDouble(), manticore::getError(), getInteger(), getOption(), manticore::getSingleMap(), getString(), main(), manticore::process(), manticore::setKeys(), and manticore::solve().

◆ getOption() [2/3]

unsigned mutils::CommandLine::getOption	(	char	shortName,
		Arguments *	values = `nullptr`,
		unsigned	nMax = `-1`
	)		const

Retrieves all copies of a command line option.

Parameters

[in]	shortName	Short option name.
[out]	values	Option values (optional).
[in]	nMax	Maximum number of entries allowed for option.

Returns: Number of entries for option.

Exceptions

mu::Exception

The number of values present exceeds maxVals.

Note: All copies of the option (whether referenced by short or long name) are returned.

Definition at line 249 of file CommandLine.cc.

References getOption(), and validOpts_.

◆ getOption() [3/3]

unsigned mutils::CommandLine::getOption	(	const std::string &	longName,
		Arguments *	values = `nullptr`,
		unsigned	nMax = `-1`
	)		const

Retrieves all copies of a command line option.

Parameters

[in]	longName	Long option name.
[out]	values	Option values (optional).
[in]	nMax	Maximum number of entries allowed for option.

Returns: Number of entries for option.

Exceptions

mu::Exception

The number of values present exceeds maxVals.

Note: All copies of the option (whether referenced by short or long name) are returned.

Definition at line 272 of file CommandLine.cc.

References getOption(), and validOpts_.

◆ getString()

std::string mutils::CommandLine::getString	(	char	shortName,
		const std::string &	defValue
	)		const

Retrieves unique string option.

Parameters

[in]	shortName	Short name of option.
[in]	defValue	Default option value.

Returns: Option value, or the default value if the option is not present.

Exceptions

mu::Exception

The option is not unique.

Definition at line 392 of file CommandLine.cc.

References getOption().

Referenced by main(), manticore::process(), and manticore::solve().

◆ init()

void mutils::CommandLine::init	(	int	argc,
		char *	argv[],
		const std::vector< Option > *	opts
	)

Initializes new command line input.

Initializes a new command line, erasing any existing contents (i.e., command lines do not accumulate). The complete set of valid options must be supplied at this time. Short options are preceded by a single hyphen (-) and may be aggregated if they do not take a value (except the last). Long options are preceded by two hyphens (--). Values can be explicitly attached to options (both long and short) using an equals sign; otherwise the following token is consumed. A bare -- token signals the end of all options (and is removed) and all following values are considered trailing arguments. Otherwise the first trailing argument is the first token that: (1) is not the value of an option; and (2) does not begin with a hyphen, or is a single bare hyphen (-).

Parameters

[in]	argc	Number of command line arguments.
[in]	argv	Input command line arguments.
[in]	opts	Recognized command line options.

Definition at line 151 of file CommandLine.cc.

References args_, std::multimap::clear(), std::vector::clear(), driver_, longOpts_, parseLong(), parseShort(), std::vector::push_back(), shortOpts_, and validOpts_.

Referenced by main().

◆ merge()

void mutils::CommandLine::merge ( Options & options ) const

Merges command line into options dictionary.

◆ parseLong()

bool mutils::CommandLine::parseLong	(	const char *	name,
		const char *	next
	)

private

Processes a long option (possibly with a value).

Scans a GNU-style long option. The next argument is used only if there is no explicitly attached value but one is required. For options without a value, the value string will be set to a single null character; this cannot be produced by assignment from a C string and hence its meaning is unambiguous.

Parameters

[in]	name	Option name (without leading `--`, possibly with attached value).
[in]	next	Next command line argument (may be the option value).

Returns: Whether next was consumed.

Definition at line 25 of file CommandLine.cc.

References std::string::assign(), std::vector::begin(), std::string::compare(), std::vector::end(), std::find_if(), std::multimap::insert(), longOpts_, MU_EXCEPTION_IF, mutils::nullStr, std::multimap::upper_bound(), and validOpts_.

Referenced by init().

◆ parseShort()

bool mutils::CommandLine::parseShort	(	const char *	name,
		const char *	next
	)

private

Processes one or more short options (the last possibly with a value).

Scans one or more short options. The final one may have a value. The next argument is used only if there is no explicitly attached value but one is required. (Values attached to short options, such as -f=foo, are a local MathUtils extension.) For options without a value, the value string will be set to a single null character; this cannot be produced by assignment from a C string and hence its meaning is unambiguous.

Parameters

[in]	name	Option name(s) (without leading `-`, possibly with attached value).
[in]	next	Next command line argument (may be the option value).

Returns: Whether next was consumed.

Definition at line 83 of file CommandLine.cc.

References std::string::assign(), std::vector::begin(), std::vector::end(), std::find_if(), std::multimap::insert(), MU_EXCEPTION_IF, mutils::nullStr, shortOpts_, std::multimap::upper_bound(), and validOpts_.

Referenced by init().

◆ popOption() [1/3]

size_t mutils::CommandLine::popOption ( const Option & option )

Removes and destroys all copies of a command line option.

Parameters

[in] option Option specification.

Returns: Number of options erased (short or long).

Note: All copies of the option (whether referenced by short or long name) are erased.

Definition at line 290 of file CommandLine.cc.

References std::string::empty(), std::multimap::erase(), mutils::CommandLine::Option::longName, longOpts_, mutils::CommandLine::Option::shortName, and shortOpts_.

Referenced by popOption().

◆ popOption() [2/3]

size_t mutils::CommandLine::popOption ( char shortName )

Removes and destroys all copies of a command line option.

Parameters

[in] shortName Short option name.

Returns: Number of options erased (long or short).

Note: All copies of the option (whether referenced by short or long name) are erased.

Definition at line 306 of file CommandLine.cc.

References popOption(), and validOpts_.

◆ popOption() [3/3]

size_t mutils::CommandLine::popOption ( const std::string & longName )

Removes and destroys all copies of a command line option.

Parameters

[in] longName Long option name.

Returns: Number of options erased (long or short).

Note: All copies of the option (whether referenced by short or long name) are erased.

Definition at line 323 of file CommandLine.cc.

References popOption(), and validOpts_.

◆ usage()

void mutils::CommandLine::usage	(	FILE *	f,
		const std::vector< Option > &	opts,
		const char *	args = `""`,
		bool	quiet = `false`,
		bool	basename = `true`
	)		const

Summarizes command line usage (including options).

Parameters

[in]	f	Open output file stream.
[in]	opts	Command line options specification.
[in]	args	Trailing arguments usage summary.
[in]	quiet	Whether to omit detailed option usage.
[in]	basename	Whether to strip pathname from driver program output.

Note: If Log::level is Log::DEBUG (or greater), the options summary will include the corresponding Options name, if any.

Definition at line 411 of file CommandLine.cc.

References std::string::c_str(), mutils::Log::DEBUG, driver_, std::string::find_last_of(), mutils::Log::level, mutils::npos, and mutils::nullStr.

Referenced by main().

Member Data Documentation

◆ args_

Arguments mutils::CommandLine::args_

private

Trailing command line arguments.

Definition at line 202 of file CommandLine.h.

Referenced by arguments(), and init().

◆ driver_

std::string mutils::CommandLine::driver_

private

Invoked driver program name (argv[0] value).

Definition at line 199 of file CommandLine.h.

Referenced by driver(), init(), and usage().

◆ longOpts_

LongMap mutils::CommandLine::longOpts_

private

Long option map.

Definition at line 196 of file CommandLine.h.

Referenced by getOption(), init(), parseLong(), and popOption().

◆ shortOpts_

ShortMap mutils::CommandLine::shortOpts_

private

Short option map.

Definition at line 193 of file CommandLine.h.

Referenced by getOption(), init(), parseShort(), and popOption().

◆ validOpts_

const std::vector<Option>* mutils::CommandLine::validOpts_

private

Recognized command line options.

Definition at line 190 of file CommandLine.h.

Referenced by getOption(), init(), parseLong(), parseShort(), and popOption().

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

mutils/CommandLine.h
mutils/CommandLine.cc

Classes

Public Types

Public Member Functions

Private Types

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ Arguments

◆ LongMap

◆ ShortMap

Constructor & Destructor Documentation

◆ CommandLine()

◆ ~CommandLine()

Member Function Documentation

◆ arguments()

◆ driver()

◆ getDouble()

◆ getInteger() [1/2]

◆ getInteger() [2/2]

◆ getOption() [1/3]

◆ getOption() [2/3]

◆ getOption() [3/3]

◆ getString()

◆ init()

◆ merge()

◆ parseLong()

◆ parseShort()

◆ popOption() [1/3]

◆ popOption() [2/3]

◆ popOption() [3/3]

◆ usage()

Member Data Documentation

◆ args_

◆ driver_

◆ longOpts_

◆ shortOpts_

◆ validOpts_