E-MailRelay
|
A class to represent allowed command-line options and to provide command-line usage text. More...
#include <goptions.h>
Public Types | |
using | Layout = OptionsLayout |
Public Member Functions | |
Options (const std::string &spec, char sep_major='|', char sep_minor='!', char escape='^') | |
Constructor taking a specification string. More... | |
Options () | |
Default constructor for no options. | |
void | add (StringArray) |
Adds one component of the specification, broken down into its seven separate parts. More... | |
void | add (StringArray, char sep, char escape='\\') |
Adds one component of the specification broken down into six separate parts with fields 3 and 4 joined by the given separator character. More... | |
const StringArray & | names () const |
Returns the sorted list of long-form option names. More... | |
std::string | lookup (char c) const |
Converts from short-form option character to the corresponding long-form name. More... | |
bool | valid (const std::string &) const |
Returns true if the long-form option name is valid. More... | |
bool | visible (const std::string &name, unsigned int level, bool level_exact=false) const |
Returns true if the option is visible at the given level. More... | |
bool | visible (const std::string &name) const |
Returns true if the option is visible. More... | |
bool | valued (char) const |
Returns true if the given short-form option takes a value, Returns true if the short-form option character is valued, including multivalued() and defaulting(). More... | |
bool | valued (const std::string &) const |
Returns true if the given long-form option takes a value, including multivalued() and defaulting(). More... | |
bool | multivalued (char) const |
Returns true if the short-form option can have multiple values. More... | |
bool | multivalued (const std::string &) const |
Returns true if the long-form option can have multiple values. More... | |
bool | unvalued (const std::string &) const |
Returns true if the given option name is valid and takes no value. More... | |
bool | defaulting (const std::string &) const |
Returns true if the given long-form single-valued() option can optionally have no explicit value, so "--foo=" and "--foo" are equivalent, having an empty value, and "--foo=bar" has a value of 'bar' but "--foo bar" is interpreted as 'foo' taking its default (empty) value followed by a separate argument 'bar'. More... | |
std::string | usageSummary (const Layout &, const std::string &exe, const std::string &args=std::string()) const |
Returns a one-line (or line-wrapped) usage summary, as "usage: <exe> <options> <args>". More... | |
std::string | usageHelp (const Layout &) const |
Returns a multi-line string giving help on each option. More... | |
void | showUsage (const Layout &, std::ostream &stream, const std::string &exe, const std::string &args=std::string()) const |
Streams out multi-line usage text using usageSummary() and usageHelp(). More... | |
A class to represent allowed command-line options and to provide command-line usage text.
Definition at line 65 of file goptions.h.
using G::Options::Layout = OptionsLayout |
Definition at line 68 of file goptions.h.
|
explicit |
Constructor taking a specification string.
Uses specifications like "p!port!defines the port number!!1!port!1|v!verbose!shows more logging!!0!!1" made up of (1) an optional single-character-option-letter, (2) a multi-character-option-name (3) an option-description, (4) optional option-description-extra text, (5) a value-type (with '0' for unvalued, '1' for a single value, '2' for a comma-separated list (possibly multiple times), or '01' for a defaultable single value) or (6) a value-description (unless unvalued), and (7) a level enumeration.
By convention mainstream options should have a level of 1, and obscure ones level 2 and above. If the option-description field is empty or if the level is zero then the option is hidden.
Definition at line 33 of file goptions.cpp.
void G::Options::add | ( | StringArray | spec_parts | ) |
Adds one component of the specification, broken down into its seven separate parts.
Definition at line 65 of file goptions.cpp.
void G::Options::add | ( | StringArray | spec_parts, |
char | sep, | ||
char | escape = '\\' |
||
) |
Adds one component of the specification broken down into six separate parts with fields 3 and 4 joined by the given separator character.
Definition at line 78 of file goptions.cpp.
bool G::Options::defaulting | ( | const std::string & | name | ) | const |
Returns true if the given long-form single-valued() option can optionally have no explicit value, so "--foo=" and "--foo" are equivalent, having an empty value, and "--foo=bar" has a value of 'bar' but "--foo bar" is interpreted as 'foo' taking its default (empty) value followed by a separate argument 'bar'.
Definition at line 106 of file goptions.cpp.
std::string G::Options::lookup | ( | char | c | ) | const |
Converts from short-form option character to the corresponding long-form name.
Returns the empty string if none.
Definition at line 159 of file goptions.cpp.
bool G::Options::multivalued | ( | char | c | ) | const |
Returns true if the short-form option can have multiple values.
Returns false if not valid().
Definition at line 128 of file goptions.cpp.
bool G::Options::multivalued | ( | const std::string & | name | ) | const |
Returns true if the long-form option can have multiple values.
Returns false if not valid().
Definition at line 133 of file goptions.cpp.
const G::StringArray & G::Options::names | ( | ) | const |
Returns the sorted list of long-form option names.
Definition at line 169 of file goptions.cpp.
void G::Options::showUsage | ( | const Layout & | layout, |
std::ostream & | stream, | ||
const std::string & | exe, | ||
const std::string & | args = std::string() |
||
) | const |
Streams out multi-line usage text using usageSummary() and usageHelp().
Definition at line 435 of file goptions.cpp.
bool G::Options::unvalued | ( | const std::string & | name | ) | const |
Returns true if the given option name is valid and takes no value.
Returns false if not valid().
Definition at line 123 of file goptions.cpp.
std::string G::Options::usageHelp | ( | const Layout & | layout | ) | const |
Returns a multi-line string giving help on each option.
Definition at line 385 of file goptions.cpp.
std::string G::Options::usageSummary | ( | const Layout & | layout, |
const std::string & | exe, | ||
const std::string & | args = std::string() |
||
) | const |
Returns a one-line (or line-wrapped) usage summary, as "usage: <exe> <options> <args>".
The 'args' parameter should represent the non-option arguments (with a leading space), like " <foo> [<bar>]".
Eg:
Definition at line 444 of file goptions.cpp.
bool G::Options::valid | ( | const std::string & | name | ) | const |
Returns true if the long-form option name is valid.
Definition at line 154 of file goptions.cpp.
bool G::Options::valued | ( | char | c | ) | const |
Returns true if the given short-form option takes a value, Returns true if the short-form option character is valued, including multivalued() and defaulting().
Returns false if not valid().
Definition at line 112 of file goptions.cpp.
bool G::Options::valued | ( | const std::string & | name | ) | const |
Returns true if the given long-form option takes a value, including multivalued() and defaulting().
Returns false if not valid().
Definition at line 117 of file goptions.cpp.
bool G::Options::visible | ( | const std::string & | name | ) | const |
Returns true if the option is visible.
Returns false if the option is hidden or the name is not valid().
Definition at line 149 of file goptions.cpp.
bool G::Options::visible | ( | const std::string & | name, |
unsigned int | level, | ||
bool | level_exact = false |
||
) | const |
Returns true if the option is visible at the given level.
Deliberately hidden options at level zero are never visible(). Returns false if not a valid() name .
Definition at line 139 of file goptions.cpp.