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

A class to assemble a list of command-line options and provide access by name. More...

#include <goptions.h>

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 (const Option &, char sep='!', char escape='\\')
 Adds one component of the specification. More...
 
const std::vector< Option > & list () const
 Returns the sorted list of option structures. 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...
 
const Optionfind (const std::string &) const
 Returns a pointer to the option with a matching long-form name. 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...
 
bool defaulting (char) const
 Returns defaulting(lookup()) even though defaulting options can never take a value when short-form. More...
 

Static Public Member Functions

static void add (Options &, char c, const char *name, const char *text, const char *more, Option::Multiplicity m, const char *argname, unsigned int level, unsigned int main_tag_bit, unsigned int tag_bits=0U)
 A convenience function that constructs an Option object with the trailing arguments and then calls add(Option) on the given Options object. More...
 

Detailed Description

A class to assemble a list of command-line options and provide access by name.

Definition at line 39 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!the port! for listening!1!port!1|v!verbose!more logging! and help!0!!1!tag1!tag2" 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), (7) a level enumeration, and optional trailing tags.

Typically mainstream options are given 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.

The first tag (if any) is the main tag, corresponding to a sub-heading when generating documentation.

Definition at line 30 of file goptions.cpp.

Member Function Documentation

◆ add() [1/2]

void G::Options::add ( const Option opt,
char  sep = '!',
char  escape = '\\' 
)

Adds one component of the specification.

If the 'description' contains the unescaped 'sep' character then it is split into two parts and the second part replaces the 'description_extra', which must be empty.

Definition at line 76 of file goptions.cpp.

◆ add() [2/2]

void G::Options::add ( Options options,
char  c,
const char *  name,
const char *  text,
const char *  more,
Option::Multiplicity  m,
const char *  argname,
unsigned int  level,
unsigned int  main_tag_bit,
unsigned int  tag_bits = 0U 
)
static

A convenience function that constructs an Option object with the trailing arguments and then calls add(Option) on the given Options object.

The 'text' string is passed through G::gettext() and should therefore normally be marked for translation with G::tx(). The tag parameters are both bit-masks, with only one bit set in the main tag.

Definition at line 69 of file goptions.cpp.

◆ defaulting() [1/2]

bool G::Options::defaulting ( char  c) const

Returns defaulting(lookup()) even though defaulting options can never take a value when short-form.

Definition at line 111 of file goptions.cpp.

◆ defaulting() [2/2]

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 116 of file goptions.cpp.

◆ find()

const G::Option * G::Options::find ( const std::string &  name) const

Returns a pointer to the option with a matching long-form name.

Returns nullptr if none.

Definition at line 175 of file goptions.cpp.

◆ list()

const std::vector< G::Option > & G::Options::list ( ) const

Returns the sorted list of option structures.

Definition at line 185 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 165 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 138 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 143 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 133 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 160 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 122 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 127 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 155 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 149 of file goptions.cpp.


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