Description

The result from parsing a command line.

The Parser::parse methods parse a command line without causing any side effects, placing all results in a ParserResult return value. If parsing is successful, the user then queries the result (a "pull" paradigm) or applies the result (a "push" paradigm), or both. In fact, even when the user only needs the pull paradigm for its own switches, it should still call apply anyway so that other software layers whose switch groups may have been included in the parser will receive values for their program variables and have their actions called.

SwitchGroup switches;
Parser parser;
parser.insert(switches);
ParserResult cmdline = parser.parse(argc, argv);
cmdline.apply();

In fact, if the user doesn't need to do any querying (they use only the push paradigm), there's no reason he even needs to keep the parser result (or even the parser) in a variable:

SwitchGroup switches;

Parser().with(switches).parse(argc, argv).apply();

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

#include <CommandLine.h>

Public Member Functions
const ParserResult &	apply () const
	Saves parsed values in switch-specified locations. More...

size_t	have (const std::string &switchKey) const
	Returns the number of values for the specified key. More...

std::vector< std::string >	skippedArgs () const
	Program arguments that were skipped over during parsing. More...

std::vector< std::string >	unreachedArgs () const
	Returns program arguments that were not reached during parsing. More...

std::vector< std::string >	unparsedArgs (bool includeTerminators=false) const
	Returns unparsed switches. More...

std::vector< std::string >	parsedArgs () const
	Returns the program arguments that were processed. More...

const std::vector< std::string > &	allArgs () const
	The original command line. More...

const Parser &	parser () const
	That parser that created this result. More...


const ParsedValue &	parsed (const std::string &switchKey, size_t idx) const
	Returns values for a key. More...

ParsedValues	parsed (const std::string &switchKey) const
	Returns values for a key. More...

Member Function Documentation

◆ apply()

const ParserResult& Sawyer::CommandLine::ParserResult::apply ( ) const

Saves parsed values in switch-specified locations.

This method implements the push paradigm mentioned in the class documentation (see ParserResult).

Referenced by Sawyer::CommandLine::Boost::command_line_parser::run().

Here is the caller graph for this function:

◆ have()

size_t Sawyer::CommandLine::ParserResult::have ( const std::string & switchKey ) const

inline

Returns the number of values for the specified key.

This is the number of values actually stored for switches using this key, which might be fewer than the number of values parsed. See Switch::whichValue.

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

References Sawyer::Container::Map< K, T, Cmp, Alloc >::getOrDefault().

Here is the call graph for this function:

◆ parsed() [1/2]

const ParsedValue& Sawyer::CommandLine::ParserResult::parsed	(	const std::string &	switchKey,
		size_t	idx
	)		const

Returns values for a key.

This is the usual method for obtaining a value for a switch. During parsing, the arguments of the switch are converted to ParsedValue objects and stored according to the key of the switch that did the parsing. For example, if --verbose has an intrinsic value of 1, and --quiet has a value of 0, and both use a "verbosity" key to store their result, here's how one would obtain the value for the last occurrence of either of these switches:

int verbosity = cmdline.parsed("verbosity").last().asInt();

If it is known that the switches both had a Switch::whichValue property that was SAVE_LAST then the more efficient version of parse with an index can be used:

int verbosity = cmdline.parsed("verbosity", 0).asInt();

◆ parsed() [2/2]

ParsedValues Sawyer::CommandLine::ParserResult::parsed ( const std::string & switchKey ) const

Returns values for a key.

This is the usual method for obtaining a value for a switch. During parsing, the arguments of the switch are converted to ParsedValue objects and stored according to the key of the switch that did the parsing. For example, if --verbose has an intrinsic value of 1, and --quiet has a value of 0, and both use a "verbosity" key to store their result, here's how one would obtain the value for the last occurrence of either of these switches:

int verbosity = cmdline.parsed("verbosity").last().asInt();

If it is known that the switches both had a Switch::whichValue property that was SAVE_LAST then the more efficient version of parse with an index can be used:

int verbosity = cmdline.parsed("verbosity", 0).asInt();

◆ skippedArgs()

std::vector<std::string> Sawyer::CommandLine::ParserResult::skippedArgs ( ) const

Program arguments that were skipped over during parsing.

If the Parser::skippingUnknownSwitches or Parser::skippingNonSwitches properties are true, then this method returns those command-line arguments that the parser skipped. The library makes no distinction between these two classes of skipping because in general, it is impossible to be accurate about it (see SwitchGroup for an example).

Program arguments inserted into the command line due to file inclusion will be returned in place of the file inclusion switch itself.

See also: unparsedArgs

◆ unreachedArgs()

std::vector<std::string> Sawyer::CommandLine::ParserResult::unreachedArgs ( ) const

Returns program arguments that were not reached during parsing.

These are the arguments left over when the parser stopped. Program arguments inserted into the command line due to file inclusion will be returned in place of the file inclusion switch itself.

See also: unparsedArgs

◆ unparsedArgs()

std::vector<std::string> Sawyer::CommandLine::ParserResult::unparsedArgs ( bool includeTerminators = false ) const

Returns unparsed switches.

Unparsed switches are those returned by skippedArgs and unreachedArgs.

The returned list includes termination switches (like --) if includeTerminators is true even if those switches were parsed. This can be useful when the parser is being used to remove recognized switches from a command-line. If the original command line was --theirs --mine -- --other and the parser recognizes only --mine and the -- terminator, then the caller would probably want to pass --theirs -- --other to the next software layer, which is exactly what this method returns when includeTerminators is true. Beware: removing command-line arguments that are recognized by a parser that has an incomplete picture of the entire language is not wise–see SwitchGroup for an example that fails.

Program arguments inserted into the command-line due to file inclusion will be returned in place of the file inclusion switch itself.

◆ parsedArgs()

std::vector<std::string> Sawyer::CommandLine::ParserResult::parsedArgs ( ) const

Returns the program arguments that were processed.

This includes terminator switches that were parsed.

Program arguments inserted into the command-line due to file inclusion will be returned in place of the file inclusion switch itself.

◆ allArgs()

const std::vector<std::string>& Sawyer::CommandLine::ParserResult::allArgs ( ) const

inline

The original command line.

This returns the original command line except that program arguments inserted into the command-line due to file inclusion will be returned in place of the file inclusion switch itself.

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

References Sawyer::CommandLine::Cursor::strings().

Here is the call graph for this function: