E-MailRelay
Classes | Public Types | Public Member Functions | List of all members
G::Options Class Reference

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

Detailed Description

A class to represent allowed command-line options and to provide command-line usage text.

Definition at line 65 of file goptions.h.

Member Typedef Documentation

◆ Layout

Definition at line 68 of file goptions.h.

Constructor & Destructor Documentation

◆ Options()

G::Options::Options ( const std::string &  spec,
char  sep_major = '|',
char  sep_minor = '!',
char  escape = '^' 
)
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.

Member Function Documentation

◆ add() [1/2]

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.

◆ add() [2/2]

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.

◆ defaulting()

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.

◆ lookup()

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.

◆ multivalued() [1/2]

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.

◆ multivalued() [2/2]

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.

◆ names()

const G::StringArray & G::Options::names ( ) const

Returns the sorted list of long-form option names.

Definition at line 169 of file goptions.cpp.

◆ showUsage()

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.

◆ unvalued()

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.

◆ usageHelp()

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.

◆ usageSummary()

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:

< std::cout << options.usageSummary(
< OptionsLayout().set_level_if(!verbose,1U).set_extra(verbose) ,
< getopt.args().prefix() , " <arg> [<arg> ...]" ) << std::endl ;
<

Definition at line 444 of file goptions.cpp.

◆ valid()

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.

◆ valued() [1/2]

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.

◆ valued() [2/2]

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.

◆ visible() [1/2]

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.

◆ visible() [2/2]

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.


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