ROSE  0.9.9.109
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 2674 of file 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...
 
const std::vector< SwitchGroup > & switchGroups () const
 List of all switch groups. 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. More...
 
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 Switch &sw)
 Add switch declarations. More...
 
Parserwith (Switch sw, const std::string &docKey)
 Add switch declarations. 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...
 
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...
 

Static Public Member Functions

static std::vector< std::string > readArgsFromFile (const std::string &filename)
 Read a text file to obtain arguments. More...
 
static void printIndex (std::ostream &, const NamedSwitches &, const std::string &linePrefix="")
 Print a switch index. More...
 

Member Enumeration Documentation

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 2924 of file CommandLine.h.

Constructor & Destructor Documentation

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 2702 of file CommandLine.h.

Member Function Documentation

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 2712 of file CommandLine.h.

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 2713 of file CommandLine.h.

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 2718 of file CommandLine.h.

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 2719 of file CommandLine.h.

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

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

List of all switch groups.

Definition at line 2727 of file CommandLine.h.

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 2742 of file CommandLine.h.

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 2743 of file CommandLine.h.

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 2753 of file CommandLine.h.

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 2754 of file CommandLine.h.

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 2766 of file CommandLine.h.

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 2767 of file CommandLine.h.

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.

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 2776 of file CommandLine.h.

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 2777 of file CommandLine.h.

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.

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 2786 of file CommandLine.h.

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 2787 of file CommandLine.h.

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.

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 2798 of file CommandLine.h.

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 2799 of file CommandLine.h.

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 --.

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 2808 of file CommandLine.h.

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 2809 of file CommandLine.h.

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 2819 of file CommandLine.h.

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 2820 of file CommandLine.h.

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=");
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 2836 of file CommandLine.h.

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 2837 of file CommandLine.h.

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 2847 of file CommandLine.h.

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 2848 of file CommandLine.h.

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 2857 of file CommandLine.h.

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 2858 of file CommandLine.h.

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 2878 of file CommandLine.h.

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

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 2879 of file CommandLine.h.

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 2888 of file CommandLine.h.

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 2889 of file CommandLine.h.

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().

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.

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.

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.

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.

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 2945 of file CommandLine.h.

References programName().

Referenced by programName().

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.

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 2953 of file CommandLine.h.

References purpose().

Referenced by purpose().

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 2954 of file CommandLine.h.

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.

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 2961 of file CommandLine.h.

References version().

Referenced by version().

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.

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.

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 2981 of file CommandLine.h.

References chapter().

Referenced by chapter().

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.

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.

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 3024 of file CommandLine.h.

References doc().

Referenced by doc().

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.

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.

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.

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.

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

Generate Perl POD documentation.

Generates a Perl POD string for this parser.

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

Generate plain text documentation.

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

Print documentation to standard output.

Use a pager if possible.

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 3061 of file CommandLine.h.

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 3062 of file CommandLine.h.

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.

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

Insert records for short switch strings.

Insert records into the index for short switch strings.

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.

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.

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.

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.


The documentation for this class was generated from the following file: