Description

Describes one argument of a command-line switch.

A SwitchArgument declares one argument for a switch. Each argument should have a string name that will appear in documentation and error messages. Each argument also has a ValueParser for parsing the argument, and an optional default value to use if the argument is missing (the presence of a default value makes the argument optional). If a default value is specified then it must be parsable by the specified parser.

A SwitchArgument declares only one argument. Some switches may have more than one argument, like --swap a b, in which case their declaration would have two SwitchArgument objects. Some switches take one argument which is a list of values, like --swap a,b, which is described by declaring a single argument with listParser. Some switches may occur multiple times to specify their arguments, like --swap a --swap b, in which case the switch is declared to have one argument and to save a value for each occurrence (see Switch::whichValue).

Users seldom use this class directly, but rather call Switch::argument to declare arguments.

Definition at line 1535 of file util/Sawyer/CommandLine.h.

#include <CommandLine.h>

Public Member Functions
	SwitchArgument (const std::string &name, const ValueParser::Ptr &parser=anyParser())
	Construct a new required argument. More...

	SwitchArgument (const std::string &name, const ValueParser::Ptr &parser, const std::string &defaultValueString)
	Construct a new switch optional argument. More...

bool	isRequired () const
	Returns true if this argument is required. More...

bool	isOptional () const
	Returns true if this argument is not required. More...

const std::string &	name () const
	Argument name. More...

std::string	nameAsText () const
	Returns the name without markup. More...

const ParsedValue &	defaultValue () const
	The parsed default value. More...

const std::string &	defaultValueString () const
	The default value string. More...

const ValueParser::Ptr &	parser () const
	Returns a pointer to the parser. More...

Constructor & Destructor Documentation

◆ SwitchArgument() [1/2]

Sawyer::CommandLine::SwitchArgument::SwitchArgument	(	const std::string &	name,
		const ValueParser::Ptr &	parser = `anyParser()`
	)

inlineexplicit

Construct a new required argument.

The name is used in documentation and error messages and need not be unique.

Definition at line 1544 of file util/Sawyer/CommandLine.h.

◆ SwitchArgument() [2/2]

Sawyer::CommandLine::SwitchArgument::SwitchArgument	(	const std::string &	name,
		const ValueParser::Ptr &	parser,
		const std::string &	defaultValueString
	)

inline

Construct a new switch optional argument.

The name is used in documentation and error messages and need not be unique. The defaultValueString is immediately parsed via supplied parser and stored; an std::runtime_error exception is thrown if it cannot be parsed.

Definition at line 1550 of file util/Sawyer/CommandLine.h.

References Sawyer::CommandLine::NOWHERE, and Sawyer::CommandLine::ParsedValue::valueLocation().

Here is the call graph for this function:

Member Function Documentation

◆ isRequired()

bool Sawyer::CommandLine::SwitchArgument::isRequired ( ) const

inline

Returns true if this argument is required.

An argument is a required argument if it has no default value.

Definition at line 1556 of file util/Sawyer/CommandLine.h.

References Sawyer::CommandLine::ParsedValue::isEmpty().

Here is the call graph for this function:

◆ isOptional()

bool Sawyer::CommandLine::SwitchArgument::isOptional ( ) const

inline

Returns true if this argument is not required.

Any argument that is not a required argument will have a default value that is returned in its place when parsing the switch.

Definition at line 1562 of file util/Sawyer/CommandLine.h.

◆ name()

const std::string& Sawyer::CommandLine::SwitchArgument::name ( ) const

inline

Argument name.

The name is used for documentation and error messages. It need not look like a variable. For instance, it could be "on|off|auto" to indicate that three values are possible, or "\@v{int}|wide" to indicate that the value can be any integer or the string "wide". The string may contain markup, which is removed when used in error messages. As a convenience, if the string begins with a lower-case letter and contains only lower-case letters, hyphens, and underscores then it will be treated as a variable. That is, the string "foo" is shorthand for "\@v{foo}".

Definition at line 1571 of file util/Sawyer/CommandLine.h.

◆ nameAsText()

std::string Sawyer::CommandLine::SwitchArgument::nameAsText ( ) const

Returns the name without markup.

See also: name

◆ defaultValue()

const ParsedValue& Sawyer::CommandLine::SwitchArgument::defaultValue ( ) const

inline

The parsed default value.

The ParsedValue::isEmpty() will return true if this argument is required.

Definition at line 1577 of file util/Sawyer/CommandLine.h.

◆ defaultValueString()

const std::string& Sawyer::CommandLine::SwitchArgument::defaultValueString ( ) const

inline

The default value string.

This is the string that was parsed to create the default value. Returns an empty string if the argument is required, but since such values are also valid default values one should call isRequired() or isOptional() to make that determination.

Definition at line 1584 of file util/Sawyer/CommandLine.h.

References Sawyer::CommandLine::ParsedValue::string().

Here is the call graph for this function: