ROSE  0.11.96.11
Public Types | Public Member Functions | Static Public Member Functions | List of all members
Sawyer::CommandLine::Parser Class Reference

Description

The parser for a program command line.

A parser is configured to describe the valid program switches, their arguments, and other information, and then the parser is then applied to a program command line to return a ParserResult. The process of parsing a command line is free of side-effects other than creating the result.

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

#include <CommandLine.h>

Public Types

enum  GroupingFlags {
  DEFAULT_GROUPING = 0,
  PROHIBIT_EMPTY_GROUPS = 0x0001,
  SPLIT_SINGLE_GROUP = 0x0002
}
 Bit flags for argument grouping. More...
 

Public Member Functions

 Parser ()
 Default constructor. More...
 
bool switchGroupExists (const std::string &name) const
 Predicate to determine whether a switch group exists. More...
 
bool eraseSwitchGroup (const std::string &name)
 Remove switch group from parser. More...
 
ParserResult parse (int argc, char *argv[])
 Parse program arguments. More...
 
ParserResult parse (const std::vector< std::string > &)
 Parse program arguments. More...
 
std::vector< std::string > expandIncludedFiles (const std::vector< std::string > &args)
 Expand file arguments. More...
 
std::vector< std::vector< std::string > > regroupArgs (const std::vector< std::string > &args, const Container::Interval< size_t > &limits=Container::Interval< size_t >::whole(), unsigned flags=0)
 Group arguments by "--" separators. More...
 
std::string documentationMarkup () const
 Full documentation. More...
 
std::string podDocumentation () const
 Generate Perl POD documentation. More...
 
std::string textDocumentation () const
 Generate plain text documentation.
 
void emitDocumentationToPager () const
 Print documentation to standard output. More...
 
template<class Grammar >
void emitDocumentationToPager () const
 
void insertLongSwitchStrings (Canonical, NamedSwitches &index) const
 Insert records for long switch strings. More...
 
void insertShortSwitchStrings (NamedSwitches &index) const
 Insert records for short switch strings. More...
 
void insertSwitchStrings (Canonical, NamedSwitches &index) const
 Insert records for long and short switch strings. More...
 
NamedSwitches findAmbiguities () const
 Find switch string ambiguities. More...
 
NamedSwitches findUnresolvableAmbiguities () const
 Find unresolvable switch string ambiguities. More...
 
const ParsingPropertiesproperties () const
 
Parserwith (const SwitchGroup &sg)
 Add switch declarations. More...
 
Parserwith (const SwitchGroup &sg, const std::string &docKey)
 Add switch declarations. More...
 
Parserwith (const std::vector< SwitchGroup > &sgs)
 Add switch declarations. More...
 
Parserwith (const Switch &sw)
 Add switch declarations. More...
 
Parserwith (Switch sw, const std::string &docKey)
 Add switch declarations. More...
 
const std::vector< SwitchGroup > & switchGroups () const
 List of all switch groups.
 
std::vector< SwitchGroup > & switchGroups ()
 List of all switch groups.
 
const SwitchGroupswitchGroup (const std::string &name) const
 Switch group having specified name. More...
 
SwitchGroupswitchGroup (const std::string &name)
 Switch group having specified name. More...
 
bool reportingAmbiguities () const
 Property: Whether to report ambiguities. More...
 
ParserreportingAmbiguities (bool b)
 Property: Whether to report ambiguities. More...
 
const std::string & groupNameSeparator () const
 Property: String separating group name from switch name. More...
 
ParsergroupNameSeparator (const std::string &s)
 Property: String separating group name from switch name. More...
 
ShowGroupName showingGroupNames () const
 Property: How to show group names in switch documentation. More...
 
ParsershowingGroupNames (ShowGroupName x)
 Property: How to show group names in switch documentation. More...
 
ParserresetLongPrefixes (const std::string &s1=STR_NONE, const std::string &s2=STR_NONE, const std::string &s3=STR_NONE, const std::string &s4=STR_NONE)
 Prefixes to use for long command-line switches. More...
 
ParserlongPrefix (const std::string &s1)
 Prefixes to use for long command-line switches. More...
 
const std::vector< std::string > & longPrefixes () const
 Prefixes to use for long command-line switches. More...
 
ParserresetShortPrefixes (const std::string &s1=STR_NONE, const std::string &s2=STR_NONE, const std::string &s3=STR_NONE, const std::string &s4=STR_NONE)
 Prefixes to use for short command-line switches. More...
 
ParsershortPrefix (const std::string &s1)
 Prefixes to use for short command-line switches. More...
 
const std::vector< std::string > & shortPrefixes () const
 Prefixes to use for short command-line switches. More...
 
ParserresetValueSeparators (const std::string &s1=STR_NONE, const std::string &s2=STR_NONE, const std::string &s3=STR_NONE, const std::string &s4=STR_NONE)
 Strings that separate a long switch from its value. More...
 
ParservalueSeparator (const std::string &s1)
 Strings that separate a long switch from its value. More...
 
const std::vector< std::string > & valueSeparators () const
 Strings that separate a long switch from its value. More...
 
ParserresetTerminationSwitches (const std::string &s1=STR_NONE, const std::string &s2=STR_NONE, const std::string &s3=STR_NONE, const std::string &s4=STR_NONE)
 Strings that indicate the end of the argument list. More...
 
ParserterminationSwitch (const std::string &s1)
 Strings that indicate the end of the argument list. More...
 
const std::vector< std::string > & terminationSwitches () const
 Strings that indicate the end of the argument list. More...
 
ParsershortMayNestle (bool b)
 Indicates whether short switches can nestle together. More...
 
bool shortMayNestle () const
 Indicates whether short switches can nestle together. More...
 
ParserresetInclusionPrefixes (const std::string &s1=STR_NONE, const std::string &s2=STR_NONE, const std::string &s3=STR_NONE, const std::string &s4=STR_NONE)
 Strings that indicate that arguments are to be read from a file. More...
 
ParserinclusionPrefix (const std::string &s1)
 Strings that indicate that arguments are to be read from a file. More...
 
const std::vector< std::string > & inclusionPrefixes () const
 Strings that indicate that arguments are to be read from a file. More...
 
ParserskippingNonSwitches (bool b)
 Whether to skip over non-switch arguments when parsing. More...
 
bool skippingNonSwitches () const
 Whether to skip over non-switch arguments when parsing. More...
 
ParserskippingUnknownSwitches (bool b)
 Whether to skip over unrecognized switches. More...
 
bool skippingUnknownSwitches () const
 Whether to skip over unrecognized switches. More...
 
ParsererrorStream (const Message::SProxy &stream)
 Specifies a message stream to which errors are sent. More...
 
const Message::SProxyerrorStream () const
 Specifies a message stream to which errors are sent. More...
 
ParserexitMessage (const std::string &s)
 Extra text to print before exit. More...
 
std::string exitMessage () const
 Extra text to print before exit. More...
 
ParserenvironmentVariable (const std::string &s)
 Name of environment variable holding initial arguments. More...
 
const std::string & environmentVariable () const
 Name of environment variable holding initial arguments. More...
 
ParserprogramName (const std::string &programName)
 Program name for documentation. More...
 
const std::string & programName () const
 Program name for documentation. More...
 
Parserpurpose (const std::string &purpose)
 Program purpose. More...
 
const std::string & purpose () const
 Program purpose. More...
 
Parserversion (const std::string &versionString, const std::string &dateString="")
 Program version. More...
 
Parserversion (const std::pair< std::string, std::string > &p)
 Program version. More...
 
std::pair< std::string, std::string > version () const
 Program version. More...
 
Parserchapter (int chapterNumber, const std::string &chapterName="")
 Manual chapter. More...
 
Parserchapter (const std::pair< int, std::string > &p)
 Manual chapter. More...
 
std::pair< int, std::string > chapter () const
 Manual chapter. More...
 
Parserdoc (const std::string &sectionName, const std::string &docKey, const std::string &text)
 Documentation for a section of the manual. More...
 
Parserdoc (const std::string &sectionName, const std::string &text)
 Documentation for a section of the manual. More...
 
std::vector< std::string > docSections () const
 Documentation for a section of the manual. More...
 
std::string docForSwitches () const
 Documentation for a section of the manual. More...
 
std::string docForSection (const std::string &sectionName) const
 Documentation for a section of the manual. More...
 
SortOrder switchGroupOrder () const
 Property: How to order switch groups in documentation. More...
 
ParserswitchGroupOrder (SortOrder order)
 Property: How to order switch groups in documentation. More...
 
Sawyer::Optional< SwitchremoveMatchingSwitch (const std::string &arg)
 Remove the switch by matching parse sentence. More...
 
Sawyer::Optional< SwitchremoveMatchingSwitch (const std::vector< std::string > &args)
 Remove the switch by matching parse sentence. More...
 

Static Public Member Functions

static std::vector< std::string > splitLineIntoWords (std::string)
 Split line of text into words. More...
 
static std::vector< std::string > readArgsFromFile (const std::string &filename)
 Read a text file to obtain arguments. More...
 
static std::vector< std::string > readArgsFromEnvVar (const std::string &varName)
 Read an envrionment variable to obtain arguments. More...
 
static void printIndex (std::ostream &, const NamedSwitches &, const std::string &linePrefix="")
 Print a switch index. More...
 

Member Enumeration Documentation

◆ GroupingFlags

Bit flags for argument grouping.

See regroupArgs.

Enumerator
DEFAULT_GROUPING 

Zero, all flags are clear.

PROHIBIT_EMPTY_GROUPS 

Error if any group is empty.

SPLIT_SINGLE_GROUP 

Split single group into singleton groups.

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

Constructor & Destructor Documentation

◆ Parser()

Sawyer::CommandLine::Parser::Parser ( )
inline

Default constructor.

The default constructor sets up a new parser with defaults suitable for the operating system. The switch declarations need to be added (via with) before the parser is useful.

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

Member Function Documentation

◆ with() [1/5]

Parser& Sawyer::CommandLine::Parser::with ( const SwitchGroup sg)
inline

Add switch declarations.

The specified switch declaration or group of switch declarations is copied into the parser. A documentation key can be supplied to override the sort order for the group or switch.

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

◆ with() [2/5]

Parser& Sawyer::CommandLine::Parser::with ( const SwitchGroup sg,
const std::string &  docKey 
)
inline

Add switch declarations.

The specified switch declaration or group of switch declarations is copied into the parser. A documentation key can be supplied to override the sort order for the group or switch.

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

◆ with() [3/5]

Parser& Sawyer::CommandLine::Parser::with ( const std::vector< SwitchGroup > &  sgs)
inline

Add switch declarations.

The specified switch declaration or group of switch declarations is copied into the parser. A documentation key can be supplied to override the sort order for the group or switch.

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

◆ with() [4/5]

Parser& Sawyer::CommandLine::Parser::with ( const Switch sw)
inline

Add switch declarations.

The specified switch declaration or group of switch declarations is copied into the parser. A documentation key can be supplied to override the sort order for the group or switch.

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

◆ with() [5/5]

Parser& Sawyer::CommandLine::Parser::with ( Switch  sw,
const std::string &  docKey 
)
inline

Add switch declarations.

The specified switch declaration or group of switch declarations is copied into the parser. A documentation key can be supplied to override the sort order for the group or switch.

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

References Sawyer::CommandLine::Switch::docKey().

Here is the call graph for this function:

◆ switchGroupExists()

bool Sawyer::CommandLine::Parser::switchGroupExists ( const std::string &  name) const

Predicate to determine whether a switch group exists.

Searches this parser for a switch group having the specified name and returns true if it exists.

◆ switchGroup() [1/2]

const SwitchGroup& Sawyer::CommandLine::Parser::switchGroup ( const std::string &  name) const

Switch group having specified name.

Searches this parser and returns the first switch group having the specified name. Throws a Sawyer::Exception::NotFound error if no such SwitchGroup exists in this parser.

◆ switchGroup() [2/2]

SwitchGroup& Sawyer::CommandLine::Parser::switchGroup ( const std::string &  name)

Switch group having specified name.

Searches this parser and returns the first switch group having the specified name. Throws a Sawyer::Exception::NotFound error if no such SwitchGroup exists in this parser.

◆ eraseSwitchGroup()

bool Sawyer::CommandLine::Parser::eraseSwitchGroup ( const std::string &  name)

Remove switch group from parser.

Removes the first switch group having the specified name from this parser. Returns true if a switch group was removed, false if nothing was removed.

◆ reportingAmbiguities() [1/2]

bool Sawyer::CommandLine::Parser::reportingAmbiguities ( ) const
inline

Property: Whether to report ambiguities.

If true, report ambiguous switches. Switches that can not be disambiguated are reported regardless of whether the switch is encountered on a commandline in order to help authors detect situations where it's impossible to control some setting from the command line. Switches that can be disambiguated are reported only when they occur on the commandline, and include a message about how to disambiguate them.

If false, then no ambiguities are checked or reported. When encountering an ambiguous switch, the first matching definition is used.

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

◆ reportingAmbiguities() [2/2]

Parser& Sawyer::CommandLine::Parser::reportingAmbiguities ( bool  b)
inline

Property: Whether to report ambiguities.

If true, report ambiguous switches. Switches that can not be disambiguated are reported regardless of whether the switch is encountered on a commandline in order to help authors detect situations where it's impossible to control some setting from the command line. Switches that can be disambiguated are reported only when they occur on the commandline, and include a message about how to disambiguate them.

If false, then no ambiguities are checked or reported. When encountering an ambiguous switch, the first matching definition is used.

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

◆ groupNameSeparator() [1/2]

const std::string& Sawyer::CommandLine::Parser::groupNameSeparator ( ) const
inline

Property: String separating group name from switch name.

If switch group names are present, this property holds the string that separates the group name from the switch name. For instance, if the group name is "group" and the switch name is "switch", the prefix is "--" and the separator is "-", then the switch can be parsed as either "--switch" or as "--group-switch".

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

◆ groupNameSeparator() [2/2]

Parser& Sawyer::CommandLine::Parser::groupNameSeparator ( const std::string &  s)
inline

Property: String separating group name from switch name.

If switch group names are present, this property holds the string that separates the group name from the switch name. For instance, if the group name is "group" and the switch name is "switch", the prefix is "--" and the separator is "-", then the switch can be parsed as either "--switch" or as "--group-switch".

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

◆ showingGroupNames() [1/2]

ShowGroupName Sawyer::CommandLine::Parser::showingGroupNames ( ) const
inline

Property: How to show group names in switch documentation.

When generating a switch synopsis and the group containing the switch has a non-empty name, the group name can be added to the switch name. The default is to add the group name as an optional part of the switch, like "--[group-]switch" since the parser treats them as optional unless the abbreviated name is ambiguous.

See also, groupNameSeparator, SwitchGroup::name.

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

◆ showingGroupNames() [2/2]

Parser& Sawyer::CommandLine::Parser::showingGroupNames ( ShowGroupName  x)
inline

Property: How to show group names in switch documentation.

When generating a switch synopsis and the group containing the switch has a non-empty name, the group name can be added to the switch name. The default is to add the group name as an optional part of the switch, like "--[group-]switch" since the parser treats them as optional unless the abbreviated name is ambiguous.

See also, groupNameSeparator, SwitchGroup::name.

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

◆ resetLongPrefixes()

Parser& Sawyer::CommandLine::Parser::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 
)

Prefixes to use for long command-line switches.

The resetLongPrefixes clears the list (and adds prefixes) while longPrefix only adds another prefix to the list. The default long switch prefix on Unix-like systems is --, but this can be overridden or augmented by switch groups and switch declarations.

◆ longPrefix()

Parser& Sawyer::CommandLine::Parser::longPrefix ( const std::string &  s1)
inline

Prefixes to use for long command-line switches.

The resetLongPrefixes clears the list (and adds prefixes) while longPrefix only adds another prefix to the list. The default long switch prefix on Unix-like systems is --, but this can be overridden or augmented by switch groups and switch declarations.

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

◆ longPrefixes()

const std::vector<std::string>& Sawyer::CommandLine::Parser::longPrefixes ( ) const
inline

Prefixes to use for long command-line switches.

The resetLongPrefixes clears the list (and adds prefixes) while longPrefix only adds another prefix to the list. The default long switch prefix on Unix-like systems is --, but this can be overridden or augmented by switch groups and switch declarations.

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

◆ resetShortPrefixes()

Parser& Sawyer::CommandLine::Parser::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 
)

Prefixes to use for short command-line switches.

The resetShortPrefixes clears the list (and adds prefixes) while shortPrefix only adds another prefix to the list. The default short switch prefix on Unix-like systems is -, but this can be overridden or augmented by switch groups and switch declarations.

◆ shortPrefix()

Parser& Sawyer::CommandLine::Parser::shortPrefix ( const std::string &  s1)
inline

Prefixes to use for short command-line switches.

The resetShortPrefixes clears the list (and adds prefixes) while shortPrefix only adds another prefix to the list. The default short switch prefix on Unix-like systems is -, but this can be overridden or augmented by switch groups and switch declarations.

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

◆ shortPrefixes()

const std::vector<std::string>& Sawyer::CommandLine::Parser::shortPrefixes ( ) const
inline

Prefixes to use for short command-line switches.

The resetShortPrefixes clears the list (and adds prefixes) while shortPrefix only adds another prefix to the list. The default short switch prefix on Unix-like systems is -, but this can be overridden or augmented by switch groups and switch declarations.

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

◆ resetValueSeparators()

Parser& Sawyer::CommandLine::Parser::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 
)

Strings that separate a long switch from its value.

The resetValueSeparators clears the list (and adds separators) while valueSeparator only adds another separator to the list. The separator " " is special: it indicates that the argument for a switch must appear in a separate program argument (i.e., --author matzke as opposed to --author=matzke). The default value separators on Unix-like systems are "=" and " ", but this can be overridden or augmented by switch groups and switch declarations.

◆ valueSeparator()

Parser& Sawyer::CommandLine::Parser::valueSeparator ( const std::string &  s1)
inline

Strings that separate a long switch from its value.

The resetValueSeparators clears the list (and adds separators) while valueSeparator only adds another separator to the list. The separator " " is special: it indicates that the argument for a switch must appear in a separate program argument (i.e., --author matzke as opposed to --author=matzke). The default value separators on Unix-like systems are "=" and " ", but this can be overridden or augmented by switch groups and switch declarations.

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

◆ valueSeparators()

const std::vector<std::string>& Sawyer::CommandLine::Parser::valueSeparators ( ) const
inline

Strings that separate a long switch from its value.

The resetValueSeparators clears the list (and adds separators) while valueSeparator only adds another separator to the list. The separator " " is special: it indicates that the argument for a switch must appear in a separate program argument (i.e., --author matzke as opposed to --author=matzke). The default value separators on Unix-like systems are "=" and " ", but this can be overridden or augmented by switch groups and switch declarations.

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

◆ resetTerminationSwitches()

Parser& Sawyer::CommandLine::Parser::resetTerminationSwitches ( const std::string &  s1 = STR_NONE,
const std::string &  s2 = STR_NONE,
const std::string &  s3 = STR_NONE,
const std::string &  s4 = STR_NONE 
)

Strings that indicate the end of the argument list.

The resetTerminationSwitches clears the list (and adds terminators) while terminationSwitch only adds another terminator to the list. The default terminator on Unix-like systems is --.

◆ terminationSwitch()

Parser& Sawyer::CommandLine::Parser::terminationSwitch ( const std::string &  s1)
inline

Strings that indicate the end of the argument list.

The resetTerminationSwitches clears the list (and adds terminators) while terminationSwitch only adds another terminator to the list. The default terminator on Unix-like systems is --.

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

◆ terminationSwitches()

const std::vector<std::string>& Sawyer::CommandLine::Parser::terminationSwitches ( ) const
inline

Strings that indicate the end of the argument list.

The resetTerminationSwitches clears the list (and adds terminators) while terminationSwitch only adds another terminator to the list. The default terminator on Unix-like systems is --.

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

◆ shortMayNestle() [1/2]

Parser& Sawyer::CommandLine::Parser::shortMayNestle ( bool  b)
inline

Indicates whether short switches can nestle together.

If short switches are allowed to nestle, then -ab is the same as -a -b in two separate program arguments. This even works if the short switch takes an argument as long as the argument parsing ends at the next short switch name. For instance, if "a" takes an integer argument then -a100b will be parsed as -a100 -b, but if "a" takes a string argument the entire "100b" will be parsed as the value for the "a" switch. The default on Unix-like systems is that short switches may nestle.

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

◆ shortMayNestle() [2/2]

bool Sawyer::CommandLine::Parser::shortMayNestle ( ) const
inline

Indicates whether short switches can nestle together.

If short switches are allowed to nestle, then -ab is the same as -a -b in two separate program arguments. This even works if the short switch takes an argument as long as the argument parsing ends at the next short switch name. For instance, if "a" takes an integer argument then -a100b will be parsed as -a100 -b, but if "a" takes a string argument the entire "100b" will be parsed as the value for the "a" switch. The default on Unix-like systems is that short switches may nestle.

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

◆ resetInclusionPrefixes()

Parser& Sawyer::CommandLine::Parser::resetInclusionPrefixes ( const std::string &  s1 = STR_NONE,
const std::string &  s2 = STR_NONE,
const std::string &  s3 = STR_NONE,
const std::string &  s4 = STR_NONE 
)

Strings that indicate that arguments are to be read from a file.

The resetInclusionPrefixes clears the list (and adds prefixes) while inclusionPrefix only adds another prefix to the list. The default inclusion prefix on Unix-like systems is @. That is, a program argument @foo.conf will be replaced with arguments read from the file "foo.conf". See readArgsFromFile and expandIncludedFiles for details.

For instance, to make file inclusion look like a normal switch,

Parser parser();
parser.resetInclusionPrefixes("--file=");

◆ inclusionPrefix()

Parser& Sawyer::CommandLine::Parser::inclusionPrefix ( const std::string &  s1)
inline

Strings that indicate that arguments are to be read from a file.

The resetInclusionPrefixes clears the list (and adds prefixes) while inclusionPrefix only adds another prefix to the list. The default inclusion prefix on Unix-like systems is @. That is, a program argument @foo.conf will be replaced with arguments read from the file "foo.conf". See readArgsFromFile and expandIncludedFiles for details.

For instance, to make file inclusion look like a normal switch,

Parser parser();
parser.resetInclusionPrefixes("--file=");

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

◆ inclusionPrefixes()

const std::vector<std::string>& Sawyer::CommandLine::Parser::inclusionPrefixes ( ) const
inline

Strings that indicate that arguments are to be read from a file.

The resetInclusionPrefixes clears the list (and adds prefixes) while inclusionPrefix only adds another prefix to the list. The default inclusion prefix on Unix-like systems is @. That is, a program argument @foo.conf will be replaced with arguments read from the file "foo.conf". See readArgsFromFile and expandIncludedFiles for details.

For instance, to make file inclusion look like a normal switch,

Parser parser();
parser.resetInclusionPrefixes("--file=");

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

◆ skippingNonSwitches() [1/2]

Parser& Sawyer::CommandLine::Parser::skippingNonSwitches ( bool  b)
inline

Whether to skip over non-switch arguments when parsing.

If false, parsing stops at the first non-switch, otherwise non-switches are simply skipped over and added to the parsing result that's eventually returned. In either case, parsing stops when a terminator switch (usually --) is found. Anything that looks like a switch but doesn't match a declaration continues to result in an error regardless of this property.

See also
ParserResult::skippedArgs ParserResult::unparsedArgs

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

◆ skippingNonSwitches() [2/2]

bool Sawyer::CommandLine::Parser::skippingNonSwitches ( ) const
inline

Whether to skip over non-switch arguments when parsing.

If false, parsing stops at the first non-switch, otherwise non-switches are simply skipped over and added to the parsing result that's eventually returned. In either case, parsing stops when a terminator switch (usually --) is found. Anything that looks like a switch but doesn't match a declaration continues to result in an error regardless of this property.

See also
ParserResult::skippedArgs ParserResult::unparsedArgs

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

◆ skippingUnknownSwitches() [1/2]

Parser& Sawyer::CommandLine::Parser::skippingUnknownSwitches ( bool  b)
inline

Whether to skip over unrecognized switches.

An unrecognized switch is any program argument that looks like a switch but which doesn't match the name of any declared switch. When not skipping (the default) such program arguments throw an "unrecognized switch" std::runtime_error.

See also
ParserResult::skippedArgs ParserResult::unparsedArgs

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

◆ skippingUnknownSwitches() [2/2]

bool Sawyer::CommandLine::Parser::skippingUnknownSwitches ( ) const
inline

Whether to skip over unrecognized switches.

An unrecognized switch is any program argument that looks like a switch but which doesn't match the name of any declared switch. When not skipping (the default) such program arguments throw an "unrecognized switch" std::runtime_error.

See also
ParserResult::skippedArgs ParserResult::unparsedArgs

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

◆ errorStream() [1/2]

Parser& Sawyer::CommandLine::Parser::errorStream ( const Message::SProxy stream)
inline

Specifies a message stream to which errors are sent.

If non-null, when a parse method encounters an error it writes the error message to this stream and exits. The default, when null, is that errors cause an std::runtime_error to be thrown. The various "skip" properties suppress certain kinds of errors entirely.

Note, Message::SProxy objects are intermediaries returned by the [] operator of Message::Facility, and users don't normally interact with them explicitly. They're only present because c++11 std::move semantics aren't widely available yet.

For example, to cause command-line parsing errors to use the Sawyer-wide FATAL stream, say this:

See also
skippingNonSwitches skippingUnknownSwitches

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

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

Here is the caller graph for this function:

◆ errorStream() [2/2]

const Message::SProxy& Sawyer::CommandLine::Parser::errorStream ( ) const
inline

Specifies a message stream to which errors are sent.

If non-null, when a parse method encounters an error it writes the error message to this stream and exits. The default, when null, is that errors cause an std::runtime_error to be thrown. The various "skip" properties suppress certain kinds of errors entirely.

Note, Message::SProxy objects are intermediaries returned by the [] operator of Message::Facility, and users don't normally interact with them explicitly. They're only present because c++11 std::move semantics aren't widely available yet.

For example, to cause command-line parsing errors to use the Sawyer-wide FATAL stream, say this:

Parser parser;
parser.errorStream(Message::mlog[Message::FATAL]);
See also
skippingNonSwitches skippingUnknownSwitches

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

◆ exitMessage() [1/2]

Parser& Sawyer::CommandLine::Parser::exitMessage ( const std::string &  s)
inline

Extra text to print before exit.

This is only used when the errorStream property is non-null. The default is to emit the message "invoke with '-\-help' to see usage information." if a switch with the name "help" is present, or nothing otherwise.

See also
errorStream

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

◆ exitMessage() [2/2]

std::string Sawyer::CommandLine::Parser::exitMessage ( ) const
inline

Extra text to print before exit.

This is only used when the errorStream property is non-null. The default is to emit the message "invoke with '-\-help' to see usage information." if a switch with the name "help" is present, or nothing otherwise.

See also
errorStream

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

◆ environmentVariable() [1/2]

Parser& Sawyer::CommandLine::Parser::environmentVariable ( const std::string &  s)
inline

Name of environment variable holding initial arguments.

If the environment variable is set and has a value, its value string is treated as command-line arguments in the same way that command-line arguments are read from files by readArgsFromFile.

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

◆ environmentVariable() [2/2]

const std::string& Sawyer::CommandLine::Parser::environmentVariable ( ) const
inline

Name of environment variable holding initial arguments.

If the environment variable is set and has a value, its value string is treated as command-line arguments in the same way that command-line arguments are read from files by readArgsFromFile.

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

◆ parse() [1/2]

ParserResult Sawyer::CommandLine::Parser::parse ( int  argc,
char *  argv[] 
)

Parse program arguments.

The first program argument, argv[0], is considered to be the name of the program and is not parsed as a program argument. This function does not require that argv[argc] be a member of the argv array (normally, argv[argc]==NULL in main).

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

Here is the caller graph for this function:

◆ parse() [2/2]

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

Parse program arguments.

The vector should be only the program arguments, not a program name or final empty string.

◆ splitLineIntoWords()

static std::vector<std::string> Sawyer::CommandLine::Parser::splitLineIntoWords ( std::string  )
static

Split line of text into words.

Line is split at white space, but honoring the usual convention of single and double quotes.

◆ readArgsFromFile()

static std::vector<std::string> Sawyer::CommandLine::Parser::readArgsFromFile ( const std::string &  filename)
static

Read a text file to obtain arguments.

The specified file is opened and each line is read to obtain a vector of arguments. Blank lines and lines whose first non-space character is "#" are ignored. The remaining lines are split into one or more arguments at white space. Single and double quoted regions within a line are treated as single arguments (the quotes are removed). The backslash can be used to escape quotes, white space, and backslash; any other use of the backslash is not special.

◆ readArgsFromEnvVar()

static std::vector<std::string> Sawyer::CommandLine::Parser::readArgsFromEnvVar ( const std::string &  varName)
static

Read an envrionment variable to obtain arguments.

This function behaves identically to readArgsFromFile except the content comes from the environment variable. An undefined variable is treated as an empty variable.

◆ expandIncludedFiles()

std::vector<std::string> Sawyer::CommandLine::Parser::expandIncludedFiles ( const std::vector< std::string > &  args)

Expand file arguments.

Scans the specified argument list looking for file inclusion switches and replacing those switches with the the file.

◆ regroupArgs()

std::vector<std::vector<std::string> > Sawyer::CommandLine::Parser::regroupArgs ( const std::vector< std::string > &  args,
const Container::Interval< size_t > &  limits = Container::Interval< size_t >::whole(),
unsigned  flags = 0 
)

Group arguments by "--" separators.

Given a vector of command-line arguments, regroup them into sub-vectors by using the special "--" arguments to separate the groups. The flags is a bit vector that controls some of the finer aspects of grouping (see GroupingFlags). The number of returned groups (after flags are processed) must fall within the specified limits. If any error is encountered then either print an error message and exit, or throw an std::runtime_error, depending on whether an errorStream is defined.

◆ programName() [1/2]

Parser& Sawyer::CommandLine::Parser::programName ( const std::string &  programName)
inline

Program name for documentation.

If no program name is given (or it is set to the empty string) then the name is obtained from the operating system.

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

References programName().

Referenced by programName().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ programName() [2/2]

const std::string& Sawyer::CommandLine::Parser::programName ( ) const

Program name for documentation.

If no program name is given (or it is set to the empty string) then the name is obtained from the operating system.

◆ purpose() [1/2]

Parser& Sawyer::CommandLine::Parser::purpose ( const std::string &  purpose)
inline

Program purpose.

This is a short, one-line description of the command that will appear in the "NAME" section of a Unix man page and picked up the the makewhatis(8) command. The string specified here should be the part that appears after the hyphen, as in "foo - frobnicate the bar library".

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

References purpose().

Referenced by purpose().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ purpose() [2/2]

const std::string& Sawyer::CommandLine::Parser::purpose ( ) const
inline

Program purpose.

This is a short, one-line description of the command that will appear in the "NAME" section of a Unix man page and picked up the the makewhatis(8) command. The string specified here should be the part that appears after the hyphen, as in "foo - frobnicate the bar library".

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

◆ version() [1/3]

Parser& Sawyer::CommandLine::Parser::version ( const std::string &  versionString,
const std::string &  dateString = "" 
)

Program version.

Every program should have a version string and a date of last change. If no version string is given then "alpha" is assumed; if no date is given then the current month and year are used.

◆ version() [2/3]

Parser& Sawyer::CommandLine::Parser::version ( const std::pair< std::string, std::string > &  p)
inline

Program version.

Every program should have a version string and a date of last change. If no version string is given then "alpha" is assumed; if no date is given then the current month and year are used.

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

References version().

Referenced by version().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ version() [3/3]

std::pair<std::string, std::string> Sawyer::CommandLine::Parser::version ( ) const

Program version.

Every program should have a version string and a date of last change. If no version string is given then "alpha" is assumed; if no date is given then the current month and year are used.

◆ chapter() [1/3]

Parser& Sawyer::CommandLine::Parser::chapter ( int  chapterNumber,
const std::string &  chapterName = "" 
)

Manual chapter.

Every Unix manual page belongs to a specific chapter. The chapters are:

  • 1 – User commands that may be started by everyone.
  • 2 – System calls, that is, functions provided by the kernel.
  • 3 – Subroutines, that is, library functions.
  • 4 – Devices, that is, special files in the /dev directory.
  • 5 – File format descriptions, e.g. /etc/passwd.
  • 6 – Games, self-explanatory.
  • 7 – Miscellaneous, e.g. macro packages, conventions.
  • 8 – System administration tools that only root can execute.
  • 9 – Another (Linux specific) place for kernel routine documentation.

Do not use chapters "n", "o", or "l" (in fact, only those listed integers are accepted). If a name is supplied it overrides the default name of that chapter. If no chapter is specified, "1" is assumed.

◆ chapter() [2/3]

Parser& Sawyer::CommandLine::Parser::chapter ( const std::pair< int, std::string > &  p)
inline

Manual chapter.

Every Unix manual page belongs to a specific chapter. The chapters are:

  • 1 – User commands that may be started by everyone.
  • 2 – System calls, that is, functions provided by the kernel.
  • 3 – Subroutines, that is, library functions.
  • 4 – Devices, that is, special files in the /dev directory.
  • 5 – File format descriptions, e.g. /etc/passwd.
  • 6 – Games, self-explanatory.
  • 7 – Miscellaneous, e.g. macro packages, conventions.
  • 8 – System administration tools that only root can execute.
  • 9 – Another (Linux specific) place for kernel routine documentation.

Do not use chapters "n", "o", or "l" (in fact, only those listed integers are accepted). If a name is supplied it overrides the default name of that chapter. If no chapter is specified, "1" is assumed.

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

References chapter().

Referenced by chapter().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ chapter() [3/3]

std::pair<int, std::string> Sawyer::CommandLine::Parser::chapter ( ) const

Manual chapter.

Every Unix manual page belongs to a specific chapter. The chapters are:

  • 1 – User commands that may be started by everyone.
  • 2 – System calls, that is, functions provided by the kernel.
  • 3 – Subroutines, that is, library functions.
  • 4 – Devices, that is, special files in the /dev directory.
  • 5 – File format descriptions, e.g. /etc/passwd.
  • 6 – Games, self-explanatory.
  • 7 – Miscellaneous, e.g. macro packages, conventions.
  • 8 – System administration tools that only root can execute.
  • 9 – Another (Linux specific) place for kernel routine documentation.

Do not use chapters "n", "o", or "l" (in fact, only those listed integers are accepted). If a name is supplied it overrides the default name of that chapter. If no chapter is specified, "1" is assumed.

◆ doc() [1/2]

Parser& Sawyer::CommandLine::Parser::doc ( const std::string &  sectionName,
const std::string &  docKey,
const std::string &  text 
)

Documentation for a section of the manual.

The user may define any number of sections with any names. Names should be capitalized like titles (initial capital letter), although case is insensitive in the table that stores them. The sections of a manual page are sorted according to lower-case versions of either the docKey or the sectionName. If a section's documentation is completely empty (no user specified documentation and no automatically generated documentation) then it will not show up in the output.

Some sections have content that's generatated automatically. For these sections, setting the doc string will either override the generated content or augment the content as described below. Since setting the doc string to an empty string only suppresses any user-defined content and not the auto-generated content, this doesn't delete the section from the output. In order to delete the section, set its doc string to "delete" (this also works for sections that have no auto-generated content).

The following sections are always present in this order unless explicitly deleted by setting their doc string to "delete":

  • "Name" contains the program name and purpose separated from one another by a single hyphen. By convention, the purpose should be a short string with no capitalization (except special words) and no terminating punctuation. If no user documentation is specified then this section is generated automatically from the parser's purpose property.
  • "Synopsis" contains information about how to invoke the program. If the user does not provide documentation, then an automatically generated value is used, which says to invoke the program by its name followed by zero or more switches.
  • "Description" is the detailed description of the program. It has no automatically generated content.
  • "Switches" lists all the non-hidden switches organized by SwitchGroup.
  • All user-defined sections are inserted next.
  • "See Also" lists other man pages that were referenced prior to this point in the documentation.
  • "Documentation Issues" lists any non-fatal problems found in the documentation up to this point, such as switches that were referenced but not declared (e.g., misspelled).

The documentation is specified with a simple markup languge described by Switch::doc.

◆ doc() [2/2]

Parser& Sawyer::CommandLine::Parser::doc ( const std::string &  sectionName,
const std::string &  text 
)
inline

Documentation for a section of the manual.

The user may define any number of sections with any names. Names should be capitalized like titles (initial capital letter), although case is insensitive in the table that stores them. The sections of a manual page are sorted according to lower-case versions of either the docKey or the sectionName. If a section's documentation is completely empty (no user specified documentation and no automatically generated documentation) then it will not show up in the output.

Some sections have content that's generatated automatically. For these sections, setting the doc string will either override the generated content or augment the content as described below. Since setting the doc string to an empty string only suppresses any user-defined content and not the auto-generated content, this doesn't delete the section from the output. In order to delete the section, set its doc string to "delete" (this also works for sections that have no auto-generated content).

The following sections are always present in this order unless explicitly deleted by setting their doc string to "delete":

  • "Name" contains the program name and purpose separated from one another by a single hyphen. By convention, the purpose should be a short string with no capitalization (except special words) and no terminating punctuation. If no user documentation is specified then this section is generated automatically from the parser's purpose property.
  • "Synopsis" contains information about how to invoke the program. If the user does not provide documentation, then an automatically generated value is used, which says to invoke the program by its name followed by zero or more switches.
  • "Description" is the detailed description of the program. It has no automatically generated content.
  • "Switches" lists all the non-hidden switches organized by SwitchGroup.
  • All user-defined sections are inserted next.
  • "See Also" lists other man pages that were referenced prior to this point in the documentation.
  • "Documentation Issues" lists any non-fatal problems found in the documentation up to this point, such as switches that were referenced but not declared (e.g., misspelled).

The documentation is specified with a simple markup languge described by Switch::doc.

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

References doc().

Referenced by doc().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ docSections()

std::vector<std::string> Sawyer::CommandLine::Parser::docSections ( ) const

Documentation for a section of the manual.

The user may define any number of sections with any names. Names should be capitalized like titles (initial capital letter), although case is insensitive in the table that stores them. The sections of a manual page are sorted according to lower-case versions of either the docKey or the sectionName. If a section's documentation is completely empty (no user specified documentation and no automatically generated documentation) then it will not show up in the output.

Some sections have content that's generatated automatically. For these sections, setting the doc string will either override the generated content or augment the content as described below. Since setting the doc string to an empty string only suppresses any user-defined content and not the auto-generated content, this doesn't delete the section from the output. In order to delete the section, set its doc string to "delete" (this also works for sections that have no auto-generated content).

The following sections are always present in this order unless explicitly deleted by setting their doc string to "delete":

  • "Name" contains the program name and purpose separated from one another by a single hyphen. By convention, the purpose should be a short string with no capitalization (except special words) and no terminating punctuation. If no user documentation is specified then this section is generated automatically from the parser's purpose property.
  • "Synopsis" contains information about how to invoke the program. If the user does not provide documentation, then an automatically generated value is used, which says to invoke the program by its name followed by zero or more switches.
  • "Description" is the detailed description of the program. It has no automatically generated content.
  • "Switches" lists all the non-hidden switches organized by SwitchGroup.
  • All user-defined sections are inserted next.
  • "See Also" lists other man pages that were referenced prior to this point in the documentation.
  • "Documentation Issues" lists any non-fatal problems found in the documentation up to this point, such as switches that were referenced but not declared (e.g., misspelled).

The documentation is specified with a simple markup languge described by Switch::doc.

◆ docForSwitches()

std::string Sawyer::CommandLine::Parser::docForSwitches ( ) const

Documentation for a section of the manual.

The user may define any number of sections with any names. Names should be capitalized like titles (initial capital letter), although case is insensitive in the table that stores them. The sections of a manual page are sorted according to lower-case versions of either the docKey or the sectionName. If a section's documentation is completely empty (no user specified documentation and no automatically generated documentation) then it will not show up in the output.

Some sections have content that's generatated automatically. For these sections, setting the doc string will either override the generated content or augment the content as described below. Since setting the doc string to an empty string only suppresses any user-defined content and not the auto-generated content, this doesn't delete the section from the output. In order to delete the section, set its doc string to "delete" (this also works for sections that have no auto-generated content).

The following sections are always present in this order unless explicitly deleted by setting their doc string to "delete":

  • "Name" contains the program name and purpose separated from one another by a single hyphen. By convention, the purpose should be a short string with no capitalization (except special words) and no terminating punctuation. If no user documentation is specified then this section is generated automatically from the parser's purpose property.
  • "Synopsis" contains information about how to invoke the program. If the user does not provide documentation, then an automatically generated value is used, which says to invoke the program by its name followed by zero or more switches.
  • "Description" is the detailed description of the program. It has no automatically generated content.
  • "Switches" lists all the non-hidden switches organized by SwitchGroup.
  • All user-defined sections are inserted next.
  • "See Also" lists other man pages that were referenced prior to this point in the documentation.
  • "Documentation Issues" lists any non-fatal problems found in the documentation up to this point, such as switches that were referenced but not declared (e.g., misspelled).

The documentation is specified with a simple markup languge described by Switch::doc.

◆ docForSection()

std::string Sawyer::CommandLine::Parser::docForSection ( const std::string &  sectionName) const

Documentation for a section of the manual.

The user may define any number of sections with any names. Names should be capitalized like titles (initial capital letter), although case is insensitive in the table that stores them. The sections of a manual page are sorted according to lower-case versions of either the docKey or the sectionName. If a section's documentation is completely empty (no user specified documentation and no automatically generated documentation) then it will not show up in the output.

Some sections have content that's generatated automatically. For these sections, setting the doc string will either override the generated content or augment the content as described below. Since setting the doc string to an empty string only suppresses any user-defined content and not the auto-generated content, this doesn't delete the section from the output. In order to delete the section, set its doc string to "delete" (this also works for sections that have no auto-generated content).

The following sections are always present in this order unless explicitly deleted by setting their doc string to "delete":

  • "Name" contains the program name and purpose separated from one another by a single hyphen. By convention, the purpose should be a short string with no capitalization (except special words) and no terminating punctuation. If no user documentation is specified then this section is generated automatically from the parser's purpose property.
  • "Synopsis" contains information about how to invoke the program. If the user does not provide documentation, then an automatically generated value is used, which says to invoke the program by its name followed by zero or more switches.
  • "Description" is the detailed description of the program. It has no automatically generated content.
  • "Switches" lists all the non-hidden switches organized by SwitchGroup.
  • All user-defined sections are inserted next.
  • "See Also" lists other man pages that were referenced prior to this point in the documentation.
  • "Documentation Issues" lists any non-fatal problems found in the documentation up to this point, such as switches that were referenced but not declared (e.g., misspelled).

The documentation is specified with a simple markup languge described by Switch::doc.

◆ documentationMarkup()

std::string Sawyer::CommandLine::Parser::documentationMarkup ( ) const

Full documentation.

Combines all the documentation parts to return a string documenting the entire parser. The returned string contains markup in the Sawyer::Markup language, with some extensions specific to command-line parsing.

◆ podDocumentation()

std::string Sawyer::CommandLine::Parser::podDocumentation ( ) const

Generate Perl POD documentation.

Generates a Perl POD string for this parser.

◆ emitDocumentationToPager()

void Sawyer::CommandLine::Parser::emitDocumentationToPager ( ) const

Print documentation to standard output.

Use a pager if possible.

◆ switchGroupOrder() [1/2]

SortOrder Sawyer::CommandLine::Parser::switchGroupOrder ( ) const
inline

Property: How to order switch groups in documentation.

If the parser contains titled switch groups then switches will be organized into subsections based on the group titles, and this property controls how those subsections are ordered with respect to each other. The subsections can be sorted according to the order they were inserted into the parser, or alphabetically by their documentation keys or titles.

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

◆ switchGroupOrder() [2/2]

Parser& Sawyer::CommandLine::Parser::switchGroupOrder ( SortOrder  order)
inline

Property: How to order switch groups in documentation.

If the parser contains titled switch groups then switches will be organized into subsections based on the group titles, and this property controls how those subsections are ordered with respect to each other. The subsections can be sorted according to the order they were inserted into the parser, or alphabetically by their documentation keys or titles.

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

◆ insertLongSwitchStrings()

void Sawyer::CommandLine::Parser::insertLongSwitchStrings ( Canonical  ,
NamedSwitches index 
) const

Insert records for long switch strings.

Inserts records into the index for long switch strings depending on whether the switch string is canonical.

◆ insertShortSwitchStrings()

void Sawyer::CommandLine::Parser::insertShortSwitchStrings ( NamedSwitches index) const

Insert records for short switch strings.

Insert records into the index for short switch strings.

◆ insertSwitchStrings()

void Sawyer::CommandLine::Parser::insertSwitchStrings ( Canonical  ,
NamedSwitches index 
) const

Insert records for long and short switch strings.

Insert records into the index for both long and short switch strings. This is just a convenient way to invoke insertLongSwitchStrings and insertShortSwitchStrings.

◆ printIndex()

static void Sawyer::CommandLine::Parser::printIndex ( std::ostream &  ,
const NamedSwitches ,
const std::string &  linePrefix = "" 
)
static

Print a switch index.

This is mostly for debugging. It's quite easy to traverse the NamedSwitches object and print them yourself.

◆ findAmbiguities()

NamedSwitches Sawyer::CommandLine::Parser::findAmbiguities ( ) const

Find switch string ambiguities.

Return an index containing all switches that are ambiguous regardless of whether they're canonical.

◆ findUnresolvableAmbiguities()

NamedSwitches Sawyer::CommandLine::Parser::findUnresolvableAmbiguities ( ) const

Find unresolvable switch string ambiguities.

Return an index containing all switches that are ambiguous and which cannot be made unambiguous by qualifying them.

◆ removeMatchingSwitch() [1/2]

Sawyer::Optional<Switch> Sawyer::CommandLine::Parser::removeMatchingSwitch ( const std::string &  arg)

Remove the switch by matching parse sentence.

Removes from this parser whichever switch is able to parse the specified command-line. The input should be either a single command line argument string (like "--debug-level=5") or a vector of strings (like {"--debug-level", "5"}). Only long-name switches (not single-letter switches) can be removed this way. Only the first matched switch is removed from the parser.

Returns either nothing, or a copy of the switch parser that was removed. Since the switch parser is returned, it can then be modified and added back to the same parser or to a different parser.

◆ removeMatchingSwitch() [2/2]

Sawyer::Optional<Switch> Sawyer::CommandLine::Parser::removeMatchingSwitch ( const std::vector< std::string > &  args)

Remove the switch by matching parse sentence.

Removes from this parser whichever switch is able to parse the specified command-line. The input should be either a single command line argument string (like "--debug-level=5") or a vector of strings (like {"--debug-level", "5"}). Only long-name switches (not single-letter switches) can be removed this way. Only the first matched switch is removed from the parser.

Returns either nothing, or a copy of the switch parser that was removed. Since the switch parser is returned, it can then be modified and added back to the same parser or to a different parser.


The documentation for this class was generated from the following file:
Sawyer::Message::mlog
Facility mlog
Facility used by Sawyer components.
Sawyer::Message::FATAL
@ FATAL
Messages that indicate an abnormal situation from which the program was unable to recover.
Definition: Message.h:332
Sawyer::CommandLine::Parser::errorStream
Parser & errorStream(const Message::SProxy &stream)
Specifies a message stream to which errors are sent.
Definition: util/Sawyer/CommandLine.h:2998
Sawyer::CommandLine::Parser::Parser
Parser()
Default constructor.
Definition: util/Sawyer/CommandLine.h:2785
Sawyer::CommandLine::Parser::resetInclusionPrefixes
Parser & resetInclusionPrefixes(const std::string &s1=STR_NONE, const std::string &s2=STR_NONE, const std::string &s3=STR_NONE, const std::string &s4=STR_NONE)
Strings that indicate that arguments are to be read from a file.