parsers.hpp¶

See Public API for a list of names and headers that are part of the public HPX API.

namespace hpx

namespace program_options

Typedefs

using parsed_options = basic_parsed_options<char>¶

using wparsed_options = basic_parsed_options<wchar_t>¶

using ext_parser = std::function<std::pair<std::string, std::string>(const std::string&)>¶: Augments basic_parsed_options<wchar_t> with conversion from ‘parsed_options’

using command_line_parser = basic_command_line_parser<char>¶

using wcommand_line_parser = basic_command_line_parser<wchar_t>¶

Enums

enum collect_unrecognized_mode¶

Controls if the ‘collect_unregistered’ function should include positional options, or not.

Values:

include_positional¶

exclude_positional¶

Functions

template<class Char> basic_parsed_options<Char> parse_command_line(int argc, const Char *const argv[], const options_description&, int style = 0, std::function<std::pair<std::string, std::string>(const std::string&)> ext = ext_parser())¶: Creates instance of ‘command_line_parser’, passes parameters to it, and returns the result of calling the ‘run’ method.

template<class Char> basic_parsed_options<Char> parse_config_file(std::basic_istream<Char>&, const options_description&, bool allow_unregistered = false)¶

Parse a config file.

Read from given stream.

template<class Char = char> basic_parsed_options<Char> parse_config_file(const char *filename, const options_description&, bool allow_unregistered = false)¶

Parse a config file.

Read from file with the given name. The character type is passed to the file stream.

template<class Char> std::vector<std::basic_string<Char>> collect_unrecognized(const std::vector<basic_option<Char>> &options, enum collect_unrecognized_mode mode)¶: Collects the original tokens for all named options with ‘unregistered’ flag set. If ‘mode’ is ‘include_positional’ also collects all positional options. Returns the vector of original tokens for all collected options.

parsed_options parse_environment(const options_description&, const std::function<std::string(std::string)> &name_mapper)¶

Parse environment.

For each environment variable, the ‘name_mapper’ function is called to obtain the option name. If it returns empty string, the variable is ignored.

This is done since naming of environment variables is typically different from the naming of command line options.

parsed_options parse_environment(const options_description&, const std::string &prefix)¶

Parse environment.

Takes all environment variables which start with ‘prefix’. The option name is obtained from variable name by removing the prefix and converting the remaining string into lower case.

parsed_options parse_environment(const options_description&, const char *prefix)¶: This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. This function exists to resolve ambiguity between the two above functions when second argument is of ‘char*’ type. There’s implicit conversion to both std::function and string.

std::vector<std::string> split_unix(const std::string &cmdline, const std::string &separator = " \t", const std::string &quote = "'\"", const std::string &escape = "\\")¶: Splits a given string to a collection of single strings which can be passed to command_line_parser. The second parameter is used to specify a collection of possible separator chars used for splitting. The separator is defaulted to space ” “. Splitting is done in a unix style way, with respect to quotes ‘”’ and escape characters ‘'

std::vector<std::wstring> hpx::program_options::split_unix(const std::wstring & cmdline, const std::wstring & separator = L" \t", const std::wstring & quote = L"'\"", const std::wstring & escape = L"\\"): This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<class Char> class basic_command_line_parser : private cmdline¶

#include <parsers.hpp>

Command line parser.

The class allows one to specify all the information needed for parsing and to parse the command line. It is primarily needed to emulate named function parameters – a regular function with 5 parameters will be hard to use and creating overloads with a smaller number of parameters will be confusing.

For the most common case, the function parse_command_line is a better alternative.

There are two typedefs – command_line_parser and wcommand_line_parser, for charT == char and charT == wchar_t cases.

Public Functions

basic_command_line_parser(const std::vector<std::basic_string<Char>> &args)¶: Creates a command line parser for the specified arguments list. The ‘args’ parameter should not include program name.

basic_command_line_parser(int argc, const Char *const argv[])¶: Creates a command line parser for the specified arguments list. The parameters should be the same as passed to ‘main’.

basic_command_line_parser &options(const options_description &desc)¶: Sets options descriptions to use.

basic_command_line_parser &positional(const positional_options_description &desc)¶: Sets positional options description to use.

basic_command_line_parser &style(int)¶: Sets the command line style.

basic_command_line_parser &extra_parser(ext_parser)¶: Sets the extra parsers.

basic_parsed_options<Char> run()¶: Parses the options and returns the result of parsing. Throws on error.

basic_command_line_parser &allow_unregistered()¶: Specifies that unregistered options are allowed and should be passed though. For each command like token that looks like an option but does not contain a recognized name, an instance of basic_option<charT> will be added to result, with ‘unrecognized’ field set to ‘true’. It’s possible to collect all unrecognized options with the ‘collect_unrecognized’ function.

basic_command_line_parser &extra_style_parser(style_parser s)¶

Private Members

const options_description *m_desc¶

template<class Char> class basic_parsed_options¶

#include <parsers.hpp>

Results of parsing an input source. The primary use of this class is passing information from parsers component to value storage component. This class does not makes much sense itself.

Public Functions

basic_parsed_options(const options_description *xdescription, int options_prefix = 0)¶

Public Members

std::vector<basic_option<Char>> options¶: Options found in the source.

const options_description *description¶: Options description that was used for parsing. Parsers should return pointer to the instance of option_description passed to them, and issues of lifetime are up to the caller. Can be NULL.

int m_options_prefix¶: Mainly used for the diagnostic messages in exceptions. The canonical option prefix for the parser which generated these results, depending on the settings for basic_command_line_parser::style() or cmdline::style(). In order of precedence of command_line_style enums: allow_long allow_long_disguise allow_dash_for_short allow_slash_for_short

template<> class basic_parsed_options<wchar_t>¶

#include <parsers.hpp>

Specialization of basic_parsed_options which:

provides convenient conversion from basic_parsed_options<char>
stores the passed char-based options for later use.

Public Functions

basic_parsed_options(const basic_parsed_options<char> &po)¶: Constructs wrapped options from options in UTF8 encoding.

Public Members

std::vector<basic_option<wchar_t>> options

const options_description *description

basic_parsed_options<char> utf8_encoded_options¶: Stores UTF8 encoded options that were passed to constructor, to avoid reverse conversion in some cases.

int m_options_prefix: Mainly used for the diagnostic messages in exceptions. The canonical option prefix for the parser which generated these results, depending on the settings for basic_command_line_parser::style() or cmdline::style(). In order of precedence of command_line_style enums: allow_long allow_long_disguise allow_dash_for_short allow_slash_for_short