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 <util/Sawyer/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. 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 ParsingProperties &	properties () const


Parser &	with (const SwitchGroup &sg)
	Add switch declarations. More...

Parser &	with (const SwitchGroup &sg, const std::string &docKey)
	Add switch declarations. More...

Parser &	with (const std::vector< SwitchGroup > &sgs)
	Add switch declarations. More...

Parser &	with (const Switch &sw)
	Add switch declarations. More...

Parser &	with (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 SwitchGroup &	switchGroup (const std::string &name) const
	Switch group having specified name. More...

SwitchGroup &	switchGroup (const std::string &name)
	Switch group having specified name. More...


bool	reportingAmbiguities () const
	Property: Whether to report ambiguities. More...

Parser &	reportingAmbiguities (bool b)
	Property: Whether to report ambiguities. More...


const std::string &	groupNameSeparator () const
	Property: String separating group name from switch name. More...

Parser &	groupNameSeparator (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...

Parser &	showingGroupNames (ShowGroupName x)
	Property: How to show group names in switch documentation. More...


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

Parser &	longPrefix (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...


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

Parser &	shortPrefix (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...


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

Parser &	valueSeparator (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...


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

Parser &	terminationSwitch (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...


Parser &	shortMayNestle (bool b)
	Indicates whether short switches can nestle together. More...

bool	shortMayNestle () const
	Indicates whether short switches can nestle together. More...


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

Parser &	inclusionPrefix (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...


Parser &	skippingNonSwitches (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...


Parser &	skippingUnknownSwitches (bool b)
	Whether to skip over unrecognized switches. More...

bool	skippingUnknownSwitches () const
	Whether to skip over unrecognized switches. More...


Parser &	errorStream (const Message::SProxy &stream)
	Specifies a message stream to which errors are sent. More...

const Message::SProxy &	errorStream () const
	Specifies a message stream to which errors are sent. More...


Parser &	exitMessage (const std::string &s)
	Extra text to print before exit. More...

std::string	exitMessage () const
	Extra text to print before exit. More...


Parser &	environmentVariable (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...


Parser &	programName (const std::string &programName)
	Program name for documentation. More...

const std::string &	programName () const
	Program name for documentation. More...


Parser &	purpose (const std::string &purpose)
	Program purpose. More...

const std::string &	purpose () const
	Program purpose. More...


Parser &	version (const std::string &versionString, const std::string &dateString="")
	Program version. More...

Parser &	version (const std::pair< std::string, std::string > &p)
	Program version. More...

std::pair< std::string, std::string >	version () const
	Program version. More...


Parser &	chapter (int chapterNumber, const std::string &chapterName="")
	Manual chapter. More...

Parser &	chapter (const std::pair< int, std::string > &p)
	Manual chapter. More...

std::pair< int, std::string >	chapter () const
	Manual chapter. More...


Parser &	doc (const std::string &sectionName, const std::string &docKey, const std::string &text)
	Documentation for a section of the manual. More...

Parser &	doc (const std::string &sectionName, const std::string &text)
	Documentation for a section of the manual. More...

Parser &	doc (const std::pair< std::string, std::string > &)
	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...

Parser &	switchGroupOrder (SortOrder order)
	Property: How to order switch groups in documentation. More...


Sawyer::Optional< Switch >	removeMatchingSwitch (const std::string &arg)
	Remove the switch by matching parse sentence. More...

Sawyer::Optional< Switch >	removeMatchingSwitch (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

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

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

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.

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.

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.

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.

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

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.

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

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.

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.

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.

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.

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.

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.

Definition at line 2886 of file util/Sawyer/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.

Definition at line 2887 of file util/Sawyer/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 2896 of file util/Sawyer/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 2897 of file util/Sawyer/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 2906 of file util/Sawyer/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 2907 of file util/Sawyer/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 2918 of file util/Sawyer/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 2919 of file util/Sawyer/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 2928 of file util/Sawyer/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 2929 of file util/Sawyer/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 2939 of file util/Sawyer/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 2940 of file util/Sawyer/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 2956 of file util/Sawyer/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 2957 of file util/Sawyer/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 2967 of file util/Sawyer/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 2968 of file util/Sawyer/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 2977 of file util/Sawyer/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 2978 of file util/Sawyer/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:

Parser parser;

parser.errorStream(Message::mlog[Message::FATAL]);

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

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.

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.

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.

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.

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.

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

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.

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.

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 3086 of file util/Sawyer/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 3094 of file util/Sawyer/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 3095 of file util/Sawyer/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 3102 of file util/Sawyer/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 3122 of file util/Sawyer/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 3165 of file util/Sawyer/CommandLine.h.

References doc().

Referenced by doc().

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

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::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 3203 of file util/Sawyer/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 3204 of file util/Sawyer/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.

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.

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:

util/Sawyer/CommandLine.h

Description

Public Types

Public Member Functions

Static Public Member Functions

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation