Argument parser base class. More...

#include <arg_parser.hpp>

Public Member Functions
String	display ()
	Produce formatted output of all values in this parser. More...

const std::deque< String > &	errors () const

String	help_text ()
	Generate help text for this parser. More...

bool	parse (const PropertyMap &property_map)
	Populate this parser. More...

bool	parse (const String &property_map_path)
	Populate this parser. More...

bool	parse (int argc, const char const argv, const PropertyMap *property_map=nullptr)
	Populate this parser. More...

bool	parse (int argc, const char const argv, const String &property_map_path)
	Populate this parser. More...

void	set_description (String &&description)
	Set program description. More...

Protected Member Functions
template<typename T_ >
ParameterBuilder< T_ >	parameter (T_ &&default_value=T_{})
	Add a Parameter to this parser. More...

Private Member Functions
bool	_check_for_unique_parameters ()

void	_collect_args (int argc, const char const argv)

void	_collect_env ()

void	_collect_property_map (const PropertyMap *property_map)

void	_validate ()
	Validate parameters after parsing. More...

Static Private Member Functions
static bool	is_flag (const String &s)

static void	parameter_help (const Intern::ParameterCore &core, std::stringstream &s)
	Write flags, property path, environment variable and help text for given parameter to stringstream. More...

Private Attributes
String	_description {""}

std::deque< String >	_errors

std::deque< std::shared_ptr< Intern::ParameterCore > >	_parameters

String	_program {""}

Static Private Attributes
static constexpr int	priority_cli = 3

static constexpr int	priority_default = 0

static constexpr int	priority_env = 1

static constexpr int	priority_property = 2

Detailed Description

Argument parser base class.

This class aims to be a more convenient alternative to the SimpleArgParser. It allows defining fully integrated argument parsers that can:

parse arguments from the command line, property maps, and environment variables
store parsed arguments directly into a convenient struct
generate a help text
handle required and optional parameters
handle custom parsing
handle validation of arguments
model dependencies between parameters.

Example

// Define parser
struct ExampleParser : public ArgParser
{
  Parameter<String> mesh_path = parameter(String("mesh.xml")).short_flag("-m").long_flag("--mesh").required();
 
  Parameter<bool> write_vtk = parameter(false).long_flag("--vtk");
  Parameter<String> output_file = parameter(String("output.vtu")).long_flag("--output-file").needs(write_vtk);
 
  Parameter<std::uint32_t> max_iters = parameter(std::uint32_t(0)).long_flag("--max-iters").property("max-iters");
  Parameter<String> solver = parameter(String("Umfpack"))
                               .long_flag("--solver")
                               .property("solver")
                               .validator([](const auto& s) { return s == "Umfpack" || s == "CG"; })
                               .needs_if(max_iters, [](const auto& s) { return s == "CG"; });
}
 
// Use like this
ExampleParser args;
bool success = args.parse(argc, argv, property_map);
 
if(!success)
{
  for(const String& error : parser.errors())
  {
    std::cout << error << "\n";
  }
  Runtime::abort();
}
 
if(*args.write_vtk)
{
  // Export VTK
}

Creating a parser

You create a parser by defining a class or struct that inherits from this base class. Inheriting from this class makes a protected method ArgParser::parameter available to you that allows you to define Parameters via a ParameterBuilder. See the various methods of the ParameterBuilder for details on the different settings you can use to define your parser.

Using a parser

After you have defined your parser, you can use it by simply creating an instance of it and calling the parse method. The parse method returns a boolean indicating whether the parameter parsing was successful. If parsing was unsuccessful the parser will contain a list of errors that occured during parsing. Note that for a better user experience the parser is optimistic and will try to produce as many errors as possible rather than quitting after the first warning.

After successfull parsing you can access the parsed values via the Parameter::value() method or the overloads of operator* and operator-> on the Parameter class.

The parser supports being reused. If you call parse again with different parameters, then the parsed result will be identical to calling parse on a fresh parser.

Parsing priority

The parser considers, if provided, command line arguments, property map entries, environment variables, and the supplied default values of parameters. During parsing the priority for sources is as follows:

Default Values < environment variables < property maps < command line arguments

Roughly, the more explicit and interactive the method, to higher the prioritiy. This means that setting a parameter via the command line will overide a value for that parameter set in a property map.

Allowed types

The ArgParser supports all types that can be parsed via the String::parse method. To add support for your own custom type, either supply an operator>> overload for your type, which will be used by String::parse or supply a custom parser in the parameter definition.

Boolean parameters are handled specially. Environment variables and properties are parsed as normal, but setting the command line flag sets the parameters value to the inverse of the default value. This allows you to define "--no-foo" flags that are on by default and get turned off by setting the flag.

If a type T can be parsed, then the Parser also supports Parameters of type std::deque<T>. These parameters are parsed by either splitting the value of a environment variable or property map index at whitespace and parsing each value individually, or by parsing all following command line arguments until the next flag occurs.

Help Text

You can create a help text with a list of all parameters with their flags, property map paths, and environment variables via the ArgParser::help method. The ParameterBuilder provides various settings to customize this help text for each parameter.

Display Text

You can create a table containing the values of all parameters and their respective sources via the ArgParser::display method.

Errors

In the interest of correctness the parser treats most unexpected things as errors. This includes:

unused command line arguments
failed calls to String::parse
unset required parameters
failed validators
unfulfilled dependencies between parameters

Definition at line 833 of file arg_parser.hpp.

Member Function Documentation

◆ _check_for_unique_parameters()

bool FEAT::ArgParser::_check_for_unique_parameters ( )

inlineprivate

Search for short flags, long flags, environment variables, or property paths that get used by multiple parameters

Definition at line 1075 of file arg_parser.hpp.

Referenced by parse().

◆ _collect_args()

void FEAT::ArgParser::_collect_args	(	int	argc,
		const char const	argv
	)

inlineprivate

Definition at line 1138 of file arg_parser.hpp.

◆ _collect_env()

void FEAT::ArgParser::_collect_env ( )

inlineprivate

Definition at line 1113 of file arg_parser.hpp.

◆ _collect_property_map()

void FEAT::ArgParser::_collect_property_map ( const PropertyMap * property_map )

inlineprivate

Definition at line 1126 of file arg_parser.hpp.

◆ _validate()

void FEAT::ArgParser::_validate ( )

inlineprivate

Validate parameters after parsing.

Definition at line 1211 of file arg_parser.hpp.

Referenced by parse().

◆ display()

String FEAT::ArgParser::display ( )

inline

Produce formatted output of all values in this parser.

Returns: A string containing the values of all parameters

Note: This function shows the arguments given by the user. Parser might change these values however they like.

Definition at line 905 of file arg_parser.hpp.

References FEAT::String::pad_back(), and XASSERT.

◆ errors()

const std::deque< String > & FEAT::ArgParser::errors ( ) const

inline

Definition at line 848 of file arg_parser.hpp.

◆ help_text()

String FEAT::ArgParser::help_text ( )

inline

Generate help text for this parser.

Returns: A string containing the help text for this parser

The help text gives information about all parameters supported by this parser

Definition at line 872 of file arg_parser.hpp.

References parameter_help().

◆ is_flag()

static bool FEAT::ArgParser::is_flag ( const String & s )

inlinestaticprivate

Definition at line 1313 of file arg_parser.hpp.

◆ parameter()

template<typename T_ >

ParameterBuilder< T_ > FEAT::ArgParser::parameter ( T_ && default_value = T_{} )

inlineprotected

Add a Parameter to this parser.

Parameters

[in] default_value Default value for this parameter

Returns: A ParameterBuilder for the new Parameter

Definition at line 1058 of file arg_parser.hpp.

◆ parameter_help()

static void FEAT::ArgParser::parameter_help	(	const Intern::ParameterCore &	core,
		std::stringstream &	s
	)

inlinestaticprivate

Write flags, property path, environment variable and help text for given parameter to stringstream.

Definition at line 1220 of file arg_parser.hpp.

References FEAT::String::split_by_charset(), and FEAT::value.

Referenced by help_text().

◆ parse() [1/4]

bool FEAT::ArgParser::parse ( const PropertyMap & property_map )

inline

Populate this parser.

Parameters

[in] property_map Reference to property map root

Collect all parameters from the environment and given property map.

Definition at line 1012 of file arg_parser.hpp.

References parse().

◆ parse() [2/4]

bool FEAT::ArgParser::parse ( const String & property_map_path )

inline

Populate this parser.

Parameters

[in] property_map_path Path to file containing property map

Collect all parameters from the environment and given property map.

Definition at line 1042 of file arg_parser.hpp.

References parse(), and FEAT::PropertyMap::read().

◆ parse() [3/4]

bool FEAT::ArgParser::parse	(	int	argc,
		const char const	argv,
		const PropertyMap *	property_map = `nullptr`
	)

inline

Populate this parser.

Parameters

[in]	argc	Number of command line arguments, as passed to main
[in]	argv	Command line arguments
[in]	property_map	Pointer to property map root

Collect all parameters from the given sources, parse values, validate parser. Note that the parser expects the first command line parameter to be the path to the program binary, as is usual.

Definition at line 966 of file arg_parser.hpp.

References _check_for_unique_parameters(), and _validate().

Referenced by parse().

◆ parse() [4/4]

bool FEAT::ArgParser::parse	(	int	argc,
		const char const	argv,
		const String &	property_map_path
	)

inline

Populate this parser.

Parameters

[in]	argc	Number of command line arguments, as passed to main
[in]	argv	Command line arguments
[in]	property_map_path	Path to file containing property map

Collect all parameters from the given sources, parse values, validate parser. Note that the parser expects the first command line parameter to be the path to the program binary, as is usual.

Definition at line 1028 of file arg_parser.hpp.

References parse(), and FEAT::PropertyMap::read().

◆ set_description()

void FEAT::ArgParser::set_description ( String && description )

inline

Set program description.

Parameters

[in] description Description

This text will be shown before the usage information in the help text.

Definition at line 860 of file arg_parser.hpp.

Member Data Documentation

◆ _description

String FEAT::ArgParser::_description {""}

private

Definition at line 840 of file arg_parser.hpp.

◆ _errors

std::deque<String> FEAT::ArgParser::_errors

private

Definition at line 837 of file arg_parser.hpp.

◆ _parameters

std::deque<std::shared_ptr<Intern::ParameterCore> > FEAT::ArgParser::_parameters

private

Definition at line 836 of file arg_parser.hpp.

◆ _program

String FEAT::ArgParser::_program {""}

private

Definition at line 839 of file arg_parser.hpp.

◆ priority_cli

constexpr int FEAT::ArgParser::priority_cli = 3

staticconstexprprivate

Definition at line 845 of file arg_parser.hpp.

◆ priority_default

constexpr int FEAT::ArgParser::priority_default = 0

staticconstexprprivate

Definition at line 842 of file arg_parser.hpp.

◆ priority_env

constexpr int FEAT::ArgParser::priority_env = 1

staticconstexprprivate

Definition at line 843 of file arg_parser.hpp.

◆ priority_property

constexpr int FEAT::ArgParser::priority_property = 2

staticconstexprprivate

Definition at line 844 of file arg_parser.hpp.

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

kernel/util/arg_parser.hpp

Public Member Functions

Protected Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Member Function Documentation

◆ _check_for_unique_parameters()

◆ _collect_args()

◆ _collect_env()

◆ _collect_property_map()

◆ _validate()

◆ display()

◆ errors()

◆ help_text()

◆ is_flag()

◆ parameter()

◆ parameter_help()

◆ parse() [1/4]

◆ parse() [2/4]

◆ parse() [3/4]

◆ parse() [4/4]

◆ set_description()

Member Data Documentation

◆ _description

◆ _errors

◆ _parameters

◆ _program

◆ priority_cli

◆ priority_default

◆ priority_env

◆ priority_property