Description

  Management and parsing of the command line

Author: Juan-Antonio Fernandez-Madrigal. http://jafma.net

Date: 2019 - 2020

Copyright: Copyright (c), Individual contributors, see AUTHORS file. This program is free for non-commercial uses. For the rest, contact the AUTHORS. Please include a mention in your programs to the main developer and the web page of the library.

Collaboration diagram for Command-line management and parsing:

Classes
class	elementa::utils::CLOption
	Specification for an option in the command line. More...

class	elementa::utils::CLOptionManager
	A class in charge of parsing and managing command line options. More...

Class Documentation

◆ elementa::utils::CLOption

class elementa::utils::CLOption

Specification for an option in the command line.

See also: CLOptionManager

Definition at line 47 of file commandline.h.

Collaboration diagram for elementa::utils::CLOption:

[legend]

Public Attributes
std::string	shortname
	Short option name; its unique identifier. More...

std::string	longname
	Long alternative name (may be empty). More...

PresenceKind	presence
	Presence of the option. More...

ValKind	valkind
	Kind of values it may have. More...

elementa::base::Strings	values
	Only used if valkind==ValKind::kEnum. More...

bool	mandatoryval
	TRUE if a value must be provided for the option. More...

std::string	dflt
	Default value. If empty, opt cannot have empty value. More...

StringGroups	dependencies
	Dependencies. More...

std::string	help
	Description of the option for showing help. More...

Public Member Functions
	ELE_CLASS_ENUM (ValKind, kFreeText, kNatural, kPositive, kInteger, kNumber, kEnum, kNone)
	Kind of values that the option may have. More...

	ELE_CLASS_ENUM (PresenceKind, kMandatory, kOptional, kAlone)
	Kind of presence an option may have.

void	checkSpec (void) const
	Check that the option specification is valid. Throw InvOptSpec if not.

void	checkValue (const std::string &v) const
	Check that the value is valid for the option. Throw InvOptValue if not.

elementa::base::Strings::size_type	whichIsDflt (void) const
	If it is an enum, return the index in VALUES of DFLT. More...

std::string	helpValues (void) const
	Return a string with the help about the values of the option.

bool	dependsOn (const CLOption &other) const
	Return TRUE if this option depends on OTHER.

bool	operator== (const CLOption &oo) const
	Return TRUE if both options have the same shortname. More...

bool	operator!= (const CLOption &oo) const
	The opposite to operator==. More...

Member Function Documentation

◆ ELE_CLASS_ENUM()

elementa::utils::CLOption::ELE_CLASS_ENUM	(	ValKind	,
		kFreeText	,
		kNatural	,
		kPositive	,
		kInteger	,
		kNumber	,
		kEnum	,
		kNone
	)

Kind of values that the option may have.

Note that the user cannot enter any value that begins the same as the option preffix used in the CLOptionManager.

◆ whichIsDflt()

elementa::base::Strings::size_type elementa::utils::CLOption::whichIsDflt ( void ) const

If it is an enum, return the index in VALUES of DFLT.

Return VALUES.SIZE() if DFLT is empty. Throws if it is not an enum.

◆ operator==()

bool elementa::utils::CLOption::operator== ( const CLOption & oo ) const

inline

Return TRUE if both options have the same shortname.

Definition at line 229 of file commandline.h.

References shortname.

◆ operator!=()

bool elementa::utils::CLOption::operator!= ( const CLOption & oo ) const

inline

The opposite to operator==.

Definition at line 233 of file commandline.h.

Member Data Documentation

◆ shortname

std::string elementa::utils::CLOption::shortname

Short option name; its unique identifier.

Definition at line 192 of file commandline.h.

Referenced by operator==().

◆ longname

std::string elementa::utils::CLOption::longname

Long alternative name (may be empty).

Definition at line 193 of file commandline.h.

◆ presence

PresenceKind elementa::utils::CLOption::presence

Presence of the option.

Definition at line 194 of file commandline.h.

◆ valkind

ValKind elementa::utils::CLOption::valkind

Kind of values it may have.

Definition at line 195 of file commandline.h.

◆ values

elementa::base::Strings elementa::utils::CLOption::values

Only used if valkind==ValKind::kEnum.

Text values from which the user must choose one to assign to the option.

Definition at line 196 of file commandline.h.

◆ mandatoryval

bool elementa::utils::CLOption::mandatoryval

TRUE if a value must be provided for the option.

kNone are never mandatory.

Definition at line 199 of file commandline.h.

◆ dflt

std::string elementa::utils::CLOption::dflt

Default value. If empty, opt cannot have empty value.

If enum, must be one of the enum values.

Definition at line 201 of file commandline.h.

◆ dependencies

StringGroups elementa::utils::CLOption::dependencies

Dependencies.

The option can appear in the CL only if any of the elements of 'dependencies' appear as well, i.e., only if ALL the short names appear. The order of appearance is not important.

Definition at line 203 of file commandline.h.

◆ help

std::string elementa::utils::CLOption::help

Description of the option for showing help.

Definition at line 209 of file commandline.h.

◆ elementa::utils::CLOptionManager

class elementa::utils::CLOptionManager

A class in charge of parsing and managing command line options.

Definition at line 245 of file commandline.h.

Public Member Functions
	CLOptionManager (const std::string &progname, const CLOption::Vector &opts, const CLOption::StringGroups &incomps, const std::string preff="-")
	Constructor from the options. More...

virtual	~CLOptionManager (void)=default
	Just to assure polymorphic deletions.

const std::string &	progName (void) const noexcept
	Return a reference to the program name. More...

const std::string &	preffix (void) const noexcept
	Return a reference to the preffix. More...

std::string	help (const std::string &shortname="", unsigned charwidth=80)
	Return a string with formatted help. More...

void	process (int argc, char *argv[])
	Read and process the command line parameters according to the options. More...

bool	present (const std::string &shortn, std::string &val) const
	If that option is present after processing, return TRUE and fill VAL. More...

bool	present (const std::string &shortn) const
	If that option is present after processing, return TRUE. More...

const CLOption &	optDef (const std::string &shortn) const
	Return a reference to the definition of the given option. More...

elementa::base::Strings	depOpts (const std::string &shortn) const
	Return all the options dependent on SHORTN, or empty if none. More...

std::string	processed_tostring (void) const
	Return the content of the command line after processing, as a text. More...

Constructor & Destructor Documentation

◆ CLOptionManager()

elementa::utils::CLOptionManager::CLOptionManager	(	const std::string &	progname,
		const CLOption::Vector &	opts,
		const CLOption::StringGroups &	incomps,
		const std::string	preff = `"-"`
	)

Constructor from the options.

Parameters

progname	is the name of the program that uses those options. It is copied internally.
opts	must outlive this object, since a reference to it is kept internally to consulting it.
incomps	must contain groups of options that are mutually incompatible (they cannot appear in the same command line). They must also outlive this object.
preff	is copied internally and contains the preffix required in all short- and long- option names. It is added automatically to them, thus you must not add it in OPTS. It cannot be empty.

Member Function Documentation

◆ progName()

const std::string & elementa::utils::CLOptionManager::progName ( void ) const

inlinenoexcept

Return a reference to the program name.

Definition at line 359 of file commandline.h.

◆ preffix()

const std::string & elementa::utils::CLOptionManager::preffix ( void ) const

inlinenoexcept

Return a reference to the preffix.

Definition at line 363 of file commandline.h.

◆ help()

std::string elementa::utils::CLOptionManager::help	(	const std::string &	shortname = `""`,
		unsigned	charwidth = `80`
	)

Return a string with formatted help.

Parameters

shortname	indicates about which you want the help: it it is empty return the help of all options; otherwise return only the help for that option (or throw if that option does not exist).
charwidth	is the number of character columns that bound the width of the help text (0 for no bound).

Note: If you set a charwidth and some element in the help (including the program name) is longer, an exception will be issued.

◆ process()

void elementa::utils::CLOptionManager::process	(	int	argc,
		char *	argv[]
	)

Read and process the command line parameters according to the options.

The parameters of the options cannot begin with the same preffix as the one of the options; in that case, they are not considered parameters, but another options, and therefore the one currently being processed has no parameter -if any default value was specified, that one will be used; otherwise, an error will be issued-.

◆ present() [1/2]

bool elementa::utils::CLOptionManager::present	(	const std::string &	shortn,
		std::string &	val
	)		const

If that option is present after processing, return TRUE and fill VAL.

If the option is not present, return FALSE and does not modify VAL. This is O(n*m), where N is the number of specified options and M the length of their longest short name. Undefined behaviour if no processing has been done previously.

◆ present() [2/2]

bool elementa::utils::CLOptionManager::present ( const std::string & shortn ) const

If that option is present after processing, return TRUE.

If the option is not present, return FALSE. This is O(n*m), where N is the number of specified options and M the length of their longest short name. Undefined behaviour if no processing has been done previously.

◆ optDef()

const CLOption & elementa::utils::CLOptionManager::optDef ( const std::string & shortn ) const

Return a reference to the definition of the given option.

If the option is not defined in this manager, throws.

◆ depOpts()

elementa::base::Strings elementa::utils::CLOptionManager::depOpts ( const std::string & shortn ) const

Return all the options dependent on SHORTN, or empty if none.

Throw if SHORTN is not an option defined in this manager.

◆ processed_tostring()

std::string elementa::utils::CLOptionManager::processed_tostring ( void ) const

inline

Return the content of the command line after processing, as a text.

If there has not been any processing, the behaviour is undefined. This is O(n*m), where N is the number of specified options and M the length of their longest short name.

Definition at line 412 of file commandline.h.

Description

Classes

Class Documentation

◆ elementa::utils::CLOption

Public Attributes

Public Member Functions

Member Function Documentation

◆ ELE_CLASS_ENUM()

◆ whichIsDflt()

◆ operator==()

◆ operator!=()

Member Data Documentation

◆ shortname

◆ longname

◆ presence

◆ valkind

◆ values

◆ mandatoryval

◆ dflt

◆ dependencies

◆ help

◆ elementa::utils::CLOptionManager

Public Member Functions

Constructor & Destructor Documentation

◆ CLOptionManager()

Member Function Documentation

◆ progName()

◆ preffix()

◆ help()

◆ process()

◆ present() [1/2]

◆ present() [2/2]

◆ optDef()

◆ depOpts()

◆ processed_tostring()