Description
Describes one command-line switch.
A command line switch is something that typically starts with a hyphen on Unix or a slash on Windows, followed by a name, and zero or more values. Switches refer to named command-line arguments but not usually positional command-line arguments.
The user normally interacts with the Switch class by instantiating a new switch object and setting properties for that object before inserting it into a SwitchGroup. All property-setting methods return a reference to the same switch and are typically chained together. In fact, the switch is often immediately inserted into the SwitchGroup without even creating a permanent switch object:
Definition at line 2041 of file util/Sawyer/CommandLine.h.
#include <CommandLine.h>
Public Member Functions | |
| Switch (const std::string &longName, char shortName='\0') | |
| Constructs a switch declaration. More... | |
| std::string | preferredName () const |
| Name by which switch prefers to be known. More... | |
| size_t | nArguments () const |
| Total number of arguments. More... | |
| size_t | nRequiredArguments () const |
| Number of required arguments. More... | |
| const ParsingProperties & | properties () const |
| Switch & | longName (const std::string &name) |
| Property: switch long name. More... | |
| const std::string & | longName () const |
| Property: switch long name. More... | |
| const std::vector< std::string > & | longNames () const |
| Property: switch long name. More... | |
| Switch & | shortName (char c) |
| Property: switch short name. More... | |
| const std::string & | shortNames () const |
| Property: switch short name. More... | |
| Switch & | key (const std::string &s) |
| Property: value storage key. More... | |
| const std::string & | key () const |
| Property: value storage key. More... | |
| Switch & | synopsis (const std::string &s) |
| Property: abstract summary of the switch syntax. More... | |
| std::string | synopsis () const |
| Property: abstract summary of the switch syntax. More... | |
| Switch & | doc (const std::string &s) |
| Property: detailed description. More... | |
| const std::string & | doc () const |
| Property: detailed description. More... | |
| Switch & | docKey (const std::string &s) |
| Property: key to control order of documentation. More... | |
| const std::string & | docKey () const |
| Property: key to control order of documentation. More... | |
| Switch & | hidden (bool b) |
| Property: whether this switch appears in documentation. More... | |
| bool | hidden () const |
| Property: whether this switch appears in documentation. More... | |
| Switch & | skipping (SwitchSkipping how) |
| Property: whether to skip over this switch. More... | |
| SwitchSkipping | skipping () const |
| Property: whether to skip over this switch. More... | |
| Switch & | resetLongPrefixes (const std::string &s1=STR_NONE, const std::string &s2=STR_NONE, const std::string &s3=STR_NONE, const std::string &s4=STR_NONE) |
| Property: prefixes for long names. More... | |
| Switch & | longPrefix (const std::string &s1) |
| Property: prefixes for long names. More... | |
| const std::vector< std::string > & | longPrefixes () const |
| Property: prefixes for long names. More... | |
| Switch & | resetShortPrefixes (const std::string &s1=STR_NONE, const std::string &s2=STR_NONE, const std::string &s3=STR_NONE, const std::string &s4=STR_NONE) |
| Property: prefixes for short names. More... | |
| Switch & | shortPrefix (const std::string &s1) |
| Property: prefixes for short names. More... | |
| const std::vector< std::string > & | shortPrefixes () const |
| Property: prefixes for short names. More... | |
| Switch & | resetValueSeparators (const std::string &s1=STR_NONE, const std::string &s2=STR_NONE, const std::string &s3=STR_NONE, const std::string &s4=STR_NONE) |
| Property: strings that separate a long switch from its value. More... | |
| Switch & | valueSeparator (const std::string &s1) |
| Property: strings that separate a long switch from its value. More... | |
| const std::vector< std::string > & | valueSeparators () const |
| Property: strings that separate a long switch from its value. More... | |
| Switch & | argument (const std::string &name, const ValueParser::Ptr &parser=anyParser()) |
| Property: switch argument. More... | |
| Switch & | argument (const std::string &name, const ValueParser::Ptr &parser, const std::string &defaultValue) |
| Property: switch argument. More... | |
| Switch & | argument (const SwitchArgument &arg) |
| Property: switch argument. More... | |
| const SwitchArgument & | argument (size_t idx) const |
| Property: switch argument. More... | |
| const std::vector< SwitchArgument > & | arguments () const |
| Property: switch argument. More... | |
| template<typename T > | |
| Switch & | intrinsicValue (const T &value, T &storage) |
| Property: value for a switch that has no declared arguments. More... | |
| Switch & | intrinsicValue (const char *value, std::string &storage) |
| Property: value for a switch that has no declared arguments. More... | |
| Switch & | intrinsicValue (const std::string &text, const ValueParser::Ptr &p) |
| Property: value for a switch that has no declared arguments. More... | |
| Switch & | intrinsicValue (const std::string &text) |
| Property: value for a switch that has no declared arguments. More... | |
| Switch & | intrinsicValue (const ParsedValue &value) |
| Property: value for a switch that has no declared arguments. More... | |
| ParsedValue | intrinsicValue () const |
| Property: value for a switch that has no declared arguments. More... | |
| Switch & | explosiveLists (bool b) |
| Property: whether to convert a list value to individual values. More... | |
| bool | explosiveLists () const |
| Property: whether to convert a list value to individual values. More... | |
| Switch & | action (const SwitchAction::Ptr &f) |
| Property: action to occur. More... | |
| const SwitchAction::Ptr & | action () const |
| Property: action to occur. More... | |
| Switch & | whichValue (WhichValue s) |
| Property: how to handle multiple occurrences. More... | |
| WhichValue | whichValue () const |
| Property: how to handle multiple occurrences. More... | |
| Switch & | valueAugmenter (const ValueAugmenter::Ptr &f) |
| Property: functor to agument values. More... | |
| ValueAugmenter::Ptr | valueAugmenter () const |
| Property: functor to agument values. More... | |
Constructor & Destructor Documentation
◆ Switch()
|
inlineexplicit |
Constructs a switch declaration.
Every switch must have either a long or short name (or both), neither of which should include prefix characters such as hyphens. The best practice is to provide a long name for every switch and short names only for the most commonly used switches.
Additional names can be specified with the longName and shortName methods, but the constructor should be provided the canonical names. The canonical names will be used to create the initial value for the key property, and will be used for organizing parsed values by switch. They also appear in some error messages when command-line text is not available, and they will appear first in documentation.
Names of switches need not be unique. If more than one switch is able to parse a command-line argument then the first declaration wins. This feature is sometimes used to declare two switches having identical names but different arguments or argument types.
Definition at line 2074 of file util/Sawyer/CommandLine.h.
Member Function Documentation
◆ longName() [1/2]
| Switch& Sawyer::CommandLine::Switch::longName | ( | const std::string & | name | ) |
Property: switch long name.
Long names normally consist of multiple letters and use prefixes that are different than the short (single-letter) names. Also, the value for long-name switches is usually separated from the switch by a special character (like "=") or by appearing in the next program argument.
◆ longName() [2/2]
|
inline |
Property: switch long name.
Long names normally consist of multiple letters and use prefixes that are different than the short (single-letter) names. Also, the value for long-name switches is usually separated from the switch by a special character (like "=") or by appearing in the next program argument.
Definition at line 2086 of file util/Sawyer/CommandLine.h.
◆ longNames()
|
inline |
Property: switch long name.
Long names normally consist of multiple letters and use prefixes that are different than the short (single-letter) names. Also, the value for long-name switches is usually separated from the switch by a special character (like "=") or by appearing in the next program argument.
Definition at line 2087 of file util/Sawyer/CommandLine.h.
◆ shortName()
|
inline |
Property: switch short name.
Short names are single letters and use a different set of prefixes than long names (which can also be a single letter). Also, when a short-name switch has an argument the value for the argument can be adjacent to the switch, like -n5, but long-name switches usually separate the switch from the value with a special string, like --number=5.
Definition at line 2095 of file util/Sawyer/CommandLine.h.
◆ shortNames()
|
inline |
Property: switch short name.
Short names are single letters and use a different set of prefixes than long names (which can also be a single letter). Also, when a short-name switch has an argument the value for the argument can be adjacent to the switch, like -n5, but long-name switches usually separate the switch from the value with a special string, like --number=5.
Definition at line 2096 of file util/Sawyer/CommandLine.h.
◆ preferredName()
|
inline |
Name by which switch prefers to be known.
This is the first long name, or the first short name if there are no long names.
Definition at line 2101 of file util/Sawyer/CommandLine.h.
◆ key() [1/2]
|
inline |
Property: value storage key.
When a switch value is parsed (or an intrinsic or default value is used) to create a ParsedValue object, the object will be associated with the switch key. This allows different switches to write to the same result locations and is useful for different keys that refer to the same concept, like --verbose and --quiet. The default is to use the long (or short, if no long) name specified in the constructor. The switch prefix (e.g., "-") should generally not be part of the key because it becomes confusing when it appears in error messages (it looks like a switch occurrence string yet might be completely unrelated to what appeared on the command line).
Definition at line 2111 of file util/Sawyer/CommandLine.h.
◆ key() [2/2]
|
inline |
Property: value storage key.
When a switch value is parsed (or an intrinsic or default value is used) to create a ParsedValue object, the object will be associated with the switch key. This allows different switches to write to the same result locations and is useful for different keys that refer to the same concept, like --verbose and --quiet. The default is to use the long (or short, if no long) name specified in the constructor. The switch prefix (e.g., "-") should generally not be part of the key because it becomes confusing when it appears in error messages (it looks like a switch occurrence string yet might be completely unrelated to what appeared on the command line).
Definition at line 2112 of file util/Sawyer/CommandLine.h.
◆ synopsis() [1/2]
|
inline |
Property: abstract summary of the switch syntax.
The synopsis is normally generated automatically from other information specified for the switch, but the user may provide a synopsis to override the generated one. A synopsis should be a semi-colon separated list of alternative switch sytax specifications using markup to specify things such as the switch name and switch/value separator. Using markup will cause the synopsis to look correct regardless of the operating system or output media. See the doc method for details. For example, the git-rev-parse(1) man page has the following documentation for three related switches:
This library handles that situation by attaching the documentation to a single switch, say "branches", and hiding documentation for the other two switches. But this also requires that the synopsis for "branches" be changed from its library-generated vesion:
Note: the git man pages separate alternative switches with commas, but this library uses semicolons since commas also frequirently appear within the syntax description of a single switch.
- See also
- doc
Definition at line 2146 of file util/Sawyer/CommandLine.h.
◆ synopsis() [2/2]
| std::string Sawyer::CommandLine::Switch::synopsis | ( | ) | const |
Property: abstract summary of the switch syntax.
The synopsis is normally generated automatically from other information specified for the switch, but the user may provide a synopsis to override the generated one. A synopsis should be a semi-colon separated list of alternative switch sytax specifications using markup to specify things such as the switch name and switch/value separator. Using markup will cause the synopsis to look correct regardless of the operating system or output media. See the doc method for details. For example, the git-rev-parse(1) man page has the following documentation for three related switches:
This library handles that situation by attaching the documentation to a single switch, say "branches", and hiding documentation for the other two switches. But this also requires that the synopsis for "branches" be changed from its library-generated vesion:
Note: the git man pages separate alternative switches with commas, but this library uses semicolons since commas also frequirently appear within the syntax description of a single switch.
- See also
- doc
◆ doc() [1/2]
|
inline |
Property: detailed description.
This is the description of the switch in a simple markup language.
Parts of the text can be marked by surrounding the text in curly braces and prepending a tag consisting of an "@" followed by a word. For instance, @b{foo} makes the word "foo" bold and @i{foo} makes it italic. The text between the curly braces can be any length, and if it contains curly braces they must either balance or be escaped with a preceding "@". The curly braces that start an argument must not be preceded by white space.
Besides describing the format of a piece of text, markup is also used to describe the intent of a piece of text. The following intents are supported:
@v{foo}specifies that "foo" is a variable. POD-based man pages will underline it, and text based documentation will surround it with angle brackets.@s{foo}specifies that "foo" is a switch. The argument should be a single word or single letter without leading hyphens, and the correct prefix (hyphens, etc.) will be added automatically based on the parser's configuration. The documentation system also verifies that "foo" is spelled correctly and if not, it adds an error to the "Documentation issues" section of the output. To suppress these errors, supply a second argument whose name is "noerror", as in "@s{foo}{noerror}".@man{foo}{n}means refer to the "foo" page in chapter "n" of the man pages. This also adds an entry to the "See also" section of the output.
The @prop tag takes one argument which is a property name and is replaced by the value of the property. The following properties are defined:
inclusionPrefixis the preferred (first) string returned by Parser::inclusionPrefixes.terminationSwitchis the preferred (first) switch returned by Parser::terminationSwitches.programNameis the string returned by Parser::programName.purposeis the string returned by Parser::purpose.versionStringis the first member of the pair returned by Parser::version.versionDateis the second member of the pair returned by Parser::version.chapterNumberis the first member of the pair returned by Parser::chapter.chapterNameis the second member of the pair returned by Parser::chapter.
Even switches with no documentation will show up in the generated documentation–they will be marked as "Not documented". To suppress them entirely, set their hidden property to true.
Definition at line 2185 of file util/Sawyer/CommandLine.h.
◆ doc() [2/2]
|
inline |
Property: detailed description.
This is the description of the switch in a simple markup language.
Parts of the text can be marked by surrounding the text in curly braces and prepending a tag consisting of an "@" followed by a word. For instance, @b{foo} makes the word "foo" bold and @i{foo} makes it italic. The text between the curly braces can be any length, and if it contains curly braces they must either balance or be escaped with a preceding "@". The curly braces that start an argument must not be preceded by white space.
Besides describing the format of a piece of text, markup is also used to describe the intent of a piece of text. The following intents are supported:
@v{foo}specifies that "foo" is a variable. POD-based man pages will underline it, and text based documentation will surround it with angle brackets.@s{foo}specifies that "foo" is a switch. The argument should be a single word or single letter without leading hyphens, and the correct prefix (hyphens, etc.) will be added automatically based on the parser's configuration. The documentation system also verifies that "foo" is spelled correctly and if not, it adds an error to the "Documentation issues" section of the output. To suppress these errors, supply a second argument whose name is "noerror", as in "@s{foo}{noerror}".@man{foo}{n}means refer to the "foo" page in chapter "n" of the man pages. This also adds an entry to the "See also" section of the output.
The @prop tag takes one argument which is a property name and is replaced by the value of the property. The following properties are defined:
inclusionPrefixis the preferred (first) string returned by Parser::inclusionPrefixes.terminationSwitchis the preferred (first) switch returned by Parser::terminationSwitches.programNameis the string returned by Parser::programName.purposeis the string returned by Parser::purpose.versionStringis the first member of the pair returned by Parser::version.versionDateis the second member of the pair returned by Parser::version.chapterNumberis the first member of the pair returned by Parser::chapter.chapterNameis the second member of the pair returned by Parser::chapter.
Even switches with no documentation will show up in the generated documentation–they will be marked as "Not documented". To suppress them entirely, set their hidden property to true.
Definition at line 2186 of file util/Sawyer/CommandLine.h.
◆ docKey() [1/2]
|
inline |
Property: key to control order of documentation.
Normally, documentation for a group of switches is sorted according to the switche's preferredName. Specifying a docKey string causes that string to be used instead of the switch names. The key string itself never appears in any documentation.
Definition at line 2193 of file util/Sawyer/CommandLine.h.
Referenced by Sawyer::CommandLine::Parser::with().
◆ docKey() [2/2]
|
inline |
Property: key to control order of documentation.
Normally, documentation for a group of switches is sorted according to the switche's preferredName. Specifying a docKey string causes that string to be used instead of the switch names. The key string itself never appears in any documentation.
Definition at line 2194 of file util/Sawyer/CommandLine.h.
◆ hidden() [1/2]
|
inline |
Property: whether this switch appears in documentation.
A hidden switch still participates when parsing command lines, but will not show up in documentation. This is ofen used for a switch when that switch is documented as part of some other switch.
Definition at line 2201 of file util/Sawyer/CommandLine.h.
◆ hidden() [2/2]
|
inline |
Property: whether this switch appears in documentation.
A hidden switch still participates when parsing command lines, but will not show up in documentation. This is ofen used for a switch when that switch is documented as part of some other switch.
Definition at line 2202 of file util/Sawyer/CommandLine.h.
◆ skipping() [1/2]
|
inline |
Property: whether to skip over this switch.
The default is to not skip over anything, in which case if the switch appears on the command-line its actions are run and its value are saved. If skipping is set to SKIP_WEAK or SKIP_STRONG then the switch and its arguments are also added to the skipped list returned by ParserResult::skippedArgs and ParserResult::unparsedArgs. The difference between weak and strong is that strong also skips any actions and value saving for the switch.
For short, nestled switches, a program argument is added to the skipped list if any of the short switches in that argument are SKIP_WEAK or SKIP_STRONG.
Definition at line 2216 of file util/Sawyer/CommandLine.h.
◆ skipping() [2/2]
|
inline |
Property: whether to skip over this switch.
The default is to not skip over anything, in which case if the switch appears on the command-line its actions are run and its value are saved. If skipping is set to SKIP_WEAK or SKIP_STRONG then the switch and its arguments are also added to the skipped list returned by ParserResult::skippedArgs and ParserResult::unparsedArgs. The difference between weak and strong is that strong also skips any actions and value saving for the switch.
For short, nestled switches, a program argument is added to the skipped list if any of the short switches in that argument are SKIP_WEAK or SKIP_STRONG.
Definition at line 2217 of file util/Sawyer/CommandLine.h.
◆ resetLongPrefixes()
| Switch& Sawyer::CommandLine::Switch::resetLongPrefixes | ( | const std::string & | s1 = STR_NONE, |
| const std::string & | s2 = STR_NONE, |
||
| const std::string & | s3 = STR_NONE, |
||
| const std::string & | s4 = STR_NONE |
||
| ) |
Property: prefixes for long names.
A long name prefix is the characters that introduce a long switch, usually "-\-" and sometimes "-" or "+"). Prefixes are specified in the parser, the switch group, and the switch, each entity inheriting and augmenting the list from the earlier entity. To prevent inheritance use the resetLongPrefixes method, which also takes an optional list of new prefixes. In any case, additional prefixes can be added with longPrefix, which should be after resetLongPrefixes if both are used. The empty string is a valid prefix and is sometimes used in conjunction with "=" as a value separator to describe dd(1)-style switches of the form "bs=1024".
It is generally unwise to override prefixes without inheritance since the parser itself chooses the basic prefixes based on the conventions used by the operating system. Erasing these defaults might get you a command line syntax that's jarring to uses.
◆ longPrefix()
|
inline |
Property: prefixes for long names.
A long name prefix is the characters that introduce a long switch, usually "-\-" and sometimes "-" or "+"). Prefixes are specified in the parser, the switch group, and the switch, each entity inheriting and augmenting the list from the earlier entity. To prevent inheritance use the resetLongPrefixes method, which also takes an optional list of new prefixes. In any case, additional prefixes can be added with longPrefix, which should be after resetLongPrefixes if both are used. The empty string is a valid prefix and is sometimes used in conjunction with "=" as a value separator to describe dd(1)-style switches of the form "bs=1024".
It is generally unwise to override prefixes without inheritance since the parser itself chooses the basic prefixes based on the conventions used by the operating system. Erasing these defaults might get you a command line syntax that's jarring to uses.
Definition at line 2233 of file util/Sawyer/CommandLine.h.
◆ longPrefixes()
|
inline |
Property: prefixes for long names.
A long name prefix is the characters that introduce a long switch, usually "-\-" and sometimes "-" or "+"). Prefixes are specified in the parser, the switch group, and the switch, each entity inheriting and augmenting the list from the earlier entity. To prevent inheritance use the resetLongPrefixes method, which also takes an optional list of new prefixes. In any case, additional prefixes can be added with longPrefix, which should be after resetLongPrefixes if both are used. The empty string is a valid prefix and is sometimes used in conjunction with "=" as a value separator to describe dd(1)-style switches of the form "bs=1024".
It is generally unwise to override prefixes without inheritance since the parser itself chooses the basic prefixes based on the conventions used by the operating system. Erasing these defaults might get you a command line syntax that's jarring to uses.
Definition at line 2234 of file util/Sawyer/CommandLine.h.
◆ resetShortPrefixes()
| Switch& Sawyer::CommandLine::Switch::resetShortPrefixes | ( | const std::string & | s1 = STR_NONE, |
| const std::string & | s2 = STR_NONE, |
||
| const std::string & | s3 = STR_NONE, |
||
| const std::string & | s4 = STR_NONE |
||
| ) |
Property: prefixes for short names.
A short name prefix is the characters that introduce a short switch, usually "-". Prefixes are specified in the parser, the switch group, and the switch, each entity inheriting and augmenting the list from the earlier entity. To prevent inheritance use the resetShortPrefixes method, which also takes an optional list of new prefixes. In any case, additional prefixes can be added with shortPrefix, which should be after resetShortPrefixes if both are used. The empty string is a valid short prefix to be able to parse tar(1)-like switches like "xvf".
It is generally unwise to override prefixes without inheritance since the parser itself chooses the basic prefixes based on the conventions used by the operating system. Erasing these defaults might get you a command line syntax that's jarring to uses.
◆ shortPrefix()
|
inline |
Property: prefixes for short names.
A short name prefix is the characters that introduce a short switch, usually "-". Prefixes are specified in the parser, the switch group, and the switch, each entity inheriting and augmenting the list from the earlier entity. To prevent inheritance use the resetShortPrefixes method, which also takes an optional list of new prefixes. In any case, additional prefixes can be added with shortPrefix, which should be after resetShortPrefixes if both are used. The empty string is a valid short prefix to be able to parse tar(1)-like switches like "xvf".
It is generally unwise to override prefixes without inheritance since the parser itself chooses the basic prefixes based on the conventions used by the operating system. Erasing these defaults might get you a command line syntax that's jarring to uses.
Definition at line 2250 of file util/Sawyer/CommandLine.h.
◆ shortPrefixes()
|
inline |
Property: prefixes for short names.
A short name prefix is the characters that introduce a short switch, usually "-". Prefixes are specified in the parser, the switch group, and the switch, each entity inheriting and augmenting the list from the earlier entity. To prevent inheritance use the resetShortPrefixes method, which also takes an optional list of new prefixes. In any case, additional prefixes can be added with shortPrefix, which should be after resetShortPrefixes if both are used. The empty string is a valid short prefix to be able to parse tar(1)-like switches like "xvf".
It is generally unwise to override prefixes without inheritance since the parser itself chooses the basic prefixes based on the conventions used by the operating system. Erasing these defaults might get you a command line syntax that's jarring to uses.
Definition at line 2251 of file util/Sawyer/CommandLine.h.
◆ resetValueSeparators()
| Switch& Sawyer::CommandLine::Switch::resetValueSeparators | ( | const std::string & | s1 = STR_NONE, |
| const std::string & | s2 = STR_NONE, |
||
| const std::string & | s3 = STR_NONE, |
||
| const std::string & | s4 = STR_NONE |
||
| ) |
Property: strings that separate a long switch from its value.
A value separator is the string that separates a long switch name from its value and is usually "=" and/or " ". The " " string has special meaning: it indicates that the value must be separated from the switch by being in the following command line argument. Separators are specified in the parser, the switch group, and the switch, each entity inheriting and augmenting the list from the earlier entity. To prevent inheritance use the resetValueSeparators method, which also takes an optional list of new separators. In any case, additional separators can be added with valueSeparator, which should be after resetValueSeparators if both are used.
The empty string is a valid separator although typically not used since it leads to hacks like --liberty as an alternative to --lib=irty, and confusing error messages like "switch '-\-lib' is mutually exclusive
with '-\-no-libs'" (and the user says, "I didn't use '-\-lib' anywhere, something's wrong with the parser").
It is generally unwise to override the separators without inheritance since the parser itself chooses the basic separators based on the conventions used by the operating system. Erasing these defaults might get you a command line syntax that's jarring to uses.
◆ valueSeparator()
|
inline |
Property: strings that separate a long switch from its value.
A value separator is the string that separates a long switch name from its value and is usually "=" and/or " ". The " " string has special meaning: it indicates that the value must be separated from the switch by being in the following command line argument. Separators are specified in the parser, the switch group, and the switch, each entity inheriting and augmenting the list from the earlier entity. To prevent inheritance use the resetValueSeparators method, which also takes an optional list of new separators. In any case, additional separators can be added with valueSeparator, which should be after resetValueSeparators if both are used.
The empty string is a valid separator although typically not used since it leads to hacks like --liberty as an alternative to --lib=irty, and confusing error messages like "switch '-\-lib' is mutually exclusive
with '-\-no-libs'" (and the user says, "I didn't use '-\-lib' anywhere, something's wrong with the parser").
It is generally unwise to override the separators without inheritance since the parser itself chooses the basic separators based on the conventions used by the operating system. Erasing these defaults might get you a command line syntax that's jarring to uses.
Definition at line 2272 of file util/Sawyer/CommandLine.h.
◆ valueSeparators()
|
inline |
Property: strings that separate a long switch from its value.
A value separator is the string that separates a long switch name from its value and is usually "=" and/or " ". The " " string has special meaning: it indicates that the value must be separated from the switch by being in the following command line argument. Separators are specified in the parser, the switch group, and the switch, each entity inheriting and augmenting the list from the earlier entity. To prevent inheritance use the resetValueSeparators method, which also takes an optional list of new separators. In any case, additional separators can be added with valueSeparator, which should be after resetValueSeparators if both are used.
The empty string is a valid separator although typically not used since it leads to hacks like --liberty as an alternative to --lib=irty, and confusing error messages like "switch '-\-lib' is mutually exclusive
with '-\-no-libs'" (and the user says, "I didn't use '-\-lib' anywhere, something's wrong with the parser").
It is generally unwise to override the separators without inheritance since the parser itself chooses the basic separators based on the conventions used by the operating system. Erasing these defaults might get you a command line syntax that's jarring to uses.
Definition at line 2273 of file util/Sawyer/CommandLine.h.
◆ argument() [1/4]
| Switch& Sawyer::CommandLine::Switch::argument | ( | const std::string & | name, |
| const ValueParser::Ptr & | parser = anyParser() |
||
| ) |
Property: switch argument.
A switch argument declares how text after the switch name is parsed to form a value. An argument specifier contains a name, a parser, and an optional default value.
The name is used in error messages and documentation and should be chosen to be a descriptive but terse. Good examples are (here juxtaposed with their switch): --lines=n, --author=name, --image-type=rgb|gray. The string may contain simple markup which is removed when used in error messages. As a convenience, if the string looks like a lower-case variable name then it will be formatted in the documentation like a variable.
The value parser is normally created with one of the Command line parser factories. It defaults to the AnyParser, which accepts any string from the command line and stores it as an std::string.
If a default is specified then the argument will be optional and the parser will behave as if the default value string appeared on the command line at the point where the argument was expected. This also means that the default value string must be parsable as if it were truly present.
Although switches usually have either no arguments or one argument, it is possible to declare switches that have multiple arguments. This is different from a switch that occurs multiple times or from a switch that has one argument which is a list. Each switch argument must be separated from the previous switch argument by occuring in a subsequent program command line argument. E.g., --swap a b as three program arguments, or --swap=a b as two program arguments; but --swap=a,b is one switch argument that happens to look like a list, and --swap=a --swap=b is obviously two switches with one switch argument each.
◆ argument() [2/4]
| Switch& Sawyer::CommandLine::Switch::argument | ( | const std::string & | name, |
| const ValueParser::Ptr & | parser, | ||
| const std::string & | defaultValue | ||
| ) |
Property: switch argument.
A switch argument declares how text after the switch name is parsed to form a value. An argument specifier contains a name, a parser, and an optional default value.
The name is used in error messages and documentation and should be chosen to be a descriptive but terse. Good examples are (here juxtaposed with their switch): --lines=n, --author=name, --image-type=rgb|gray. The string may contain simple markup which is removed when used in error messages. As a convenience, if the string looks like a lower-case variable name then it will be formatted in the documentation like a variable.
The value parser is normally created with one of the Command line parser factories. It defaults to the AnyParser, which accepts any string from the command line and stores it as an std::string.
If a default is specified then the argument will be optional and the parser will behave as if the default value string appeared on the command line at the point where the argument was expected. This also means that the default value string must be parsable as if it were truly present.
Although switches usually have either no arguments or one argument, it is possible to declare switches that have multiple arguments. This is different from a switch that occurs multiple times or from a switch that has one argument which is a list. Each switch argument must be separated from the previous switch argument by occuring in a subsequent program command line argument. E.g., --swap a b as three program arguments, or --swap=a b as two program arguments; but --swap=a,b is one switch argument that happens to look like a list, and --swap=a --swap=b is obviously two switches with one switch argument each.
◆ argument() [3/4]
|
inline |
Property: switch argument.
A switch argument declares how text after the switch name is parsed to form a value. An argument specifier contains a name, a parser, and an optional default value.
The name is used in error messages and documentation and should be chosen to be a descriptive but terse. Good examples are (here juxtaposed with their switch): --lines=n, --author=name, --image-type=rgb|gray. The string may contain simple markup which is removed when used in error messages. As a convenience, if the string looks like a lower-case variable name then it will be formatted in the documentation like a variable.
The value parser is normally created with one of the Command line parser factories. It defaults to the AnyParser, which accepts any string from the command line and stores it as an std::string.
If a default is specified then the argument will be optional and the parser will behave as if the default value string appeared on the command line at the point where the argument was expected. This also means that the default value string must be parsable as if it were truly present.
Although switches usually have either no arguments or one argument, it is possible to declare switches that have multiple arguments. This is different from a switch that occurs multiple times or from a switch that has one argument which is a list. Each switch argument must be separated from the previous switch argument by occuring in a subsequent program command line argument. E.g., --swap a b as three program arguments, or --swap=a b as two program arguments; but --swap=a,b is one switch argument that happens to look like a list, and --swap=a --swap=b is obviously two switches with one switch argument each.
Definition at line 2300 of file util/Sawyer/CommandLine.h.
◆ argument() [4/4]
|
inline |
Property: switch argument.
A switch argument declares how text after the switch name is parsed to form a value. An argument specifier contains a name, a parser, and an optional default value.
The name is used in error messages and documentation and should be chosen to be a descriptive but terse. Good examples are (here juxtaposed with their switch): --lines=n, --author=name, --image-type=rgb|gray. The string may contain simple markup which is removed when used in error messages. As a convenience, if the string looks like a lower-case variable name then it will be formatted in the documentation like a variable.
The value parser is normally created with one of the Command line parser factories. It defaults to the AnyParser, which accepts any string from the command line and stores it as an std::string.
If a default is specified then the argument will be optional and the parser will behave as if the default value string appeared on the command line at the point where the argument was expected. This also means that the default value string must be parsable as if it were truly present.
Although switches usually have either no arguments or one argument, it is possible to declare switches that have multiple arguments. This is different from a switch that occurs multiple times or from a switch that has one argument which is a list. Each switch argument must be separated from the previous switch argument by occuring in a subsequent program command line argument. E.g., --swap a b as three program arguments, or --swap=a b as two program arguments; but --swap=a,b is one switch argument that happens to look like a list, and --swap=a --swap=b is obviously two switches with one switch argument each.
Definition at line 2301 of file util/Sawyer/CommandLine.h.
◆ arguments()
|
inline |
Property: switch argument.
A switch argument declares how text after the switch name is parsed to form a value. An argument specifier contains a name, a parser, and an optional default value.
The name is used in error messages and documentation and should be chosen to be a descriptive but terse. Good examples are (here juxtaposed with their switch): --lines=n, --author=name, --image-type=rgb|gray. The string may contain simple markup which is removed when used in error messages. As a convenience, if the string looks like a lower-case variable name then it will be formatted in the documentation like a variable.
The value parser is normally created with one of the Command line parser factories. It defaults to the AnyParser, which accepts any string from the command line and stores it as an std::string.
If a default is specified then the argument will be optional and the parser will behave as if the default value string appeared on the command line at the point where the argument was expected. This also means that the default value string must be parsable as if it were truly present.
Although switches usually have either no arguments or one argument, it is possible to declare switches that have multiple arguments. This is different from a switch that occurs multiple times or from a switch that has one argument which is a list. Each switch argument must be separated from the previous switch argument by occuring in a subsequent program command line argument. E.g., --swap a b as three program arguments, or --swap=a b as two program arguments; but --swap=a,b is one switch argument that happens to look like a list, and --swap=a --swap=b is obviously two switches with one switch argument each.
Definition at line 2302 of file util/Sawyer/CommandLine.h.
◆ nArguments()
|
inline |
Total number of arguments.
This is the total number of arguments currently declared for the switch.
Definition at line 2306 of file util/Sawyer/CommandLine.h.
◆ nRequiredArguments()
| size_t Sawyer::CommandLine::Switch::nRequiredArguments | ( | ) | const |
Number of required arguments.
This is the number of arguments which do not have default values and which therefore must appear on the command line for each occurrence of the switch.
◆ intrinsicValue() [1/6]
|
inline |
Property: value for a switch that has no declared arguments.
A switch with no declared arguments (not even optional arguments) is always parsed as if it had one argument–it's intrinsic value–the string "true" parsed and stored as type "bool" by the BooleanParser. The intrinsicValue property can specify a different value and type for the switch. For instance, --laconic and --effusive might be two switches that use the same key "verbosity" and have intrinsic values of "1" and "2" as integers (or even LACONIC and EFFUSIVE as enums).
Intrinsic values can either be supplied as a string and a parser, or as the value itself. If a value is supplied directly, then it must have a printing operator (operator<<(std::ostream, const T&)) so that its string representation can be returned if the user asks the ParserResult for it.
If a switch has at least one declared argument then this property is not consulted, even if that argument is optional and missing (in which case that argument's default value is used).
Some examples:
Definition at line 2342 of file util/Sawyer/CommandLine.h.
References Sawyer::CommandLine::NOWHERE.
◆ intrinsicValue() [2/6]
|
inline |
Property: value for a switch that has no declared arguments.
A switch with no declared arguments (not even optional arguments) is always parsed as if it had one argument–it's intrinsic value–the string "true" parsed and stored as type "bool" by the BooleanParser. The intrinsicValue property can specify a different value and type for the switch. For instance, --laconic and --effusive might be two switches that use the same key "verbosity" and have intrinsic values of "1" and "2" as integers (or even LACONIC and EFFUSIVE as enums).
Intrinsic values can either be supplied as a string and a parser, or as the value itself. If a value is supplied directly, then it must have a printing operator (operator<<(std::ostream, const T&)) so that its string representation can be returned if the user asks the ParserResult for it.
If a switch has at least one declared argument then this property is not consulted, even if that argument is optional and missing (in which case that argument's default value is used).
Some examples:
Definition at line 2346 of file util/Sawyer/CommandLine.h.
References Sawyer::CommandLine::NOWHERE.
◆ intrinsicValue() [3/6]
|
inline |
Property: value for a switch that has no declared arguments.
A switch with no declared arguments (not even optional arguments) is always parsed as if it had one argument–it's intrinsic value–the string "true" parsed and stored as type "bool" by the BooleanParser. The intrinsicValue property can specify a different value and type for the switch. For instance, --laconic and --effusive might be two switches that use the same key "verbosity" and have intrinsic values of "1" and "2" as integers (or even LACONIC and EFFUSIVE as enums).
Intrinsic values can either be supplied as a string and a parser, or as the value itself. If a value is supplied directly, then it must have a printing operator (operator<<(std::ostream, const T&)) so that its string representation can be returned if the user asks the ParserResult for it.
If a switch has at least one declared argument then this property is not consulted, even if that argument is optional and missing (in which case that argument's default value is used).
Some examples:
Definition at line 2350 of file util/Sawyer/CommandLine.h.
References Sawyer::CommandLine::NOWHERE, and Sawyer::CommandLine::ParsedValue::valueLocation().
◆ intrinsicValue() [4/6]
|
inline |
Property: value for a switch that has no declared arguments.
A switch with no declared arguments (not even optional arguments) is always parsed as if it had one argument–it's intrinsic value–the string "true" parsed and stored as type "bool" by the BooleanParser. The intrinsicValue property can specify a different value and type for the switch. For instance, --laconic and --effusive might be two switches that use the same key "verbosity" and have intrinsic values of "1" and "2" as integers (or even LACONIC and EFFUSIVE as enums).
Intrinsic values can either be supplied as a string and a parser, or as the value itself. If a value is supplied directly, then it must have a printing operator (operator<<(std::ostream, const T&)) so that its string representation can be returned if the user asks the ParserResult for it.
If a switch has at least one declared argument then this property is not consulted, even if that argument is optional and missing (in which case that argument's default value is used).
Some examples:
Definition at line 2355 of file util/Sawyer/CommandLine.h.
References Sawyer::CommandLine::anyParser(), Sawyer::CommandLine::NOWHERE, and Sawyer::CommandLine::ParsedValue::valueLocation().
◆ intrinsicValue() [5/6]
|
inline |
Property: value for a switch that has no declared arguments.
A switch with no declared arguments (not even optional arguments) is always parsed as if it had one argument–it's intrinsic value–the string "true" parsed and stored as type "bool" by the BooleanParser. The intrinsicValue property can specify a different value and type for the switch. For instance, --laconic and --effusive might be two switches that use the same key "verbosity" and have intrinsic values of "1" and "2" as integers (or even LACONIC and EFFUSIVE as enums).
Intrinsic values can either be supplied as a string and a parser, or as the value itself. If a value is supplied directly, then it must have a printing operator (operator<<(std::ostream, const T&)) so that its string representation can be returned if the user asks the ParserResult for it.
If a switch has at least one declared argument then this property is not consulted, even if that argument is optional and missing (in which case that argument's default value is used).
Some examples:
Definition at line 2360 of file util/Sawyer/CommandLine.h.
◆ intrinsicValue() [6/6]
|
inline |
Property: value for a switch that has no declared arguments.
A switch with no declared arguments (not even optional arguments) is always parsed as if it had one argument–it's intrinsic value–the string "true" parsed and stored as type "bool" by the BooleanParser. The intrinsicValue property can specify a different value and type for the switch. For instance, --laconic and --effusive might be two switches that use the same key "verbosity" and have intrinsic values of "1" and "2" as integers (or even LACONIC and EFFUSIVE as enums).
Intrinsic values can either be supplied as a string and a parser, or as the value itself. If a value is supplied directly, then it must have a printing operator (operator<<(std::ostream, const T&)) so that its string representation can be returned if the user asks the ParserResult for it.
If a switch has at least one declared argument then this property is not consulted, even if that argument is optional and missing (in which case that argument's default value is used).
Some examples:
Definition at line 2361 of file util/Sawyer/CommandLine.h.
◆ explosiveLists() [1/2]
|
inline |
Property: whether to convert a list value to individual values.
The ListParser returns a single value of type ListParser::ValueList, an std::list containing parsed values. If the explodeLists property is true, then each switch argument that is a ListParser::ValueList is exploded into multiple switch arguments.
This is useful for switches that can either occur multiple times on the command-line or take a list as an argument, such as GCC's -I switch, where -Ia:b:c is the same as -Ia -Ib -Ic. It is also useful when one wants to store a list argument in a user-supplied std::vector during the ParserResult::apply call. Here's an example that stores the aforementioned -I switch arguments in a vector:
If the explosiveLists property was false (its default) and the command line was -Ia:b:c, then the library would try to store a ListParser::ValueList as the first element of includeDirectories, resulting in an std::runtime_error regarding an invalid type conversion.
Definition at line 2386 of file util/Sawyer/CommandLine.h.
◆ explosiveLists() [2/2]
|
inline |
Property: whether to convert a list value to individual values.
The ListParser returns a single value of type ListParser::ValueList, an std::list containing parsed values. If the explodeLists property is true, then each switch argument that is a ListParser::ValueList is exploded into multiple switch arguments.
This is useful for switches that can either occur multiple times on the command-line or take a list as an argument, such as GCC's -I switch, where -Ia:b:c is the same as -Ia -Ib -Ic. It is also useful when one wants to store a list argument in a user-supplied std::vector during the ParserResult::apply call. Here's an example that stores the aforementioned -I switch arguments in a vector:
If the explosiveLists property was false (its default) and the command line was -Ia:b:c, then the library would try to store a ListParser::ValueList as the first element of includeDirectories, resulting in an std::runtime_error regarding an invalid type conversion.
Definition at line 2387 of file util/Sawyer/CommandLine.h.
◆ action() [1/2]
|
inline |
Property: action to occur.
Each switch may define an action that will be called by ParserResult::apply. When a switch is recognized on the command line and added to the ParserResult eventually returned by Parser::parse, an optional action functor is saved.
Actions are associted with the key of parsed switches, with at most one action per key–the last action (or non-action if null) for a key is the one which is saved in the ParserResult for that key. In other words, if two switches share the same key but have two different actions, the action for the switch that's parsed last will be the action called by ParserResult::apply. A switch with a null action, when recognized on the command-line, cancels any action that was previously associated with the same key in the ParserResult from a previously recognized switch.
The library provides a few actions, all of which are derived from SwitchAction, and the user can provide additional actions. For instance, two commonly used switches are:
Definition at line 2411 of file util/Sawyer/CommandLine.h.
◆ action() [2/2]
|
inline |
Property: action to occur.
Each switch may define an action that will be called by ParserResult::apply. When a switch is recognized on the command line and added to the ParserResult eventually returned by Parser::parse, an optional action functor is saved.
Actions are associted with the key of parsed switches, with at most one action per key–the last action (or non-action if null) for a key is the one which is saved in the ParserResult for that key. In other words, if two switches share the same key but have two different actions, the action for the switch that's parsed last will be the action called by ParserResult::apply. A switch with a null action, when recognized on the command-line, cancels any action that was previously associated with the same key in the ParserResult from a previously recognized switch.
The library provides a few actions, all of which are derived from SwitchAction, and the user can provide additional actions. For instance, two commonly used switches are:
Definition at line 2412 of file util/Sawyer/CommandLine.h.
◆ whichValue() [1/2]
|
inline |
Property: how to handle multiple occurrences.
Describes what to do if a switch occurs more than once. Normally, if a switch occurs more than once on the command line then only its final value is made available in the parser result since this is usually what one wants for most switches. The whichValue property can be adjusted to change this behavior (see documentation for the WhichValue enumeration for possibilities). The SAVE_AUGMENTED mode also needs a valueAugmenter, otherwise it behaves the same as SAVE_LAST.
The whichValue property is applied per switch occurrence, but applied using the switch's key, which it may share with other switches. For example, if two switches, "foo1" and "foo2" both use the key "foo" and both have the SAVE_ONE mode, then an error will be raised if the command line is --foo1 --foo2. But if "foo1" uses SAVE_ONE and "foo2" uses SAVE_ALL, then no error is raised because at the point in the command line when the --foo1 occurrence is checked, --foo2 hasn't occurred yet.
A switch that has a list value (i.e., from ListParser) is treated as having a single value per occurrence, but if the list is exploded (explosiveLists) then it will be treated as if the switch occurred more than once. In other words, SAVE_ONE will not normaly raise an error for an occurrence like --foo=a,b,c because it's considered to be a single value (a single list), but would cause an error if the list were exploded into three values since the exploding makes the command line look more like --foo=a --foo=b --foo=c.
Single letter switches that are nestled and repeated, like the somewhat common debug switch where more occurrences means more debugging output, like -d for a little debugging versus -ddd for extensive debugging, are counted as individual switches: -ddd is equivalent to -d -d -d.
If a switch with SAVE_LAST is processed, it deletes all the previously saved values for the same key even if they came from other switches having the same key but not the same SAVE_LAST configuration.
Definition at line 2440 of file util/Sawyer/CommandLine.h.
◆ whichValue() [2/2]
|
inline |
Property: how to handle multiple occurrences.
Describes what to do if a switch occurs more than once. Normally, if a switch occurs more than once on the command line then only its final value is made available in the parser result since this is usually what one wants for most switches. The whichValue property can be adjusted to change this behavior (see documentation for the WhichValue enumeration for possibilities). The SAVE_AUGMENTED mode also needs a valueAugmenter, otherwise it behaves the same as SAVE_LAST.
The whichValue property is applied per switch occurrence, but applied using the switch's key, which it may share with other switches. For example, if two switches, "foo1" and "foo2" both use the key "foo" and both have the SAVE_ONE mode, then an error will be raised if the command line is --foo1 --foo2. But if "foo1" uses SAVE_ONE and "foo2" uses SAVE_ALL, then no error is raised because at the point in the command line when the --foo1 occurrence is checked, --foo2 hasn't occurred yet.
A switch that has a list value (i.e., from ListParser) is treated as having a single value per occurrence, but if the list is exploded (explosiveLists) then it will be treated as if the switch occurred more than once. In other words, SAVE_ONE will not normaly raise an error for an occurrence like --foo=a,b,c because it's considered to be a single value (a single list), but would cause an error if the list were exploded into three values since the exploding makes the command line look more like --foo=a --foo=b --foo=c.
Single letter switches that are nestled and repeated, like the somewhat common debug switch where more occurrences means more debugging output, like -d for a little debugging versus -ddd for extensive debugging, are counted as individual switches: -ddd is equivalent to -d -d -d.
If a switch with SAVE_LAST is processed, it deletes all the previously saved values for the same key even if they came from other switches having the same key but not the same SAVE_LAST configuration.
Definition at line 2441 of file util/Sawyer/CommandLine.h.
◆ valueAugmenter() [1/2]
|
inline |
Property: functor to agument values.
This is the functor that is called to augment a previously parsed values by merging them with newly parsed values. The whichValue property must be SAVE_AUGMENTED in order for the specified functor to be invoked.
- See also
Definition at line 2452 of file util/Sawyer/CommandLine.h.
◆ valueAugmenter() [2/2]
|
inline |
Property: functor to agument values.
This is the functor that is called to augment a previously parsed values by merging them with newly parsed values. The whichValue property must be SAVE_AUGMENTED in order for the specified functor to be invoked.
- See also
Definition at line 2453 of file util/Sawyer/CommandLine.h.
The documentation for this class was generated from the following file:
