FEAT::SimpleArgParser Class Reference

Simple argument parser implementation. More...

#include <simple_arg_parser.hpp>

Public Member Functions
	SimpleArgParser (int argc, const char *const *const argv)
	Constructor. More...
int	check (const String &option) const
	Checks whether an option was given. More...
String	get_arg (int i) const
	Returns an argument. More...
String	get_supported_help (bool double_newline=true) const
	Returns a string of all supported options and their help strings. More...
int	num_args () const
	Returns the total number of arguments passed in the constructor. More...
int	num_skipped_args () const
	Returns the number of arguments skipped by the parser. More...
template<typename... Prms_>
int	parse (const String &option, Prms_ &&... prms) const
	Parses the parameters of an option. More...
template<typename T_ >
T_	parse_default (const String &option, T_ default_value) const
	Parses a single parameter of an option and returns it or, if not given, a default value. More...
const std::pair< int, std::deque< String > > *	query (const String &option) const
	Query the parameters of an option. More...
std::deque< std::pair< int, String > >	query_unsupported () const
	Queries all unsupported options passed in the command line. More...
std::deque< String >	skipped_args () const
	Returns a deque of all arguments skipped by the parser. More...
void	support (const String &option, const String &description=String())
	Adds an option to the set of supported options. More...

Private Attributes
std::deque< String >	_args
	command line arguments More...
int	_num_skipped_args
	number of skipped arguments More...
std::map< String, std::pair< int, std::deque< String > > >	_opts
	option-parameter map More...
std::map< String, String >	_supported
	supported option set More...

Detailed Description

Simple argument parser implementation.

This class implements a simple parser for command line arguments.

The parser interprets the command line arguments according to the following rules:

• Any command line argument starting with -- (double hyphen) is interpreted as an option.
• Any command line argument not starting with -- is interpreted as a parameter for the last option preceding the parameter.
• Any command line argument preceding the very first option is ignored by the parser.

Example:
The command line call

   my_app foobar --quiet --level 4 --precon spai jacobi

has a total of 8 arguments:

• 0: "my_app": The name of the application's binary.
• 1: "foobar": An argument ignored by the parser (as there is no option preceding it).
• 2: "--quiet": The first option named quiet without any parameters.
• 3: "--level": The second option named level with one parameter following.
• 4: "4": The first and only parameter for the preceding option level.
• 5: "--precon": The second option precon with two parameters following.
• 6: "spai": The first parameter for the preceding option precon.
• 7: "jacobi": The second parameter for the preceding option precon.

Assume that the application's main function creates an SimpleArgParser object by

int main(int argc, char* argv[])
{
  SimpleArgParser args(argc, argv);
  ...
}

The first step, which is highly recommended, is to add all option names, which are supported by your application, to the argument parser by using the support() function:

args.support("level");
args.support("precon");
args.support("quiet");

Afterwards, you can call the query_unsupported() function to get a list of all options, which were given in the command line arguments but were not marked as supported. Note that for the parser, it is not an error if unsupported options were given - you have to take care of the error handling by yourself. An appropriate error handling code could look like this:

std::deque<std::pair<int,String> > unsupported = args.query_unsupported();
if( !unsupported.empty() )
{
  // print all unsupported options to cerr
  for(auto it = unsupported.begin(); it != unsupported.end(); ++it)
    std::cerr << "ERROR: unsupported option '--" << (*it).second << "'\n";
 
  // abort program execution here, if you want to
}

Moreover, one may use the check() member function to check whether an option was given or not.

• The call args.check("solver") will return -1, indicating the option solver was not given in the command line.
• The call args.check("quiet") will return 0, indicating that the option quiet was given with no parameters.
• The call args.check("level") will return 1, indicating that the option level was given with one additional parameter.
• The call args.check("precon") will return 2, indicating that the option precon was given with two additional parameters.

Furthermore, the parse() member function can be used to parse the parameters of a particular option. For instance, the level parameter of the example above can be queried by

int level(0);
args.parse("level", level);

The parse() function will return the value 1 indicating that the option level exists and that 1 parameter was parsed successfully.

For the above example, the parse call in

int quietness(0);
args.parse("quiet", quietness);

will return 0 indicating that the quiet option does not have any parsable parameters.

Moreover, the parse call in

int precon(0);
args.parse("precon", precon);

will return -6, indicating that the 6th command line argument "spai" could not be parsed as an int.

Furthermore, the parse() function contains special handling for StringMapped parameters, i.e. in the example above, one may use the following code to parse the precon parameters to corresponding enumeration values.

enum class Precon
{
  none,
  spai,
  jacobi
};
std::map<String, Precon> precon_map;
precon_map.insert(std::make_pair("none", Precon::none));
precon_map.insert(std::make_pair("spai", Precon::spai));
precon_map.insert(std::make_pair("jacobi", Precon::jacobi));
 
Precon precon1(Precon::none), precon2(Precon::none);
args.parse("precon", string_mapped(precon1, precon_map), string_mapped(precon2, precon_map));

The above parse call will return the value 2 indicating that both parameters were parsed successfully and it will hold that precon1 = Precon::spai and precon2 = Precon::jacobi.

Finally, this class contains a member function named query(), which retrieves the argument index a particular option and the deque of all parameters for this option. This member function can be used for parsing custom and more complex parameter sets, which can not be covered by the parse() function.

Author

Peter Zajac

Definition at line 139 of file simple_arg_parser.hpp.

Constructor & Destructor Documentation

SimpleArgParser()

FEAT::SimpleArgParser::SimpleArgParser ( int  argc, const char *const *const  argv  )

inlineexplicit

Constructor.

Parameters

[in]	argc	The number of arguments passed to the application.
[in]	argv	The array of all command line arguments passed to the application.

Definition at line 161 of file simple_arg_parser.hpp.

References _args.

Member Function Documentation

check()

int FEAT::SimpleArgParser::check ( const String &  option ) const

inline

Checks whether an option was given.

Parameters

[in]

option

The name of the option (without the leading --) that is to be checked for.

Returns

A value n >= 0 specifying the number of parameters of the option if the option was given, or -1 if the option was not given at all.

Definition at line 329 of file simple_arg_parser.hpp.

References _opts.

get_arg()

String FEAT::SimpleArgParser::get_arg ( int  i ) const

inline

Returns an argument.

Parameters

[in]

i

The index of the argument that is to be returned.

Returns

The i-th argument passed to the constructor or an empty string if i is out-of-bounds.

Definition at line 200 of file simple_arg_parser.hpp.

References _args.

get_supported_help()

String FEAT::SimpleArgParser::get_supported_help ( bool  double_newline = true ) const

inline

Returns a string of all supported options and their help strings.

This function returns a new-line separated string of all options and their descriptions, which have been added to the parser using the support() function.

Each option is listed in the form

--option description

Recommendations:

• If your option has no parameters, your description string should begin with a new-line character, so that the description starts in the next line.
• Parameters should be enclosed in angle-brackets and their names should be referenced in the description, e.g. choosing option="level" and description="\<n\>\nSets the refinement level to \<n\>\n" leads to the output

    --level <n>
    Sets the refinement level to <n>.

Parameters

[in]

double_newline

Inserts double-newline instead of single newline at the end of each argument.

Definition at line 268 of file simple_arg_parser.hpp.

References _supported.

num_args()

int FEAT::SimpleArgParser::num_args ( ) const

inline

Returns the total number of arguments passed in the constructor.

Returns

The number of arguments passed in the constructor, including the command name (first argument).

Definition at line 176 of file simple_arg_parser.hpp.

References _args.

num_skipped_args()

int FEAT::SimpleArgParser::num_skipped_args ( ) const

inline

Returns the number of arguments skipped by the parser.

Returns

The number of skipped arguments.

Definition at line 186 of file simple_arg_parser.hpp.

References _num_skipped_args.

parse()

template<typename... Prms_>

int FEAT::SimpleArgParser::parse ( const String &  option, Prms_ &&...  prms  ) const

inline

Parses the parameters of an option.

This function uses the String::parse() member function to parse the parameter values. This function also contains special handling for StringMapped objects, which allows to parse enumeration values directly.

Parameters

[in]	option	The name of the option (without the leading --) that is to be queried.
[in,out]	prms	A list of references to the objects that shall be parsed as parameters.

Returns

• 0, if the option was not given at all or if it was given, but without any parameters.
• n > 0, if the option was given and n parameters were parsed successfully.
• n < 0, if the option was given, but the n-th command line argument could not be parsed as a parameter. The faulty argument can be accessed by get_arg(n) for error handling.

Definition at line 384 of file simple_arg_parser.hpp.

References _opts.

Referenced by FEAT::Control::Domain::PartiDomainControlBase< DomainLevel_ >::parse_args(), and parse_default().

parse_default()

template<typename T_ >

T_ FEAT::SimpleArgParser::parse_default ( const String &  option, T_  default_value  ) const

inline

Parses a single parameter of an option and returns it or, if not given, a default value.

Parameters

[in]	option	The name of the option (without the leading --) that is to be queried.
[in]	default_value	A default value that is to be returned if the parameter parsing failed or the option was not given.

Returns

The parsed option parameter or the default_value if parsing failed or the option was not given.

Definition at line 408 of file simple_arg_parser.hpp.

References parse().

query()

const std::pair< int, std::deque< String > > * FEAT::SimpleArgParser::query ( const String &  option ) const

inline

Query the parameters of an option.

This function checks whether an option was given and returns a pointer to a pair whose first member is the index of the command line argument identifying this option and the second member is a deque of Strings representing the parameters of this option.

Parameters

[in]

option

The name of the option (without the leading --) that is to be checked for.

Returns

A const pointer to the pair of argument index and parameter deque or nullptr, if the option was not given.

Note

The returned pointer (if not null) points to an internal buffer of the SimpleArgParser and therefore the returned object must not be deleted by the caller.

Definition at line 356 of file simple_arg_parser.hpp.

References _opts.

Referenced by FEAT::Control::Domain::PartiDomainControlBase< DomainLevel_ >::parse_args(), and FEAT::Control::Domain::PartiDomainControl< DomainLevel_ >::parse_args().

query_unsupported()

std::deque< std::pair< int, String > > FEAT::SimpleArgParser::query_unsupported ( ) const

inline

Queries all unsupported options passed in the command line.

This function loops over all options, which were given in the command line, and checks whether they have been added to the list of supported options by using the support() function.

Returns

A deque of int-String pairs representing all unsupported options. The first (int) component is the index of the argument in the command line, whereas the second (String) component is the name of the unsupported option.

Definition at line 292 of file simple_arg_parser.hpp.

References _opts, _supported, and FEAT::String::starts_with().

skipped_args()

std::deque< String > FEAT::SimpleArgParser::skipped_args ( ) const

inline

Returns a deque of all arguments skipped by the parser.

Definition at line 210 of file simple_arg_parser.hpp.

References _args, and _num_skipped_args.

support()

void FEAT::SimpleArgParser::support ( const String &  option, const String &  description = String()  )

inline

Adds an option to the set of supported options.

This function adds an option name to the set of supported options, which is used by the query_unsupported() function.

Parameters

[in]	option	The name of the option that is to be added.
[in]	description	A descriptive string that describes the meaning of the option and its parameters. This is used for the generation of a commented option list; see the documentation of the get_supported_help() function for details and remarks about this help string.

Note

This function has no effect on the check(), query() and parse() functions, i.e. you can use these functions to query options independently of whether they have been added to the set of supported options or not.

Definition at line 237 of file simple_arg_parser.hpp.

References _supported.

Referenced by FEAT::Control::Domain::add_supported_pdc_args().

Member Data Documentation

_args

std::deque<String> FEAT::SimpleArgParser::_args

private

command line arguments

Definition at line 145 of file simple_arg_parser.hpp.

Referenced by SimpleArgParser(), get_arg(), num_args(), and skipped_args().

_num_skipped_args

int FEAT::SimpleArgParser::_num_skipped_args

private

number of skipped arguments

Definition at line 143 of file simple_arg_parser.hpp.

Referenced by num_skipped_args(), and skipped_args().

_opts

std::map<String, std::pair<int, std::deque<String> > > FEAT::SimpleArgParser::_opts

private

option-parameter map

Definition at line 147 of file simple_arg_parser.hpp.

Referenced by check(), parse(), query(), and query_unsupported().

_supported

std::map<String, String> FEAT::SimpleArgParser::_supported

private

supported option set

Definition at line 149 of file simple_arg_parser.hpp.

Referenced by get_supported_help(), query_unsupported(), and support().

---

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

• kernel/util/simple_arg_parser.hpp