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

A parser for command-line arguments that operates according to an Options specification and returns an OptionValue multimap. More...

#include <goptionparser.h>

Public Member Functions

 OptionParser (const Options &spec, OptionMap &values_out, StringArray &errors_out)
 Constructor. More...
 
 OptionParser (const Options &spec, OptionMap &values_out, StringArray *errors_out=nullptr)
 Constructor overload taking an optional errors-out parameter. More...
 
StringArray parse (const StringArray &args_in, std::size_t start_position=1U, std::size_t ignore_non_options=0U, std::function< std::string(const std::string &, bool)> callback_fn={})
 Parses the given command-line arguments into the value map and/or error list defined by the constructor. More...
 
void errorDuplicate (const std::string &)
 Adds a 'duplicate' error in the constructor's error list for the given option. More...
 
 OptionParser (const OptionParser &)=delete
 
 OptionParser (OptionParser &&)=delete
 
OptionParseroperator= (const OptionParser &)=delete
 
OptionParseroperator= (OptionParser &&)=delete
 

Static Public Member Functions

static StringArray parse (const StringArray &args_in, const Options &spec, OptionMap &values_out, StringArray *errors_out=nullptr, std::size_t start_position=1U, std::size_t ignore_non_options=0U, std::function< std::string(const std::string &, bool)> callback_fn={})
 A static function to contruct an OptionParser object and call its parse() method. More...
 

Detailed Description

A parser for command-line arguments that operates according to an Options specification and returns an OptionValue multimap.

See also
G::Options, G::OptionValue

Definition at line 43 of file goptionparser.h.

Constructor & Destructor Documentation

◆ OptionParser() [1/2]

G::OptionParser::OptionParser ( const Options spec,
OptionMap values_out,
StringArray errors_out 
)

Constructor.

All references are kept (including the const reference). The output map is a multimap, but with methods that also allow it to be used as a simple map with multi-valued options concatenated into a comma-separated list.

Definition at line 33 of file goptionparser.cpp.

◆ OptionParser() [2/2]

G::OptionParser::OptionParser ( const Options spec,
OptionMap values_out,
StringArray errors_out = nullptr 
)

Constructor overload taking an optional errors-out parameter.

Definition at line 41 of file goptionparser.cpp.

Member Function Documentation

◆ errorDuplicate()

void G::OptionParser::errorDuplicate ( const std::string &  name)

Adds a 'duplicate' error in the constructor's error list for the given option.

Definition at line 258 of file goptionparser.cpp.

◆ parse() [1/2]

G::StringArray G::OptionParser::parse ( const StringArray args_in,
const Options spec,
OptionMap values_out,
StringArray errors_out = nullptr,
std::size_t  start_position = 1U,
std::size_t  ignore_non_options = 0U,
std::function< std::string(const std::string &, bool)>  callback_fn = {} 
)
static

A static function to contruct an OptionParser object and call its parse() method.

Returns the residual non-option arguments. Throws on error.

Definition at line 48 of file goptionparser.cpp.

◆ parse() [2/2]

G::StringArray G::OptionParser::parse ( const StringArray args_in,
std::size_t  start_position = 1U,
std::size_t  ignore_non_options = 0U,
std::function< std::string(const std::string &, bool)>  callback_fn = {} 
)

Parses the given command-line arguments into the value map and/or error list defined by the constructor.

This can be called more than once, with options accumulating in the internal OptionMap.

By default the program name is expected to be the first item in the array and it is ignored, although the 'start-position' parameter can be used to change this. See also G::Arg::array().

Parsing stops at the first non-option or at "--" and the remaining non-options are returned. Optionally some number of non-options are tolerated without stopping the parsing if 'ignore_non_options' is non-zero. This is to allow for sub-commands like "exe subcmd --opt arg".

Individual arguments can be in short-form like "-c", or long-form like "--foo" or "--foo=bar". Long-form arguments can be passed in two separate arguments, eg. "--foo" followed by "bar". Short-form options can be grouped (eg. "-abc"). Boolean options can be enabled by (eg.) "--verbose" or "--verbose=yes", and disabled by "--verbose=no". Boolean options cannot use two separate arguments (eg. "--verbose" followed by "yes").

Entries in the output map are keyed by the option's long name, even if supplied in short-form.

Errors are appended to the caller's error list.

The optional callback function can be used to modify the parsing of each option. For a double-dash option the callback is passed the string after the double-dash (with false) and it should return the option name to be used for parsing, with an optional leading '-' character to indicate that the parsing results should be discarded. For single-dash options the option letter is looked up in the Options spec first and the long name is passed to the callback (with true).

Returns the non-option arguments.

Definition at line 56 of file goptionparser.cpp.


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