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 OptionMapmap () 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") ) ;
A class which holds a represention of the argc/argv command line array, and supports simple command-l...
Definition: garg.h:50
A command-line option parser.
Definition: ggetopt.h:59
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: