ROSE
0.11.96.11
|
The parser for a program command line.
A parser is configured to describe the valid program switches, their arguments, and other information, and then the parser is then applied to a program command line to return a ParserResult. The process of parsing a command line is free of side-effects other than creating the result.
Definition at line 2756 of file util/Sawyer/CommandLine.h.
#include <CommandLine.h>
Public Types | |
enum | GroupingFlags { DEFAULT_GROUPING = 0, PROHIBIT_EMPTY_GROUPS = 0x0001, SPLIT_SINGLE_GROUP = 0x0002 } |
Bit flags for argument grouping. More... | |
Public Member Functions | |
Parser () | |
Default constructor. More... | |
bool | switchGroupExists (const std::string &name) const |
Predicate to determine whether a switch group exists. More... | |
bool | eraseSwitchGroup (const std::string &name) |
Remove switch group from parser. More... | |
ParserResult | parse (int argc, char *argv[]) |
Parse program arguments. More... | |
ParserResult | parse (const std::vector< std::string > &) |
Parse program arguments. More... | |
std::vector< std::string > | expandIncludedFiles (const std::vector< std::string > &args) |
Expand file arguments. More... | |
std::vector< std::vector< std::string > > | regroupArgs (const std::vector< std::string > &args, const Container::Interval< size_t > &limits=Container::Interval< size_t >::whole(), unsigned flags=0) |
Group arguments by "--" separators. More... | |
std::string | documentationMarkup () const |
Full documentation. More... | |
std::string | podDocumentation () const |
Generate Perl POD documentation. More... | |
std::string | textDocumentation () const |
Generate plain text documentation. | |
void | emitDocumentationToPager () const |
Print documentation to standard output. More... | |
template<class Grammar > | |
void | emitDocumentationToPager () const |
void | insertLongSwitchStrings (Canonical, NamedSwitches &index) const |
Insert records for long switch strings. More... | |
void | insertShortSwitchStrings (NamedSwitches &index) const |
Insert records for short switch strings. More... | |
void | insertSwitchStrings (Canonical, NamedSwitches &index) const |
Insert records for long and short switch strings. More... | |
NamedSwitches | findAmbiguities () const |
Find switch string ambiguities. More... | |
NamedSwitches | findUnresolvableAmbiguities () const |
Find unresolvable switch string ambiguities. More... | |
const 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 §ionName, const std::string &docKey, const std::string &text) |
Documentation for a section of the manual. More... | |
Parser & | doc (const std::string §ionName, 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 §ionName) 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... | |
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.
|
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.
|
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.
|
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.
|
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.
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.
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.
|
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.
|
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.
|
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.
|
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.
|
inline |
Property: How to show group names in switch documentation.
When generating a switch synopsis and the group containing the switch has a non-empty name, the group name can be added to the switch name. The default is to add the group name as an optional part of the switch, like "--[group-]switch" since the parser treats them as optional unless the abbreviated name is ambiguous.
See also, groupNameSeparator, SwitchGroup::name.
Definition at line 2886 of file util/Sawyer/CommandLine.h.
|
inline |
Property: How to show group names in switch documentation.
When generating a switch synopsis and the group containing the switch has a non-empty name, the group name can be added to the switch name. The default is to add the group name as an optional part of the switch, like "--[group-]switch" since the parser treats them as optional unless the abbreviated name is ambiguous.
See also, groupNameSeparator, SwitchGroup::name.
Definition at line 2887 of file util/Sawyer/CommandLine.h.
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.
|
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.
|
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.
|
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.
|
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.
|
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.
|
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 --
.
|
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.
|
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.
|
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.
|
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,
|
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,
Definition at line 2956 of file util/Sawyer/CommandLine.h.
|
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,
Definition at line 2957 of file util/Sawyer/CommandLine.h.
|
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.
Definition at line 2967 of file util/Sawyer/CommandLine.h.
|
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.
Definition at line 2968 of file util/Sawyer/CommandLine.h.
|
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
.
Definition at line 2977 of file util/Sawyer/CommandLine.h.
|
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
.
Definition at line 2978 of file util/Sawyer/CommandLine.h.
|
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:
Definition at line 2998 of file util/Sawyer/CommandLine.h.
Referenced by Sawyer::CommandLine::Boost::command_line_parser::command_line_parser().
|
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:
Definition at line 2999 of file util/Sawyer/CommandLine.h.
|
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.
Definition at line 3008 of file util/Sawyer/CommandLine.h.
|
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.
Definition at line 3009 of file util/Sawyer/CommandLine.h.
|
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.
|
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 |
Split line of text into words.
Line is split at white space, but honoring the usual convention of single and double quotes.
|
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 |
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.
|
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.
|
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().
|
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.
|
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:
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.
|
inline |
Manual chapter.
Every Unix manual page belongs to a specific chapter. The chapters are:
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:
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":
The documentation is specified with a simple markup languge described by Switch::doc.
|
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":
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().
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":
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":
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":
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.
void Sawyer::CommandLine::Parser::emitDocumentationToPager | ( | ) | const |
Print documentation to standard output.
Use a pager if possible.
|
inline |
Property: How to order switch groups in documentation.
If the parser contains titled switch groups then switches will be organized into subsections based on the group titles, and this property controls how those subsections are ordered with respect to each other. The subsections can be sorted according to the order they were inserted into the parser, or alphabetically by their documentation keys or titles.
Definition at line 3202 of file util/Sawyer/CommandLine.h.
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.
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 |
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.