E-MailRelay

Public Member Functions | Static Public Member Functions | List of all members
G::GetOpt Class Reference

A command-line option parser. More...

`#include <ggetopt.h>`

## Public Member Functions
| GetOpt (const Arg &arg, const std::string &spec, std::size_t ignore_non_options=0U)
| Constructor taking a Arg object and a G::Options specification string. More...
| GetOpt (const StringArray &arg, const std::string &spec, std::size_t ignore_non_options=0U)
| An overload taking a vector of command-line arguments. More...
| GetOpt (const Arg &arg, const Options &spec, std::size_t ignore_non_options=0U)
| A constructor overload taking an Options object. More...
| GetOpt (const StringArray &arg, const Options &spec, std::size_t ignore_non_options=0U)
| A constructor overload taking an Options object. More...
void | reload (const StringArray &arg, std::size_t ignore_non_options=0U)
| Reinitialises the object with the given command-line arguments. More...
void | addOptionsFromFile (std::size_t n=1U, const std::string &varkey={}, const std::string &varvalue={})
| Adds options from the config file named by the n'th non-option command-line argument (zero-based and allowing for the program name in argv0). More...
bool | addOptionsFromFile (size_t n, const StringArray &extension_blocklist)
| Adds options from the config file named by the n'th non-option argument, but not if the file extension matches any in the block list. More...
void | addOptionsFromFile (const Path &file)
| Adds options from the given config file. More...
const std::vector< Option > & | options () const
| Exposes the list of option specification objects. More...
const OptionMap & | map () const
| Exposes the map of option-values. More...
Arg | args () const
| Returns the G::Arg command-line, excluding options. More...
StringArray | errorList () const
| Returns the list of errors. More...
bool | hasErrors () const
| Returns true if there are errors. More...
void | showErrors (std::ostream &stream, const std::string &prefix_1, const std::string &prefix_2=std::string(": ")) const
| A convenience function which streams out each errorList() item to the given stream, prefixed with the given prefix(es). More...
void | showErrors (std::ostream &stream) const
| An overload which has a sensible prefix. More...
bool | contains (char option_letter) const
| Returns true if the command-line contains the option identified by its short-form letter. More...
bool | contains (std::string_view option_name) const
| Returns true if the command-line contains the option identified by its long-form name. More...
std::size_t | count (std::string_view option_name) const
| Returns the option's repeat count. More...
std::string | value (std::string_view option_name, std::string_view default_={}) const
| Returns the value for the option identified by its long-form name. More...
std::string | value (char option_letter, std::string_view default_={}) const
| An overload that returns the value of the option identified by its short-form letter. More...

## Static Public Member Functions
static StringArray | readOptionsFromFile (const Path &)
| Reads options from file as a list of strings like "--foo=bar". More...

## Detailed Description

A command-line option parser.

Usage:

G::Arg arg( argc , argv ) ;
G::GetOpt opt( arg , "e!extra!does something! extra!1!something!1" "|" "h!help!shows help!!0!!1" ) ;
if( opt.hasErrors() ) { opt.showErrors( std::cerr ) ; exit( 2 ) ; }
if( opt.contains("help") ) { G::OptionsUsage usage( opt.options() ) ;
usage.output( {} , std::cout , arg.prefix() , " [<more>]" ) ;
exit( 0 ) ; }
run( opt.args() , opt.value("extra","default") ) ;
G::Arg
A class which holds a represention of the argc/argv command line array, and supports simple command-l...
Definition: garg.h:50
G::GetOpt
A command-line option parser.
Definition: ggetopt.h:59
G::OptionsUsage
Provides help text for a set of options.
Definition: goptionsusage.h:65

This class is a thin layer over G::Options, G::OptionMap, G::OptionParser etc, but also adding file loading. The G::OptionsOutput class is kept separate in order to minimise dependencies.

Definition at line 58 of file ggetopt.h.

## Constructor & Destructor Documentation

## ◆ GetOpt() [1/4]

G::GetOpt::GetOpt | ( | const Arg & | arg,
|  | const std::string & | spec,
|  | std::size_t | ignore_non_options = `0U`
| ) |  |

Constructor taking a Arg object and a G::Options specification string.

Parsing errors are reported via errorList().

Definition at line 32 of file ggetopt.cpp.

## ◆ GetOpt() [2/4]

G::GetOpt::GetOpt | ( | const StringArray & | arg,
|  | const std::string & | spec,
|  | std::size_t | ignore_non_options = `0U`
| ) |  |

An overload taking a vector of command-line arguments.

The program name in the first argument is expected but ignored.

Definition at line 48 of file ggetopt.cpp.

## ◆ GetOpt() [3/4]

G::GetOpt::GetOpt | ( | const Arg & | arg,
|  | const Options & | spec,
|  | std::size_t | ignore_non_options = `0U`
| ) |  |

A constructor overload taking an Options object.

Definition at line 40 of file ggetopt.cpp.

## ◆ GetOpt() [4/4]

G::GetOpt::GetOpt | ( | const StringArray & | arg,
|  | const Options & | spec,
|  | std::size_t | ignore_non_options = `0U`
| ) |  |

A constructor overload taking an Options object.

Definition at line 57 of file ggetopt.cpp.

## Member Function Documentation

## ◆ addOptionsFromFile() [1/3]

void G::GetOpt::addOptionsFromFile | ( | const Path & | file | ) |

Adds options from the given config file.

Throws if the file cannot be opened. Parsing errors are added to errorList().

Definition at line 120 of file ggetopt.cpp.

## ◆ addOptionsFromFile() [2/3]

bool G::GetOpt::addOptionsFromFile | ( | size_t | n,
|  | const StringArray & | extension_blocklist
| ) |  |

Adds options from the config file named by the n'th non-option argument, but not if the file extension matches any in the block list.

Returns false if blocked.

## ◆ addOptionsFromFile() [3/3]

void G::GetOpt::addOptionsFromFile | ( | std::size_t | n = `1U`,
|  | const std::string & | varkey = `{}`,
|  | const std::string & | varvalue = `{}`
| ) |  |

Adds options from the config file named by the n'th non-option command-line argument (zero-based and allowing for the program name in argv0).

The n'th argument is then removed. Does nothing if the n'th argument does not exist or if it is empty. Throws if the file is specified but cannot be opened. Parsing errors are added to errorList(). The optional trailing string parameters are used to perform leading sub-string substitution on the filename.

Definition at line 98 of file ggetopt.cpp.

## ◆ args()

G::Arg G::GetOpt::args | ( |  | ) | const

Returns the G::Arg command-line, excluding options.

Definition at line 176 of file ggetopt.cpp.

## ◆ contains() [1/2]

bool G::GetOpt::contains | ( | char | option_letter | ) | const

Returns true if the command-line contains the option identified by its short-form letter.

Definition at line 145 of file ggetopt.cpp.

## ◆ contains() [2/2]

bool G::GetOpt::contains | ( | std::string_view | option_name | ) | const

Returns true if the command-line contains the option identified by its long-form name.

Definition at line 151 of file ggetopt.cpp.

## ◆ count()

std::size_t G::GetOpt::count | ( | std::string_view | option_name | ) | const

Returns the option's repeat count.

Definition at line 157 of file ggetopt.cpp.

## ◆ errorList()

G::StringArray G::GetOpt::errorList | ( |  | ) | const

Returns the list of errors.

Definition at line 138 of file ggetopt.cpp.

## ◆ hasErrors()

bool G::GetOpt::hasErrors | ( |  | ) | const

Returns true if there are errors.

Definition at line 181 of file ggetopt.cpp.

## ◆ map()

const G::OptionMap & G::GetOpt::map | ( |  | ) | const

Exposes the map of option-values.

Definition at line 131 of file ggetopt.cpp.

## ◆ options()

const std::vector< G::Option > & G::GetOpt::options | ( |  | ) | const

Exposes the list of option specification objects.

Definition at line 125 of file ggetopt.cpp.

## ◆ readOptionsFromFile()

G::StringArray G::GetOpt::readOptionsFromFile | ( | const Path & | filename | ) |
| static

Reads options from file as a list of strings like "--foo=bar".

Throws on error.

Definition at line 115 of file ggetopt.cpp.

## ◆ reload()

void G::GetOpt::reload | ( | const StringArray & | arg,
|  | std::size_t | ignore_non_options = `0U`
| ) |  |

Reinitialises the object with the given command-line arguments.

The program name in the first position is expected but ignored.

Definition at line 66 of file ggetopt.cpp.

## ◆ showErrors() [1/2]

void G::GetOpt::showErrors | ( | std::ostream & | stream | ) | const

An overload which has a sensible prefix.

Definition at line 186 of file ggetopt.cpp.

## ◆ showErrors() [2/2]

void G::GetOpt::showErrors | ( | std::ostream & | stream,
|  | const std::string & | prefix_1,
|  | const std::string & | prefix_2 = `std::string(": ")`
| ) |  | const

A convenience function which streams out each errorList() item to the given stream, prefixed with the given prefix(es).

The two prefixes are simply concatenated.

Definition at line 191 of file ggetopt.cpp.

## ◆ value() [1/2]

std::string G::GetOpt::value | ( | char | option_letter,
|  | std::string_view | default_ = `{}`
| ) |  | const

An overload that returns the value of the option identified by its short-form letter.

Precondition: contains(option_letter)

Definition at line 164 of file ggetopt.cpp.

## ◆ value() [2/2]

std::string G::GetOpt::value | ( | std::string_view | option_name,
|  | std::string_view | default_ = `{}`
| ) |  | const

Returns the value for the option identified by its long-form name.

If the option is multi-valued then the returned value is a comma-separated list. If the option-value is 'on' then Str::positive() is returned; if the option-value is 'off' then the given default is returned.

Definition at line 171 of file ggetopt.cpp.

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

- /tmp/slackdce/slackrepo.HKsbdz/build_emailrelay/emailrelay-2.6/src/glib/ggetopt.h
- /tmp/slackdce/slackrepo.HKsbdz/build_emailrelay/emailrelay-2.6/src/glib/ggetopt.cpp