Description
A collection of related switch declarations.
A switch group is an important concept in that it allows different software components to declare their own command lines, and those declarations can be used by some higher layer. The higher layer builds a parser from the various switch groups in order to simultaneously parse switches for all the software components.
In order to help avoid conflicting switches when inserting these parts (switch groups) into a parser, each switch group can have a name. A switch group's name is an optional string that can be inserted at the beginning of long switches to disambiguate them from switches with the same name in other groups. For instance, if groups with the names "output" and "input" both have a long switch "--tab-width" then the user will (by default) get an error if they specify "--tab-width" on the command-line. The error message will indicate they should use either "--output-tab-width" or "--input-tab-width". The documentation, typically generated by "--help", describes the switches like "--[output-]tab-width", but authors may override the switch synopsis with their own string. Group names are only used to disambiguate long switches, not single-letter switches. A switch group name is different than the switch group title or dockey.
Tools that are unable to simultaneously parse on behalf of multiple software components (presumably because they're not using this library), sometimes run into problems where the argument for a switch which is not part of the current parsing language looks like a valid switch in the current language. Consider a tool that uses single-hyphen prefixes for its long switches and has a switch name "go" that takes an argument, and lets say that this tool must also accept all the switches for the find(1) command but it doesn't actually know them–it just passes along all command line arguments it doesn't recognize to the find-like software component. If the command line contained -perm -go=w -print then the tool will extract the -go=w switch that it recognizes, and pass along -perm -print to the other component component. Unfortunately, the -go=w that it recognized as its own was actually the argument for the -perm switch that it didn't recognize.
When creating a switch group, switch declarations (Switch) are copied into the switch group. Eventually the switch group itself is copied into a parser.
Definition at line 2569 of file util/Sawyer/CommandLine.h.
#include <CommandLine.h>
Public Member Functions | |
| SwitchGroup () | |
| Construct an unnamed, untitled group. | |
| SwitchGroup (const std::string &title, const std::string &docKey="") | |
| Construct a titled group. More... | |
| size_t | nSwitches () const |
| Number of switches declared. | |
| const std::vector< Switch > & | switches () const |
| List of all declared switches. More... | |
| bool | nameExists (const std::string &switchName) |
| Returns true if a switch with the specified name exists. More... | |
| const Switch & | getByName (const std::string &switchName) |
| Returns the first switch with the specified name. More... | |
| bool | keyExists (const std::string &switchKey) |
| Returns true if a switch with the specified key exists. | |
| const Switch & | getByKey (const std::string &switchKey) |
| Returns the first switch with the specified key. More... | |
| SwitchGroup & | insert (const Switch &) |
| Insert a switch into the group. More... | |
| SwitchGroup & | insert (const SwitchGroup &) |
| Insert switches from another group into this one. More... | |
| SwitchGroup & | removeByIndex (size_t n) |
| Remove a switch from the group. More... | |
| SwitchGroup & | removeByName (const std::string &switchName) |
| Remove a switch from the group. More... | |
| SwitchGroup & | removeByKey (const std::string &switchKey) |
| Remove a switch from the group. More... | |
| const ParsingProperties & | properties () const |
| const std::string & | title () const |
| Property: Title of the switch group. More... | |
| SwitchGroup & | title (const std::string &title) |
| Property: Title of the switch group. More... | |
| const std::string & | name () const |
| Property: Group name. More... | |
| SwitchGroup & | name (const std::string &name) |
| Property: Group name. More... | |
| const std::string & | docKey () const |
| Property: Documentation sort key. More... | |
| SwitchGroup & | docKey (const std::string &key) |
| Property: Documentation sort key. More... | |
| SwitchGroup & | doc (const std::string &s) |
| Property: Detailed description. More... | |
| const std::string & | doc () const |
| Property: Detailed description. More... | |
| ShowGroupName | showingGroupNames () const |
| Property: How to show group name in switch synopsis. More... | |
| void | showingGroupNames (ShowGroupName x) |
| Property: How to show group name in switch synopsis. More... | |
| SwitchGroup & | 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... | |
| SwitchGroup & | longPrefix (const std::string &s1) |
| Property: prefixes for long names. More... | |
| const std::vector< std::string > & | longPrefixes () const |
| Property: prefixes for long names. More... | |
| SwitchGroup & | 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... | |
| SwitchGroup & | shortPrefix (const std::string &s1) |
| Property: prefixes for short names. More... | |
| const std::vector< std::string > & | shortPrefixes () const |
| Property: prefixes for short names. More... | |
| SwitchGroup & | 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... | |
| SwitchGroup & | 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... | |
| const SortOrder & | switchOrder () const |
| Property: Order of switches in documentation. More... | |
| SwitchGroup & | switchOrder (SortOrder order) |
| Property: Order of switches in documentation. More... | |
Constructor & Destructor Documentation
◆ SwitchGroup()
|
inlineexplicit |
Construct a titled group.
Titling a group prevents its switches from being globally sorted with other groups when the documentation is produced. The title will appear as the title of a subsection for the switches and should be capitalized like a title (initial capital letters). The optional docKey is used to sort the groups in relation to each other (the default is to sort by group title).
Definition at line 2589 of file util/Sawyer/CommandLine.h.
Member Function Documentation
◆ title() [1/2]
|
inline |
Property: Title of the switch group.
A switch group may have a subsection title for documentation. The title should be capitalized like a title. The title may also be specified in the constructor.
Definition at line 2597 of file util/Sawyer/CommandLine.h.
◆ title() [2/2]
|
inline |
Property: Title of the switch group.
A switch group may have a subsection title for documentation. The title should be capitalized like a title. The title may also be specified in the constructor.
Definition at line 2598 of file util/Sawyer/CommandLine.h.
References title().
Referenced by title().
◆ name() [1/2]
|
inline |
Property: Group name.
A switch group may have a name in order to disambiguate command-line switches that match more than one switch declaration. This is useful if a user is constructing a parser from switch groups over which they have no control. For example, if two groups have a "--foo" switch then the user can give one group a name of "alpha" and the other "beta" in which case "--alpha:foo" matches one and "--beta:foo" matches the other.
Names can only resolve long switches, not short switches.
Definition at line 2611 of file util/Sawyer/CommandLine.h.
◆ name() [2/2]
|
inline |
Property: Group name.
A switch group may have a name in order to disambiguate command-line switches that match more than one switch declaration. This is useful if a user is constructing a parser from switch groups over which they have no control. For example, if two groups have a "--foo" switch then the user can give one group a name of "alpha" and the other "beta" in which case "--alpha:foo" matches one and "--beta:foo" matches the other.
Names can only resolve long switches, not short switches.
Definition at line 2612 of file util/Sawyer/CommandLine.h.
References name().
Referenced by name().
◆ docKey() [1/2]
|
inline |
Property: Documentation sort key.
This key is used to order the switch groups with respect to one another in the documentation. Switches that belong to groups having the same documentation key are treated as if they came from the same group for the purpose of sorting the switches within groups. Any switch group that has no documentation key will use the lower-case group title (which may also be the empty string). If more than one switch group has the same documentation key but different titles, then only one of those titles is arbitrarily chosen as the subsection title in the documentation.
The documentation key may also be specified in the constructor.
- See also
- SwitchGroup::switchOrder
Definition at line 2627 of file util/Sawyer/CommandLine.h.
◆ docKey() [2/2]
|
inline |
Property: Documentation sort key.
This key is used to order the switch groups with respect to one another in the documentation. Switches that belong to groups having the same documentation key are treated as if they came from the same group for the purpose of sorting the switches within groups. Any switch group that has no documentation key will use the lower-case group title (which may also be the empty string). If more than one switch group has the same documentation key but different titles, then only one of those titles is arbitrarily chosen as the subsection title in the documentation.
The documentation key may also be specified in the constructor.
- See also
- SwitchGroup::switchOrder
Definition at line 2628 of file util/Sawyer/CommandLine.h.
◆ doc() [1/2]
|
inline |
Property: Detailed description.
This is the description of the switch group in a simple markup language. See Switch::doc for a description of the markup language. Documentation for a switch group will appear prior to the switches within that group. If multiple groups are to appear in the same section of the manual page (by virtue of having the same SwitchGroup::title then their documentation strings are appended as separate paragraphs in the order that the switch groups appear in the parser.
Documentation specified by this property is in addition to automatically generated documentation for the switches within this group.
Definition at line 2643 of file util/Sawyer/CommandLine.h.
◆ doc() [2/2]
|
inline |
Property: Detailed description.
This is the description of the switch group in a simple markup language. See Switch::doc for a description of the markup language. Documentation for a switch group will appear prior to the switches within that group. If multiple groups are to appear in the same section of the manual page (by virtue of having the same SwitchGroup::title then their documentation strings are appended as separate paragraphs in the order that the switch groups appear in the parser.
Documentation specified by this property is in addition to automatically generated documentation for the switches within this group.
Definition at line 2644 of file util/Sawyer/CommandLine.h.
◆ showingGroupNames() [1/2]
|
inline |
Property: How to show group name in switch synopsis.
A switch group can override how the group name appears in a switch synopsis. The default is to inherit the setting from the parser containing the group at the time of documentation.
Definition at line 2653 of file util/Sawyer/CommandLine.h.
◆ showingGroupNames() [2/2]
|
inline |
Property: How to show group name in switch synopsis.
A switch group can override how the group name appears in a switch synopsis. The default is to inherit the setting from the parser containing the group at the time of documentation.
Definition at line 2654 of file util/Sawyer/CommandLine.h.
◆ resetLongPrefixes()
| SwitchGroup& Sawyer::CommandLine::SwitchGroup::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 2661 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 2662 of file util/Sawyer/CommandLine.h.
◆ resetShortPrefixes()
| SwitchGroup& Sawyer::CommandLine::SwitchGroup::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 2669 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 2670 of file util/Sawyer/CommandLine.h.
◆ resetValueSeparators()
| SwitchGroup& Sawyer::CommandLine::SwitchGroup::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 2677 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 2678 of file util/Sawyer/CommandLine.h.
◆ switches()
|
inline |
List of all declared switches.
The return value contains the switch declarations in the order they were inserted into this switch group.
Definition at line 2686 of file util/Sawyer/CommandLine.h.
◆ nameExists()
| bool Sawyer::CommandLine::SwitchGroup::nameExists | ( | const std::string & | switchName | ) |
Returns true if a switch with the specified name exists.
Both long and short names are checked.
◆ getByName()
| const Switch& Sawyer::CommandLine::SwitchGroup::getByName | ( | const std::string & | switchName | ) |
Returns the first switch with the specified name.
Both long and short names are checked. Throws an exception if no switch with that name exists.
◆ getByKey()
| const Switch& Sawyer::CommandLine::SwitchGroup::getByKey | ( | const std::string & | switchKey | ) |
Returns the first switch with the specified key.
Throws an exception if no switch exists having that key.
◆ insert() [1/2]
| SwitchGroup& Sawyer::CommandLine::SwitchGroup::insert | ( | const Switch & | ) |
Insert a switch into the group.
The switch declaration is copied into the group.
◆ insert() [2/2]
| SwitchGroup& Sawyer::CommandLine::SwitchGroup::insert | ( | const SwitchGroup & | ) |
Insert switches from another group into this one.
Other properties are not copied.
◆ removeByIndex()
| SwitchGroup& Sawyer::CommandLine::SwitchGroup::removeByIndex | ( | size_t | n | ) |
Remove a switch from the group.
The nth switch is removed, as returned by switches.
◆ removeByName()
| SwitchGroup& Sawyer::CommandLine::SwitchGroup::removeByName | ( | const std::string & | switchName | ) |
Remove a switch from the group.
The first declaration with the specified name is erased from this group. Both long and short names are checked.
◆ removeByKey()
| SwitchGroup& Sawyer::CommandLine::SwitchGroup::removeByKey | ( | const std::string & | switchKey | ) |
Remove a switch from the group.
The first declaration with the specified key is erased from this group.
◆ switchOrder() [1/2]
|
inline |
Property: Order of switches in documentation.
This property controls the sorting of keys within the group. If the property's value is DOCKEY_ORDER, the default, then switches are sorted according to the Switch::docKey values; if the property is INSERTION_ORDER then switch documentation keys are ignored and switches are presented in the order they were added to the group.
Since documentation will combine into a single subsection all the switches from groups having the same title, it is possible that the subsection will have conflicting orderings. When this happens, the last group to be inserted is the one whose value is used for the entire subsection.
- See also
- SwitchGroup::docKey
Definition at line 2728 of file util/Sawyer/CommandLine.h.
◆ switchOrder() [2/2]
|
inline |
Property: Order of switches in documentation.
This property controls the sorting of keys within the group. If the property's value is DOCKEY_ORDER, the default, then switches are sorted according to the Switch::docKey values; if the property is INSERTION_ORDER then switch documentation keys are ignored and switches are presented in the order they were added to the group.
Since documentation will combine into a single subsection all the switches from groups having the same title, it is possible that the subsection will have conflicting orderings. When this happens, the last group to be inserted is the one whose value is used for the entire subsection.
- See also
- SwitchGroup::docKey
Definition at line 2729 of file util/Sawyer/CommandLine.h.
The documentation for this class was generated from the following file:
