ROSE 0.11.145.147
|
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.
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:
Definition at line 3334 of file Sawyer/CommandLine.h.
#include <Sawyer/CommandLine.h>
Public Member Functions | |
const ParserResult & | apply () const |
Saves parsed values in switch-specified locations. | |
size_t | have (const std::string &switchKey) const |
Returns the number of values for the specified key. | |
std::vector< std::string > | skippedArgs () const |
Program arguments that were skipped over during parsing. | |
std::vector< std::string > | unreachedArgs () const |
Returns program arguments that were not reached during parsing. | |
std::vector< std::string > | unparsedArgs (bool includeTerminators=false) const |
Returns unparsed switches. | |
std::vector< std::string > | parsedArgs () const |
Returns the program arguments that were processed. | |
const std::vector< std::string > & | allArgs () const |
The original command line. | |
const Parser & | parser () const |
That parser that created this result. | |
const ParsedValue & | parsed (const std::string &switchKey, size_t idx) const |
Returns values for a key. | |
ParsedValues | parsed (const std::string &switchKey) const |
Returns values for a key. | |
|
inline |
Definition at line 3368 of file Sawyer/CommandLine.h.
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().
|
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 3376 of file Sawyer/CommandLine.h.
References Sawyer::Container::Map< K, T, Cmp, Alloc >::getOrDefault().
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:
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:
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:
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:
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.
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.
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.
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.
|
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 3448 of file Sawyer/CommandLine.h.
References Sawyer::CommandLine::Cursor::strings().
|
inline |
That parser that created this result.
This is a copy of the parser that was used to create this result.
Definition at line 3451 of file Sawyer/CommandLine.h.